跳到正文
D13-01开放 API2 分钟更新于 2026-11

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

一句话

接口设计只是表皮,签名、幂等、回调、限流四件事同时成立,API 才算能用。

本文目录8 节

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

一、签名:防篡改 + 防重放

  • 签名覆盖:方法、路径、body、时间戳、随机串
  • 时间戳窗口:通常几分钟,过期即拒
  • 随机串(nonce):服务端缓存去重,防重放

只签名不防重放,等于把请求原样再发一次就能重复扣款。

二、幂等:由调用方给键

  • 幂等键由商户生成(订单号),服务端按「商户 + 幂等键」去重
  • 重复请求返回相同结果,不是报错
  • 幂等窗口要覆盖业务可能的重试周期(通常 24 小时以上)

三、回调:验签、重试、容忍乱序

  • 必须验签(否则可被伪造)
  • 必须重试(间隔递增,总时长有上限)
  • 必须容忍乱序与重复

回调是「通知」,不是「事实来源」——最终状态以主动查询为准。

四、限流与错误码

  • 限流按商户/接口维度,返回明确的限流错误码与 Retry-After
  • 错误码要分「可重试」与「不可重试」,不要都返回 500
  • 文档里写清每种错误的处理建议

反例:回调只发一次

某开放平台的支付回调只在成功时发一次,失败不重试。 结果:商户侧网络抖动一次,订单就永远停在「待支付」, 只能靠商户自己定时查单补救——而小商户根本不会做查单。

回调重试是平台的责任,不是接入方的。

沙箱:要能复现异常

好的沙箱能模拟:

  • 支付成功 / 失败 / 超时
  • 重复回调 / 乱序回调
  • 限流与错误码

只能「跑通成功路径」的沙箱,等于没有沙箱。

自查清单

  • 签名含时间戳与 nonce 吗,服务端去重吗
  • 幂等键由谁生成,重复请求返回一致结果吗
  • 回调验签、重试、乱序都处理了吗
  • 限流有明确错误码与重试建议吗
  • 沙箱能模拟异常路径吗

依据

相关阅读