架构与系统设计 / 系统课时
适配器统一不兼容的接口
适配器统一不兼容的接口
接入第三方 SDK 或遗留模块时,最危险的做法往往是让业务代码直接适配外部接口。适配器把外部模型转换成系统自己的接口,使上层只面对稳定的业务契约,而不必知道供应商实现细节。
学习目标
- 理解适配器解决的是“接口不兼容”,而不是简单复制方法
- 学会让业务代码依赖自己的接口,由适配器隔离第三方 SDK
- 能够验证适配前后业务调用方式保持稳定
适配器真正隔离了什么
假设系统内部约定的是 PaymentGateway.charge(orderId, cents),第三方 SDK 却要求 createPayment(amount, reference),返回值也使用自己的 PaymentResult。两边表达的是同一业务动作,但接口、参数和结果模型并不兼容。
适配器的职责就是站在两套契约之间,把系统内部请求转换成外部调用,再把外部结果转换回内部模型。业务层不需要知道 SDK 的类名、参数命名和返回结构。

用自己的接口包住外部实现
下面的 Java 示例模拟第三方 SDK。业务代码只依赖自己的 PaymentGateway,适配器负责字段转换。示例可直接运行,不依赖具体供应商 SDK。
public class AdapterDemo {
interface PaymentGateway {
PaymentReceipt charge(String orderId, int cents);
}
record PaymentReceipt(String orderId, String transactionId) {}
// 模拟第三方 SDK:方法名、参数顺序和返回模型都不同。
static class VendorClient {
VendorResult createPayment(int amount, String reference) {
return new VendorResult(reference, "TX-10001");
}
}
record VendorResult(String reference, String transactionId) {}
static class VendorPaymentAdapter implements PaymentGateway {
private final VendorClient client;
VendorPaymentAdapter(VendorClient client) {
this.client = client;
}
@Override
public PaymentReceipt charge(String orderId, int cents) {
VendorResult result = client.createPayment(cents, orderId);
return new PaymentReceipt(result.reference(), result.transactionId());
}
}
static class OrderService {
private final PaymentGateway gateway;
OrderService(PaymentGateway gateway) {
this.gateway = gateway;
}
String pay(String orderId, int cents) {
PaymentReceipt receipt = gateway.charge(orderId, cents);
return receipt.orderId() + " -> " + receipt.transactionId();
}
}
public static void main(String[] args) {
PaymentGateway gateway = new VendorPaymentAdapter(new VendorClient());
OrderService service = new OrderService(gateway);
System.out.println(service.pay("ORDER-42", 1999));
}
}预期输出
ORDER-42 -> TX-10001业务服务完全不需要调用 VendorClient.createPayment,因此第三方 SDK 的接口变化不会自然扩散到订单领域代码。以后替换供应商时,可以新增另一个 PaymentGateway 实现,而不改变 OrderService 的业务接口。
不要把适配器写成业务层
适配器应该主要承担接口转换。参数映射、结果映射、异常类型转换和必要的格式兼容都属于合理职责;但“是否允许支付”“订单能否取消”“用户是否有权限”等业务规则不应偷偷塞进适配器。
一个简单边界是:拿掉第三方 SDK 后,适配器中的代码大多应该失去意义;而业务服务中的规则即使更换供应商,也应该继续成立。这样可以快速判断某段逻辑到底属于集成层还是业务层。
什么时候使用适配器
最典型的场景是接入第三方 SDK、遗留模块或历史接口,而且你希望内部代码维持稳定。尤其当外部接口字段命名、异常类型、返回结构或调用方式与现有模型差异明显时,适配器能把变化集中在边界。
如果两边接口本来就完全一致,只差一个类型别名,那么额外增加适配器未必有价值。真正值得保留的适配器,应该让调用方获得一个稳定接口,同时把外部变化控制在一个明确位置。