跳到正文
D3-03网关与适配层1 分钟更新于 2026-11

适配器契约的五个字段

一句话

适配器的价值不是「接了多少家」,是「上层不知道接了多少家」。

本文目录7 节

适配器契约的五个字段

契约五要素

要素作用没做好的后果
统一请求上层只传业务字段每接一家改一次上层
统一响应成功/失败/未知三态上层要解析各家的报文
错误码映射渠道错误 → 统一语义无法决定重试策略
幂等键同一笔业务不重复执行重复扣款
能力声明这家支持什么上层写满 if-else

错误码映射是核心

渠道返回的错误码千奇百怪,必须映射成三类:

  • 可重试:网络抖动、系统繁忙
  • 不可重试:卡余额不足、账户冻结
  • 未知:超时、结果不明——必须先查单

只有映射到这三类,上层才能写出统一的补偿逻辑。 直接把渠道码透传上去,等于让每个上层模块都理解一遍渠道。

能力声明怎么写

capabilities: {
  currencies: ["USD", "EUR"],
  methods: ["card", "bank_transfer"],
  partialRefund: true,
  multiCapture: false,
  realtime: true,
  webhook: true
}

上层按能力编排(见 支付编排:多 PSP 的成功率博弈), 而不是按通道名判断。

版本与兼容

适配器会随渠道升级而变化。要求:

  • 契约版本化,破坏性变更要升版本
  • 老版本至少保留一个结算周期(退款可能发生在几个月后)
  • 记录每次调用的契约版本,便于回溯

反例:透传渠道字段

某系统的适配器直接把渠道 JSON 塞进 extra 字段透传给业务层。 结果业务代码里出现了 if (res.extra.txn_status === 'S')——渠道一改字段名,全线报错。

适配器的职责就是把「渠道的差异」翻译成「业务的语义」。透传等于没做适配。

自查清单

  • 上层代码里有渠道名或渠道字段吗
  • 错误码映射到三类了吗
  • 幂等键由谁生成,跨渠道一致吗
  • 能力声明是配置还是硬编码
  • 契约有版本号吗

依据

相关阅读