D3-03网关与适配层1 分钟更新于 2026-11
适配器契约的五个字段
一句话
适配器的价值不是「接了多少家」,是「上层不知道接了多少家」。
适配器契约的五个字段
契约五要素
| 要素 | 作用 | 没做好的后果 |
|---|---|---|
| 统一请求 | 上层只传业务字段 | 每接一家改一次上层 |
| 统一响应 | 成功/失败/未知三态 | 上层要解析各家的报文 |
| 错误码映射 | 渠道错误 → 统一语义 | 无法决定重试策略 |
| 幂等键 | 同一笔业务不重复执行 | 重复扣款 |
| 能力声明 | 这家支持什么 | 上层写满 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')——渠道一改字段名,全线报错。
适配器的职责就是把「渠道的差异」翻译成「业务的语义」。透传等于没做适配。
自查清单
- 上层代码里有渠道名或渠道字段吗
- 错误码映射到三类了吗
- 幂等键由谁生成,跨渠道一致吗
- 能力声明是配置还是硬编码
- 契约有版本号吗
依据
相关阅读