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

把支付调用隔离到基础设施层

把支付调用隔离到基础设施层

订单应用服务需要“发起支付”,但不应该知道支付厂商 SDK、HTTP 协议或鉴权细节。本节把支付能力定义成应用层端口,再由基础设施层适配第三方调用,让业务用例保持稳定,并能独立测试。

学习目标

  • 能在应用层定义不泄露第三方类型的支付能力抽象
  • 能在基础设施层完成第三方调用与结果映射
  • 能检查应用层、领域层是否仍然反向依赖支付实现

先确定支付边界

支付端口描述的是订单用例真正需要的能力,而不是某个厂商提供了哪些 API。接口和返回模型应由内层拥有,这样更换支付渠道时,应用服务的调用方式不需要跟着变化。

下面是片段示例,放在 com.example.order.application.payment 包中;它只使用应用层自己的类型,不引用第三方 SDK。

java
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;实际方法名、字段和错误码必须按所接入供应商文档实现。

java
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。

java
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。

bash
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."

预期输出

text
Payment dependency isolation passed.

如果命令打印出文件路径和行号,就说明内层仍然知道 HTTP 或基础设施实现,应把那段协议代码继续向外移动。这个检查只能发现显式导入和 java.net.http 使用;在持续集成中还可以用架构测试补充对完整依赖图的约束。

支付隔离完成后的判断标准很直接:应用层只知道“支付能力和业务语义”,基础设施层才知道“由谁支付、怎样发请求、怎样解释供应商响应”。只要第三方类型不跨过这条边界,更换通道、增加重试或修改鉴权方式就不会迫使订单用例一起改写。

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

目录与阅读设置

阅读设置

17

记录一个想法

把支付调用隔离到基础设施层

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

登录哪都通