D13-01开放 API2 分钟更新于 2026-11
开放 API 的四件事要同时成立
一句话
接口设计只是表皮,签名、幂等、回调、限流四件事同时成立,API 才算能用。
开放 API 的四件事要同时成立
一、签名:防篡改 + 防重放
- 签名覆盖:方法、路径、body、时间戳、随机串
- 时间戳窗口:通常几分钟,过期即拒
- 随机串(nonce):服务端缓存去重,防重放
只签名不防重放,等于把请求原样再发一次就能重复扣款。
二、幂等:由调用方给键
- 幂等键由商户生成(订单号),服务端按「商户 + 幂等键」去重
- 重复请求返回相同结果,不是报错
- 幂等窗口要覆盖业务可能的重试周期(通常 24 小时以上)
三、回调:验签、重试、容忍乱序
- 必须验签(否则可被伪造)
- 必须重试(间隔递增,总时长有上限)
- 必须容忍乱序与重复
回调是「通知」,不是「事实来源」——最终状态以主动查询为准。
四、限流与错误码
- 限流按商户/接口维度,返回明确的限流错误码与
Retry-After - 错误码要分「可重试」与「不可重试」,不要都返回 500
- 文档里写清每种错误的处理建议
反例:回调只发一次
某开放平台的支付回调只在成功时发一次,失败不重试。 结果:商户侧网络抖动一次,订单就永远停在「待支付」, 只能靠商户自己定时查单补救——而小商户根本不会做查单。
回调重试是平台的责任,不是接入方的。
沙箱:要能复现异常
好的沙箱能模拟:
- 支付成功 / 失败 / 超时
- 重复回调 / 乱序回调
- 限流与错误码
只能「跑通成功路径」的沙箱,等于没有沙箱。
自查清单
- 签名含时间戳与 nonce 吗,服务端去重吗
- 幂等键由谁生成,重复请求返回一致结果吗
- 回调验签、重试、乱序都处理了吗
- 限流有明确错误码与重试建议吗
- 沙箱能模拟异常路径吗
依据
- 开放 API 的签名/幂等/回调/限流四要素
- 回调与查单的关系,见 掉单与查单补偿
- 相关:适配器契约的五个字段、幂等设计
相关阅读