Go HTTP API 如何设计幂等键：重复提交的语义、存储与过期处理

订单接口上线后，客户端遇到超时通常会重试；如果服务端只把每次 POST 都当成新请求，同一个订单可能被写入两次。幂等键的作用不是让接口“永远只执行一次”，而是让服务端识别同一业务意图，并明确返回原结果、冲突或允许重新发起。

先把幂等键的边界说清楚

幂等键代表的是“一次业务意图”，不是用户、订单号或连接。移动端点击提交后拿到超时，第二次请求应该沿用同一个键；用户修改了收货地址重新提交，则应生成新键。这个区分决定了服务端能否把重试和新操作分开。

接口可以约定客户端通过 Idempotency-Key 发送一个随机值，例如 UUID。服务端将规范化后的请求体、关键路径参数和业务租户一起计算指纹。只比较键而不比较参数，会把误用的旧键误认为安全重放。

调用方需要拿到什么结果

接口目标首先是让调用方可判断。首次请求成功时保存响应状态和业务结果；相同键、相同指纹再次到达时，直接返回原来的状态码和响应体，并可增加 Idempotency-Replayed: true 说明这是重放结果。

如果键相同但指纹不同，不应该覆盖旧记录。用 409 Conflict 告知调用方这个键已经绑定了另一组参数；缺少键或键格式不合规则属于请求错误，可返回 400。正在处理的记录可以返回 409 或 425，关键是客户端能知道应该稍后查询，而不是盲目换键。

type IdempotencyRecord struct {
    Key        string
    Fingerprint string
    Status     string // processing, succeeded, failed
    HTTPStatus int
    Body       []byte
    ExpiresAt  time.Time
}

存储结构要同时防并发和防误用

请求到达时，服务端需要在一个原子操作里完成“占位”或读取已有记录。Redis 可以用带过期时间的 SETNX，关系数据库可以用唯一索引配合事务插入。占位成功的请求才执行真正的下单逻辑，其余请求读取记录状态。

不要把完整响应体无限期放在缓存里。对小型 JSON 可以直接保存；响应较大时保存对象地址和校验摘要，并保证重放期间地址仍可读。对于支付、库存这类副作用，幂等层只能防重复入口，最终写入仍要依赖业务表的唯一约束。

func fingerprint(method, path string, body []byte) string {
    h := sha256.New()
    h.Write([]byte(method + "\n" + path + "\n"))
    h.Write(body)
    return hex.EncodeToString(h.Sum(nil))
}

func sameRequest(old, current string) bool {
    return old != "" && subtle.ConstantTimeCompare([]byte(old), []byte(current)) == 1
}

一次请求的处理顺序

实际实现可以把幂等检查放在业务 handler 外的中间件中，但请求体要先被完整读取并恢复给后续 handler。下面的顺序更容易验收：校验键、计算指纹、原子占位、执行业务、写入结果、返回响应。

1. 读取并校验 Idempotency-Key，限制长度和字符集，拒绝空值。
2. 计算方法、路径、租户和请求体指纹，避免不同资源共用一个键。
3. 尝试创建 processing 记录；已存在则比较指纹和当前状态。
4. 只有占位成功者调用下单服务，并在事务提交后保存最终响应。
5. 业务失败时区分可安全重试的临时失败和已经产生副作用的失败。

第一步和第二步应在日志中留下键的脱敏摘要与指纹前缀，不能记录完整支付参数。第五步尤其重要：如果业务已经扣库存却因为网络错误被标成可重试，下一次请求可能再次扣减。

过期时间不是随手写的数字

过期时间应覆盖客户端重试窗口、消息补偿窗口和人工查询窗口。太短会让同一业务意图在缓存清理后重新执行，太长则会积压存储并阻止用户对确实失败的操作重新发起。常见做法是让订单号或业务唯一键在数据库中长期兜底，缓存只负责挡住短时间并发。

处理中的记录还需要租约或后台回收策略。进程崩溃后，永久的 processing 会让调用方一直得到冲突；租约到期后是否允许接管，必须结合业务是否可能已经提交成功来决定。对支付场景，优先查询支付单状态，再决定重试，不要仅凭缓存超时推断失败。

一个可验收的错误响应契约

建议把错误响应固定成可机器读取的字段，同时保留人能看懂的说明：

{
  "code": "idempotency_key_reused",
  "message": "Idempotency-Key 已绑定另一组请求参数",
  "request_id": "req_7f2..."
}

客户端只依据 code 和 HTTP 状态判断，不要解析 message。服务端验收至少覆盖：两次相同请求只产生一条业务记录；同键改金额返回冲突且旧结果不变；并发请求只有一个进入业务 handler；处理中进程退出后能按业务状态恢复；过期后新键可以正常提交。

容易踩中的几个坑

• 把用户 ID 当幂等键，导致同一用户的两个合法订单互相阻塞。
• 只在应用内存中加锁，部署多个 Go 实例后每台机器都可能执行一次。
• 收到请求就写成功记录，业务事务随后失败，重试会错误地拿到成功响应。
• 把幂等键直接写进日志、链路或指标标签，造成敏感业务参数可被关联。

上线前的判断清单

先确认调用方在网络超时、连接断开和 5xx 时是否复用同一键，再用并发测试观察唯一业务记录。最后检查幂等存储不可用时的降级策略：对支付和扣库存接口宁可快速失败，也不要悄悄绕过检查继续写入。

相关问题

幂等键应该由客户端还是服务端生成？

应由调用方为一次业务意图生成并在重试中复用，服务端负责校验和绑定。服务端临时生成的键无法跨网络重试保持一致。

相同幂等键能否用于不同接口？

可以允许调用方复用随机值，但服务端指纹必须包含 HTTP 方法、资源路径和租户等边界，避免不同操作误读同一条记录。

失败响应要不要缓存？

要按失败类型区分。参数错误通常不应长期占用键；已经产生业务副作用的失败则应保存可查询结果，避免重试再次执行。

把重试变成可控的协议

幂等设计的核心不是多加一张缓存表，而是把调用方的重试意图、服务端的参数指纹、业务事务结果和过期边界连成一个协议。先用唯一约束守住最终业务数据，再用原子占位挡住并发入口，最后让错误码和查询路径告诉调用方下一步怎么做，这样网络抖动才不会变成重复订单。