架构与系统设计 / 系统课时
定义幂等边界与请求去重
定义幂等边界与请求去重
请求重试不可避免,但“同一个 HTTP 方法”并不等于“同一个业务操作”。本节从业务语义定义幂等边界,设计幂等键、请求指纹、去重记录和结果重放,让重复请求既不会重复产生副作用,也不会掩盖参数冲突。
学习目标
- 从业务操作、租户和资源范围定义幂等键的有效边界。
- 设计请求指纹、唯一约束和结果重放记录。
- 区分重复成功、处理中重试和同键不同参数三类请求。
先定义业务幂等边界
幂等语义应绑定“业务命令”,而不是机械地绑定 GET、POST 或 PUT。例如“创建订单”可以通过客户端生成的幂等键做到重复提交只创建一次;而“给余额增加 100 元”即使使用 PUT,如果每次都代表一次新的加款命令,也不能仅靠 HTTP 方法获得业务幂等性。
一个实用的去重作用域通常至少包含租户或用户、操作类型和幂等键,例如 tenant-a:create-order + idem-001。若不同业务操作共用同一个全局键空间,会出现无关请求互相冲突;若作用域过窄,又可能让同一业务命令从不同入口重复执行。
设计去重记录与结果重放
去重记录不应只保存“这个键见过”。至少还要保存请求指纹、处理状态、原始响应状态码和响应体。请求指纹可由规范化后的关键参数计算哈希,用来识别“同一个键却换了参数”的错误复用。
同一幂等键再次到达时,服务端应按记录状态处理:
- 指纹相同且状态为
SUCCEEDED:直接重放第一次的状态码和响应体,不再次执行副作用。 - 指纹相同但状态为
PROCESSING:返回可重试的处理中结果,或引导客户端稍后查询。 - 指纹不同:拒绝请求,常见做法是返回冲突响应,避免把新命令误认为旧命令重试。
如果业务副作用和去重记录位于同一个数据库,应尽量放进同一事务;如果副作用发生在外部系统,则需要事务消息、Outbox 或其他可恢复协议,避免“副作用成功但幂等记录未落库”。
用状态机处理重复与冲突
幂等控制本质上是一个带唯一占位的状态机。首次请求从“无记录”原子地进入 PROCESSING,业务提交成功后进入 SUCCEEDED;重复请求只读取既有状态。这样并发到达的两个相同请求不会同时获得执行资格。

对于失败状态要更谨慎。只有能证明业务副作用没有发生时,才可以把记录释放给下一次重试;如果外部调用结果未知,应保留“结果不确定”状态并进入对账,而不是删除记录后再次执行。
运行一个最小去重示例
下面的 Python 示例只使用标准库和 SQLite。唯一约束负责抢占幂等键;请求指纹防止同键不同参数;订单写入和去重结果在同一事务中提交。
import hashlib
import json
import sqlite3
conn = sqlite3.connect(":memory:")
conn.executescript(
"""
CREATE TABLE idempotency_records (
scope TEXT NOT NULL,
idem_key TEXT NOT NULL,
request_hash TEXT NOT NULL,
status TEXT NOT NULL,
http_status INTEGER,
response_json TEXT,
PRIMARY KEY (scope, idem_key)
);
CREATE TABLE orders (
order_id TEXT PRIMARY KEY,
amount INTEGER NOT NULL
);
"""
)
conn.commit()
def handle_order(scope, idem_key, order_id, amount):
request_json = json.dumps(
{"order_id": order_id, "amount": amount},
sort_keys=True,
separators=(",", ":"),
)
request_hash = hashlib.sha256(request_json.encode()).hexdigest()
try:
conn.execute("BEGIN IMMEDIATE")
claimed = conn.execute(
"""
INSERT OR IGNORE INTO idempotency_records
(scope, idem_key, request_hash, status)
VALUES (?, ?, ?, 'PROCESSING')
""",
(scope, idem_key, request_hash),
)
if claimed.rowcount == 0:
row = conn.execute(
"""
SELECT request_hash, status, http_status, response_json
FROM idempotency_records
WHERE scope = ? AND idem_key = ?
""",
(scope, idem_key),
).fetchone()
conn.commit()
if row[0] != request_hash:
return 409, {"error": "idempotency key reused with different payload"}
if row[1] == "SUCCEEDED":
return row[2], json.loads(row[3])
return 409, {"error": "request is still processing"}
response = {"orderId": order_id, "amount": amount}
conn.execute(
"INSERT INTO orders(order_id, amount) VALUES (?, ?)",
(order_id, amount),
)
conn.execute(
"""
UPDATE idempotency_records
SET status = 'SUCCEEDED',
http_status = 201,
response_json = ?
WHERE scope = ? AND idem_key = ?
""",
(json.dumps(response), scope, idem_key),
)
conn.commit()
return 201, response
except Exception:
conn.rollback()
raise
scope = "tenant-a:create-order"
print(handle_order(scope, "idem-001", "o-1001", 9800))
print(handle_order(scope, "idem-001", "o-1001", 9800))
print(handle_order(scope, "idem-001", "o-1001", 12000))
print("order_count =", conn.execute("SELECT COUNT(*) FROM orders").fetchone()[0])预期输出
(201, {'orderId': 'o-1001', 'amount': 9800})
(201, {'orderId': 'o-1001', 'amount': 9800})
(409, {'error': 'idempotency key reused with different payload'})
order_count = 1第一次请求创建订单并保存响应;第二次没有再次写订单,而是重放第一次结果;第三次虽然复用了同一个幂等键,但参数指纹不同,因此被拒绝。
处理 TTL 与跨系统副作用
幂等记录可以设置 TTL,但保留时间必须覆盖客户端最大重试窗口、消息重投窗口以及可能的离线重试周期。TTL 太短会让旧请求在记录过期后再次产生副作用;TTL 太长则会增加存储成本,需要结合业务风险选择。
不要把去重表当成所有一致性问题的替代品。它只能约束“同一个业务命令不要重复执行”。当命令还要写数据库、发消息或调用支付等外部系统时,仍需保证幂等记录与副作用之间有可恢复的一致性协议。