架构与系统设计 / 系统课时
用幂等键抵御重复请求
用幂等键抵御重复请求
客户端超时后通常会重试,但服务端第一次请求可能已经成功。这里把“重复请求”转成可识别的业务事件:用幂等键定位同一次操作,用请求摘要防止误复用,并把首次结果持久化后直接复用。
学习目标
- 设计稳定的业务幂等键,并区分“同一次重试”和“另一笔新业务”
- 用唯一约束、请求摘要和结果记录实现原子去重
- 识别幂等记录过期、并发写入和跨资源副作用的边界
幂等键要代表一次业务意图
幂等键不是随机请求 ID 的别名,而应稳定地代表“一次业务操作”。例如创建订单可以由客户端生成 checkoutAttemptId,整个重试周期都复用它;若每次重试都重新生成键,服务端仍会把请求当成新操作。
同一个键还应绑定请求摘要。这样当调用方误把旧键用于另一组参数时,服务端可以返回冲突,而不是静默复用旧结果。常见组合是“幂等键 + 请求摘要 + 处理状态 + 响应结果 + 过期时间”。

把去重记录与业务写入放进同一事务
下面用 SQLite 演示最小可运行方案。idempotency_key 是主键;首次请求创建订单并保存响应,后续同键同参数请求直接返回旧结果,同键不同参数返回冲突。
python
import hashlib
import json
import sqlite3
conn = sqlite3.connect(":memory:")
conn.execute(
"CREATE TABLE orders (order_id TEXT PRIMARY KEY, user_id TEXT, amount INTEGER)"
)
conn.execute(
"CREATE TABLE idempotency ("
"idem_key TEXT PRIMARY KEY, request_hash TEXT NOT NULL, "
"status_code INTEGER NOT NULL, response_body TEXT NOT NULL)"
)
def request_hash(payload: dict) -> str:
raw = json.dumps(payload, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(raw.encode()).hexdigest()
def create_order(idem_key: str, payload: dict):
digest = request_hash(payload)
conn.execute("BEGIN IMMEDIATE")
row = conn.execute(
"SELECT request_hash, status_code, response_body "
"FROM idempotency WHERE idem_key = ?",
(idem_key,),
).fetchone()
if row:
conn.commit()
if row[0] != digest:
return 409, "idempotency key reused with different request"
return row[1], row[2]
# 业务写入与幂等结果必须原子提交,避免只成功一边。
conn.execute(
"INSERT INTO orders(order_id, user_id, amount) VALUES (?, ?, ?)",
(payload["orderId"], payload["userId"], payload["amount"]),
)
response = json.dumps({"orderId": payload["orderId"]})
conn.execute(
"INSERT INTO idempotency VALUES (?, ?, ?, ?)",
(idem_key, digest, 201, response),
)
conn.commit()
return 201, response
payload = {"orderId": "ord-1001", "userId": "u-7", "amount": 9900}
print(create_order("pay-attempt-88", payload))
print(create_order("pay-attempt-88", payload))
print(create_order("pay-attempt-88", {**payload, "amount": 10900}))预期输出:
text
(201, '{"orderId": "ord-1001"}')
(201, '{"orderId": "ord-1001"}')
(409, 'idempotency key reused with different request')第一次调用真正产生副作用,第二次只复用已保存结果;第三次证明旧键不能被另一组参数借用。生产数据库中应继续依赖唯一索引解决并发竞争,而不是只靠“先查再写”的应用层判断。
处理过期与跨资源副作用
幂等记录不能无限增长,应按业务重试窗口设置 TTL,但 TTL 不能短于客户端、网关和消息系统的最大重试周期。记录过早删除后,同一个旧请求再次到达就可能重新产生副作用。
如果一次操作同时写本地数据库并调用支付、库存等外部系统,本地事务无法覆盖全部资源。此时仍要让每个外部动作携带稳定业务键,并结合 Outbox、消费端去重或对方提供的幂等接口,使“重试”在链路每一跳都不会重复生效。
验收时至少检查三件事:同键同参数不会新增第二条业务记录;同键不同参数会失败;首次响应即使客户端没收到,重试仍能拿到与首次一致的结果。满足这三点,重试才真正从风险变成可控行为。
按自己的节奏,确认真正理解。