架构与系统设计 / 系统课时

用幂等键抵御重复请求

用幂等键抵御重复请求

客户端超时后通常会重试,但服务端第一次请求可能已经成功。这里把“重复请求”转成可识别的业务事件:用幂等键定位同一次操作,用请求摘要防止误复用,并把首次结果持久化后直接复用。

学习目标

  • 设计稳定的业务幂等键,并区分“同一次重试”和“另一笔新业务”
  • 用唯一约束、请求摘要和结果记录实现原子去重
  • 识别幂等记录过期、并发写入和跨资源副作用的边界

幂等键要代表一次业务意图

幂等键不是随机请求 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、消费端去重或对方提供的幂等接口,使“重试”在链路每一跳都不会重复生效。

验收时至少检查三件事:同键同参数不会新增第二条业务记录;同键不同参数会失败;首次响应即使客户端没收到,重试仍能拿到与首次一致的结果。满足这三点,重试才真正从风险变成可控行为。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用幂等键抵御重复请求

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通