架构与系统设计 / 系统课时
通道适配器设计
通道适配器设计
支付平台必须用同一套业务语义接入不同支付机构。本课将建立统一适配器接口、上下文模型与注册机制,使上层交易流程只依赖平台协议,而渠道字段、调用方式和返回码转换都收敛在各自适配器内部。
学习目标
- 定义稳定的通道适配器接口与输入输出模型
- 使用注册表按通道编码选择具体实现
- 明确协议转换、异常归一化与扩展边界
适配器要隔离什么
通道适配器不是简单的 HTTP 客户端封装。它需要把平台统一订单转换为渠道请求,把渠道响应转换为平台结果,并统一处理签名、鉴权、错误码、超时和查询语义。
上层交易服务只表达“发起支付”“查询订单”等业务动作,不直接出现渠道字段名。这样新增通道时,只增加适配器实现,不修改订单主流程。

统一接口与结果模型
接口应围绕平台能力设计,而不是照搬某个渠道 SDK。下面示例只实现“创建支付”,但接口结构可以继续扩展查询、关闭和退款能力。
java
import java.math.BigDecimal;
import java.util.HashMap;
import java.util.Map;
public class ChannelAdapterDemo {
public record PayCommand(String channelCode, String orderNo,
BigDecimal amount, String subject) {}
public record ChannelResult(boolean success, String channelOrderNo,
String errorCode, String errorMessage) {
static ChannelResult success(String channelOrderNo) {
return new ChannelResult(true, channelOrderNo, null, null);
}
static ChannelResult failure(String code, String message) {
return new ChannelResult(false, null, code, message);
}
}
public interface ChannelAdapter {
String channelCode();
ChannelResult createPay(PayCommand command);
}
public static final class AlphaPayAdapter implements ChannelAdapter {
public String channelCode() {
return "ALPHA_PAY";
}
public ChannelResult createPay(PayCommand command) {
// 渠道字段组装、签名和远程调用应封装在该实现内部
String channelOrderNo = "A-" + command.orderNo();
return ChannelResult.success(channelOrderNo);
}
}
public static final class ChannelAdapterRegistry {
private final Map<String, ChannelAdapter> adapters = new HashMap<>();
public ChannelAdapterRegistry(ChannelAdapter... adapters) {
for (ChannelAdapter adapter : adapters) {
this.adapters.put(adapter.channelCode(), adapter);
}
}
public ChannelAdapter getRequired(String channelCode) {
ChannelAdapter adapter = adapters.get(channelCode);
if (adapter == null) {
throw new IllegalArgumentException("Unsupported channel: " + channelCode);
}
return adapter;
}
}
public static void main(String[] args) {
ChannelAdapterRegistry registry =
new ChannelAdapterRegistry(new AlphaPayAdapter());
PayCommand command = new PayCommand(
"ALPHA_PAY", "P202608030001",
new BigDecimal("88.50"), "会员充值");
ChannelResult result =
registry.getRequired(command.channelCode()).createPay(command);
System.out.println(result.success());
System.out.println(result.channelOrderNo());
}
}预期输出:
text
true
A-P202608030001注册与路由规则
注册表应在应用启动时完成适配器收集,并确保一个通道编码只对应一个实现。生产项目可由 Spring 注入 List<ChannelAdapter>,再按 channelCode() 构建不可变映射。
通道路由应使用业务配置中的稳定编码,不要依赖 Java 类名或 Bean 名。配置停用、商户权限、币种支持等判断应在路由前完成,避免错误请求进入渠道。
异常与返回码归一化
适配器对外只暴露平台统一异常和结果。网络超时、签名失败、渠道业务拒绝必须区分处理,因为三者的重试策略不同。
- 网络超时:结果未知,通常转为待查询,不能直接判失败
- 渠道明确拒绝:映射为稳定的平台错误码,不自动重试
- 本地参数错误:调用渠道前失败,立即返回并记录校验原因
原始渠道码和响应摘要仍应写入审计日志,但不要泄漏密钥、完整卡号或签名原文。
扩展边界与验收
新增通道时,应只新增适配器、渠道配置和映射测试。若必须修改交易核心流程,通常说明统一接口泄漏了渠道差异。
验收时至少验证:正确适配器被选中、未知通道被拒绝、渠道成功结果能转成统一结果、超时不会被误判为支付失败。
按自己的节奏,确认真正理解。