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

拆分第三方服务接入边界

拆分第三方服务接入边界

接入支付、短信或地图供应商时,真正难维护的通常不是一次 HTTP 调用,而是供应商字段、鉴权、错误码、重试和访问控制逐渐渗入业务代码。本节用适配器、外观和代理分层隔离这些变化,让业务只依赖稳定边界。

学习目标

  • 区分适配器、外观和代理在第三方接入中的不同职责。
  • 用稳定接口隔离供应商数据模型和调用细节。
  • 把访问控制、日志等横切逻辑放到代理层,并验证替换边界。

先划清三种模式的职责

适配器解决“接口不兼容”:把供应商方法、参数单位和返回状态转换成系统自己的模型。外观解决“调用太复杂”:把一次业务动作需要的多个底层步骤收敛成少量稳定入口。代理解决“访问需要控制”:在不改变目标接口的前提下增加鉴权、限流、审计或延迟创建。

三者可以叠加,但不要互相代替。业务服务应该依赖外观;外观依赖系统定义的网关接口;代理实现同一网关接口并包住适配器;适配器再接触具体供应商 SDK 或 HTTP 客户端。

第三方服务接入的边界分层

用代码把供应商模型挡在边界外

下面的 Java 17 示例用本地类模拟供应商 SDK,不依赖真实网络。业务侧只认识 PaymentGateway 和 PaymentFacade;VendorAdapter 负责把“元”转换为供应商需要的“分”,并把供应商状态映射为系统自己的布尔结果;AccessProxy 在调用前做访问控制。

java
public class ThirdPartyBoundaryDemo {
    interface PaymentGateway {
        boolean charge(String orderId, int amountYuan);
    }

    static final class VendorSdk {
        String pay(String merchantOrderId, int amountCent) {
            return amountCent > 0 ? "SUCCESS" : "INVALID_AMOUNT";
        }
    }

    static final class VendorAdapter implements PaymentGateway {
        private final VendorSdk sdk;

        VendorAdapter(VendorSdk sdk) {
            this.sdk = sdk;
        }

        public boolean charge(String orderId, int amountYuan) {
            int amountCent = Math.multiplyExact(amountYuan, 100);
            String status = sdk.pay(orderId, amountCent);
            return "SUCCESS".equals(status);
        }
    }

    static final class AccessProxy implements PaymentGateway {
        private final PaymentGateway target;
        private final int maxAmountYuan;

        AccessProxy(PaymentGateway target, int maxAmountYuan) {
            this.target = target;
            this.maxAmountYuan = maxAmountYuan;
        }

        public boolean charge(String orderId, int amountYuan) {
            // 代理只处理访问策略,不理解供应商字段。
            if (amountYuan > maxAmountYuan) {
                return false;
            }
            return target.charge(orderId, amountYuan);
        }
    }

    static final class PaymentFacade {
        private final PaymentGateway gateway;

        PaymentFacade(PaymentGateway gateway) {
            this.gateway = gateway;
        }

        boolean payOrder(String orderId, int amountYuan) {
            return gateway.charge(orderId, amountYuan);
        }
    }

    public static void main(String[] args) {
        PaymentGateway adapter = new VendorAdapter(new VendorSdk());
        PaymentGateway proxy = new AccessProxy(adapter, 1000);
        PaymentFacade facade = new PaymentFacade(proxy);

        System.out.println(facade.payOrder("ORDER-1", 300));
        System.out.println(facade.payOrder("ORDER-2", 1500));
    }
}

预期输出

text
true
false

这个例子里,换供应商时主要替换适配器;修改访问上限时改代理配置或实现;业务入口变化时改外观。三种变化不会直接冲击业务服务。

把错误、超时和重试也收敛在边界

真实接口通常还会返回供应商专有错误码、HTTP 状态和异常。适配器应把这些信息映射成系统自己的错误类型,至少区分“业务拒绝”“可重试的临时失败”和“未知失败”。这样上层不会出现到处判断某个供应商字符串错误码的代码。

超时应配置在真正发起网络请求的客户端层;是否重试则要结合操作是否幂等。查询类接口通常可以有限重试,扣款等有副作用的接口必须依赖幂等键或供应商明确的幂等能力,不能因为超时就盲目再次提交。

用替换测试验证隔离是否成功

判断边界是否真的拆开,可以做一个简单测试:把 VendorAdapter 换成内存实现或另一个供应商适配器,如果 PaymentFacade 和业务服务无需改代码,说明依赖方向基本正确。

还要检查业务层是否出现供应商 DTO、供应商错误码或 SDK 类型;一旦出现,就意味着适配器边界被穿透。外观也不应暴露“先调用 A 再调用 B”的细节,而应提供面向业务意图的方法,例如“支付订单”或“发送验证码”。

当第三方服务非常简单、只有一个稳定接口且没有字段转换或横切控制时,不必强行叠加三种模式。模式的价值在于把不同变化隔离到不同位置;只有确实存在这些变化轴时,适配器、外观和代理的组合才会让接入层更容易替换和测试。

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

目录与阅读设置

阅读设置

17

记录一个想法

拆分第三方服务接入边界

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

登录哪都通