架构与系统设计 / 系统课时
把支付调用隔离到基础设施层
把支付调用隔离到基础设施层
订单应用服务需要“发起支付”,但不应该知道支付厂商 SDK、HTTP 协议或鉴权细节。本节把支付能力定义成应用层端口,再由基础设施层适配第三方调用,让业务用例保持稳定,并能独立测试。
学习目标
- 能在应用层定义不泄露第三方类型的支付能力抽象
- 能在基础设施层完成第三方调用与结果映射
- 能检查应用层、领域层是否仍然反向依赖支付实现
先确定支付边界
支付端口描述的是订单用例真正需要的能力,而不是某个厂商提供了哪些 API。接口和返回模型应由内层拥有,这样更换支付渠道时,应用服务的调用方式不需要跟着变化。
下面是片段示例,放在 com.example.order.application.payment 包中;它只使用应用层自己的类型,不引用第三方 SDK。
package com.example.order.application.payment;
public interface PaymentGateway {
PaymentResult charge(PaymentCommand command);
record PaymentCommand(String orderId, long amountFen) {
public PaymentCommand {
if (orderId == null || orderId.isBlank()) {
throw new IllegalArgumentException("orderId must not be blank");
}
if (amountFen <= 0) {
throw new IllegalArgumentException("amountFen must be positive");
}
}
}
record PaymentResult(Status status, String providerReference) {}
enum Status {
SUCCEEDED,
REJECTED,
UNKNOWN
}
}这里保留 UNKNOWN 很重要:网络超时并不能证明支付失败。应用层可以据此进入“待确认”状态,而不是把第三方的超时异常直接传播到领域模型。
在基础设施层适配第三方调用
基础设施实现 PaymentGateway,负责把内部命令转换为供应商请求,再把供应商结果映射回应用层语义。下面也是片段示例,其中 ProviderSdk 是本项目对真实支付 SDK 的本地包装,不代表任何厂商的官方 API;实际方法名、字段和错误码必须按所接入供应商文档实现。
package com.example.order.infrastructure.payment;
import com.example.order.application.payment.PaymentGateway;
public final class ThirdPartyPaymentGateway implements PaymentGateway {
private final ProviderSdk providerSdk;
public ThirdPartyPaymentGateway(ProviderSdk providerSdk) {
this.providerSdk = providerSdk;
}
@Override
public PaymentResult charge(PaymentCommand command) {
ProviderSdk.ChargeReply reply =
providerSdk.charge(command.orderId(), command.amountFen());
Status status = switch (reply.outcome()) {
case SUCCESS -> Status.SUCCEEDED;
case REJECTED -> Status.REJECTED;
case INDETERMINATE -> Status.UNKNOWN;
};
return new PaymentResult(status, reply.reference());
}
public interface ProviderSdk {
ChargeReply charge(String merchantOrderId, long amountFen);
record ChargeReply(Outcome outcome, String reference) {}
enum Outcome {
SUCCESS,
REJECTED,
INDETERMINATE
}
}
}这段代码的关键不是 ProviderSdk 的形状,而是类型归属:第三方协议只停留在基础设施层,向内只暴露 PaymentGateway.PaymentResult。供应商异常、错误码、签名参数和重试策略都应在适配器附近转换。

让应用服务只面向端口
应用服务只注入 PaymentGateway。它可以根据 SUCCEEDED、REJECTED、UNKNOWN 决定订单状态,但不应出现供应商客户端、HTTP 状态码或厂商错误枚举。下面是应用服务片段示例,依赖前文定义的 PaymentGateway。
package com.example.order.application;
import com.example.order.application.payment.PaymentGateway;
public final class PayOrderService {
private final PaymentGateway paymentGateway;
public PayOrderService(PaymentGateway paymentGateway) {
this.paymentGateway = paymentGateway;
}
public PaymentGateway.PaymentResult pay(String orderId, long amountFen) {
return paymentGateway.charge(
new PaymentGateway.PaymentCommand(orderId, amountFen)
);
}
}这也是测试性提升的来源:单元测试可以直接传入一个内存版 PaymentGateway,不需要启动真实支付 SDK 或网络连接。
验证隔离是否成立
重构后最容易遗漏的是某个应用服务仍然 import 基础设施类。下面的命令可作为快速检查;它假定订单模块源码位于 src/main/java/com/example/order。
if grep -R -n -E 'java\.net\.http|com\.example\.order\.infrastructure' src/main/java/com/example/order/application src/main/java/com/example/order/domain --include='*.java'; then
echo "Forbidden payment infrastructure dependency found"
exit 1
fi
echo "Payment dependency isolation passed."预期输出
Payment dependency isolation passed.如果命令打印出文件路径和行号,就说明内层仍然知道 HTTP 或基础设施实现,应把那段协议代码继续向外移动。这个检查只能发现显式导入和 java.net.http 使用;在持续集成中还可以用架构测试补充对完整依赖图的约束。
支付隔离完成后的判断标准很直接:应用层只知道“支付能力和业务语义”,基础设施层才知道“由谁支付、怎样发请求、怎样解释供应商响应”。只要第三方类型不跨过这条边界,更换通道、增加重试或修改鉴权方式就不会迫使订单用例一起改写。