架构与系统设计 / 系统课时
第三方支付接口应该放在哪里
第三方支付接口应该放在哪里
订单付款需要调用外部支付平台,但应用层不应该直接依赖某个厂商 SDK。更稳妥的做法是把“发起支付”抽象成业务可理解的端口,由基础设施层负责把这个端口适配成 HTTP 或 SDK 调用。
学习目标
- 判断支付抽象接口与第三方 SDK 实现分别属于哪一层
- 用依赖倒置让应用层只依赖支付能力而不是厂商客户端
- 识别支付结果、异常和幂等边界应该在哪里转换
先把业务能力和技术实现拆开
应用层关心的是“为订单发起支付并得到结果”,而不是请求地址、鉴权头、SDK 版本或重试参数。因此可以把 PaymentGateway 定义为应用层的出站端口;基础设施层实现它,并在实现内部调用真实支付厂商。
如果某个支付能力本身参与领域不变量判断,抽象也可以放在领域层。判断标准不是“接口一定放哪”,而是谁需要这个抽象:抽象靠近使用它的内层,具体网络实现留在基础设施层。

用一个可运行示例验证依赖方向
下面把第三方 SDK 简化成可运行的桩对象。真实项目中,只需把 ThirdPartyPaySdk 换成厂商 SDK 或 HTTP 客户端,应用服务本身不需要修改。
public class PaymentDemo {
record PaymentResult(String paymentId, String status) {}
interface PaymentGateway {
PaymentResult charge(String orderId, long amountFen);
}
static class CheckoutService {
private final PaymentGateway paymentGateway;
CheckoutService(PaymentGateway paymentGateway) {
this.paymentGateway = paymentGateway;
}
PaymentResult pay(String orderId, long amountFen) {
if (amountFen <= 0) {
throw new IllegalArgumentException("amount must be positive");
}
return paymentGateway.charge(orderId, amountFen);
}
}
static class ThirdPartyPaySdk {
String createPayment(String orderId, long amountFen) {
return "pay-" + orderId + ":" + amountFen;
}
}
static class SdkPaymentGateway implements PaymentGateway {
private final ThirdPartyPaySdk sdk = new ThirdPartyPaySdk();
@Override
public PaymentResult charge(String orderId, long amountFen) {
String raw = sdk.createPayment(orderId, amountFen);
String paymentId = raw.substring(0, raw.indexOf(':'));
return new PaymentResult(paymentId, "PENDING");
}
}
public static void main(String[] args) {
CheckoutService service = new CheckoutService(new SdkPaymentGateway());
System.out.println(service.pay("O1001", 9900));
}
}预期输出
PaymentResult[paymentId=pay-O1001, status=PENDING]应用层只看到 PaymentGateway 和业务结果;ThirdPartyPaySdk 只存在于基础设施实现中。这使测试时可以替换成内存实现,也避免厂商 API 变化扩散到用例代码。
在基础设施层完成协议转换
真实支付接口通常返回厂商状态码、错误码和原始响应。基础设施层应该把这些技术细节转换成内层能理解的结果,例如 PENDING、SUCCEEDED、FAILED,并把超时、签名失败等技术异常映射为明确的应用异常。
重试策略也要区分责任:网络超时重试属于基础设施关注点;“同一订单不能被重复扣款”属于业务幂等约束,通常需要应用层配合业务键、支付单状态或厂商幂等键保证。
处理事务边界而不是把问题藏进适配器
支付是远程调用,无法天然加入本地数据库事务。如果先保存订单再调用支付平台,可能出现本地提交成功而远程调用失败;如果先调用支付再提交订单,也可能出现支付成功但本地事务回滚。
因此 PaymentGateway 只负责外部支付能力的抽象与适配,不应该假装解决分布式事务。需要更高可靠性时,应结合支付单状态、幂等键、补偿任务或消息驱动流程显式处理失败窗口。
最终边界是:内层定义“我需要什么支付能力”,基础设施层负责“具体怎么和某家支付平台通信”。这样第三方 SDK 可以替换,业务用例不必跟着修改。