跳到正文
D13-03开放 API1 分钟更新于 2026-11

接口幂等

一句话

幂等键由调用方给,服务端只负责去重。

本文目录8 节

接口幂等

它解决什么

开放接口的幂等键由调用方提供,服务端只负责去重与返回首次结果。为什么不能服务端生成?因为客户端重试时拿不到同一个键,就会当成新请求。幂等的实现靠唯一约束,不靠「先查后插」——后者在并发下必然穿透。幂等键的保留期决定了多长的重试窗口内是安全的。

怎么用

  • 调用方生成键
  • 唯一索引兜底
  • 返回首次结果
  • 保留期覆盖重试窗口

一个判断

某接口由服务端生成幂等键,客户端超时重试后变成两笔订单,重复扣款。

边界

幂等的边界是「保留期」:键保留 24 小时,意味着超过 24 小时的重试会被当成新请求。

一个反例

某接口由服务端生成幂等键,客户端超时重试后变成两笔订单,重复扣款。现在幂等键由调用方生成,服务端按商户+键去重。

常见误判

  • 服务端自己生成幂等键。

自查清单

  • 知道这个模块的边界在哪
  • 知道它的状态机有哪几个状态
  • 知道它出错时的兜底路径
  • 知道它的数据存在哪张表

依据

  • 开放接口的幂等设计。

相关:开放 API 的四件事要同时成立

相关阅读