架构与系统设计 / 系统课时

通道适配器设计

通道适配器设计

支付平台必须用同一套业务语义接入不同支付机构。本课将建立统一适配器接口、上下文模型与注册机制,使上层交易流程只依赖平台协议,而渠道字段、调用方式和返回码转换都收敛在各自适配器内部。

学习目标

  • 定义稳定的通道适配器接口与输入输出模型
  • 使用注册表按通道编码选择具体实现
  • 明确协议转换、异常归一化与扩展边界

适配器要隔离什么

通道适配器不是简单的 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 名。配置停用、商户权限、币种支持等判断应在路由前完成,避免错误请求进入渠道。

异常与返回码归一化

适配器对外只暴露平台统一异常和结果。网络超时、签名失败、渠道业务拒绝必须区分处理,因为三者的重试策略不同。

  • 网络超时:结果未知,通常转为待查询,不能直接判失败
  • 渠道明确拒绝:映射为稳定的平台错误码,不自动重试
  • 本地参数错误:调用渠道前失败,立即返回并记录校验原因

原始渠道码和响应摘要仍应写入审计日志,但不要泄漏密钥、完整卡号或签名原文。

扩展边界与验收

新增通道时,应只新增适配器、渠道配置和映射测试。若必须修改交易核心流程,通常说明统一接口泄漏了渠道差异。

验收时至少验证:正确适配器被选中、未知通道被拒绝、渠道成功结果能转成统一结果、超时不会被误判为支付失败。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

通道适配器设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通