D13-03开放 API1 分钟更新于 2026-11
接口幂等
一句话
幂等键由调用方给,服务端只负责去重。
接口幂等
它解决什么
开放接口的幂等键由调用方提供,服务端只负责去重与返回首次结果。为什么不能服务端生成?因为客户端重试时拿不到同一个键,就会当成新请求。幂等的实现靠唯一约束,不靠「先查后插」——后者在并发下必然穿透。幂等键的保留期决定了多长的重试窗口内是安全的。
怎么用
- 调用方生成键
- 唯一索引兜底
- 返回首次结果
- 保留期覆盖重试窗口
一个判断
某接口由服务端生成幂等键,客户端超时重试后变成两笔订单,重复扣款。
边界
幂等的边界是「保留期」:键保留 24 小时,意味着超过 24 小时的重试会被当成新请求。
一个反例
某接口由服务端生成幂等键,客户端超时重试后变成两笔订单,重复扣款。现在幂等键由调用方生成,服务端按商户+键去重。
常见误判
- 服务端自己生成幂等键。
自查清单
- 知道这个模块的边界在哪
- 知道它的状态机有哪几个状态
- 知道它出错时的兜底路径
- 知道它的数据存在哪张表
依据
- 开放接口的幂等设计。
相关阅读