架构与系统设计 / 系统课时
拆分第三方服务接入边界
拆分第三方服务接入边界
接入支付、短信或地图供应商时,真正难维护的通常不是一次 HTTP 调用,而是供应商字段、鉴权、错误码、重试和访问控制逐渐渗入业务代码。本节用适配器、外观和代理分层隔离这些变化,让业务只依赖稳定边界。
学习目标
- 区分适配器、外观和代理在第三方接入中的不同职责。
- 用稳定接口隔离供应商数据模型和调用细节。
- 把访问控制、日志等横切逻辑放到代理层,并验证替换边界。
先划清三种模式的职责
适配器解决“接口不兼容”:把供应商方法、参数单位和返回状态转换成系统自己的模型。外观解决“调用太复杂”:把一次业务动作需要的多个底层步骤收敛成少量稳定入口。代理解决“访问需要控制”:在不改变目标接口的前提下增加鉴权、限流、审计或延迟创建。
三者可以叠加,但不要互相代替。业务服务应该依赖外观;外观依赖系统定义的网关接口;代理实现同一网关接口并包住适配器;适配器再接触具体供应商 SDK 或 HTTP 客户端。

用代码把供应商模型挡在边界外
下面的 Java 17 示例用本地类模拟供应商 SDK,不依赖真实网络。业务侧只认识 PaymentGateway 和 PaymentFacade;VendorAdapter 负责把“元”转换为供应商需要的“分”,并把供应商状态映射为系统自己的布尔结果;AccessProxy 在调用前做访问控制。
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));
}
}预期输出
true
false这个例子里,换供应商时主要替换适配器;修改访问上限时改代理配置或实现;业务入口变化时改外观。三种变化不会直接冲击业务服务。
把错误、超时和重试也收敛在边界
真实接口通常还会返回供应商专有错误码、HTTP 状态和异常。适配器应把这些信息映射成系统自己的错误类型,至少区分“业务拒绝”“可重试的临时失败”和“未知失败”。这样上层不会出现到处判断某个供应商字符串错误码的代码。
超时应配置在真正发起网络请求的客户端层;是否重试则要结合操作是否幂等。查询类接口通常可以有限重试,扣款等有副作用的接口必须依赖幂等键或供应商明确的幂等能力,不能因为超时就盲目再次提交。
用替换测试验证隔离是否成功
判断边界是否真的拆开,可以做一个简单测试:把 VendorAdapter 换成内存实现或另一个供应商适配器,如果 PaymentFacade 和业务服务无需改代码,说明依赖方向基本正确。
还要检查业务层是否出现供应商 DTO、供应商错误码或 SDK 类型;一旦出现,就意味着适配器边界被穿透。外观也不应暴露“先调用 A 再调用 B”的细节,而应提供面向业务意图的方法,例如“支付订单”或“发送验证码”。
当第三方服务非常简单、只有一个稳定接口且没有字段转换或横切控制时,不必强行叠加三种模式。模式的价值在于把不同变化隔离到不同位置;只有确实存在这些变化轴时,适配器、外观和代理的组合才会让接入层更容易替换和测试。