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

支付平台综合项目

支付平台综合项目

本课用一个最小但完整的项目闭环串联商户接入、统一下单、通道路由、异步通知、退款、对账和结算,最终形成可运行、可追踪、可核对、可验收的支付平台主链路。

学习目标

  • 设计覆盖支付全生命周期的最小业务模型与状态边界
  • 串联下单、路由、回调、通知、退款、对账和结算处理
  • 使用接口验收脚本验证主流程、幂等性与最终一致性

项目目标与最小范围

项目只实现一条可闭环的主链路:商户完成接入后提交统一下单请求,平台选择可用通道并创建支付,通道回调推动订单成功,平台异步通知商户;之后可发起退款,并在日终完成对账和结算批次生成。

最小数据对象包括商户、支付订单、通道路由规则、退款订单、通知任务、对账明细和结算批次。所有金额使用最小货币单位整数保存,所有外部请求都携带幂等键,所有状态变更都记录时间与追踪号。

支付平台综合业务闭环

统一状态与一致性边界

支付订单建议使用 CREATED、PROCESSING、SUCCESS、FAILED、CLOSED 五个主状态。退款订单独立使用 CREATED、PROCESSING、SUCCESS、FAILED,不能把退款成功直接改写成支付失败。

关键一致性规则如下:统一下单按“商户号 + 商户订单号”幂等;通道回调按通道流水号去重;订单成功后再创建通知任务;退款累计金额不得超过支付成功金额;对账只修复账务差异,不直接伪造支付成功;结算只汇总已支付、已对账且未结算的数据。

核心编排实现

下面是核心应用服务的片段示例,依赖已实现的订单仓储、路由器、通道适配器和通知任务仓储。它展示下单与回调之间的职责边界:下单负责创建订单并发起通道请求,回调负责幂等更新状态并创建商户通知任务。

java
import java.util.Objects;

public final class PaymentApplicationService {
    private final PaymentOrderRepository orderRepository;
    private final ChannelRouter channelRouter;
    private final ChannelAdapterFactory adapterFactory;
    private final NotifyTaskRepository notifyTaskRepository;

    public PaymentApplicationService(
            PaymentOrderRepository orderRepository,
            ChannelRouter channelRouter,
            ChannelAdapterFactory adapterFactory,
            NotifyTaskRepository notifyTaskRepository) {
        this.orderRepository = orderRepository;
        this.channelRouter = channelRouter;
        this.adapterFactory = adapterFactory;
        this.notifyTaskRepository = notifyTaskRepository;
    }

    public PayResult createOrder(CreatePayCommand command) {
        // 商户订单号是统一下单的业务幂等键
        PaymentOrder existing = orderRepository.findByMerchantOrder(
                command.merchantNo(), command.merchantOrderNo());
        if (existing != null) {
            return PayResult.from(existing);
        }

        // 先选路由并落本地订单,再调用外部通道
        ChannelRoute route = channelRouter.select(
                command.payMethod(), command.currency(), command.amount());
        PaymentOrder order = PaymentOrder.create(command, route.channelCode());
        orderRepository.insert(order);

        ChannelPayResult channelResult = adapterFactory
                .get(route.channelCode())
                .pay(order);

        order.markProcessing(channelResult.channelOrderNo());
        orderRepository.update(order);
        return PayResult.from(order);
    }

    public void handleChannelCallback(ChannelCallback callback) {
        PaymentOrder order = orderRepository.findByChannelOrderNo(
                callback.channelOrderNo());
        // 重复回调或终态回调只返回,不重复记账
        if (order == null || order.isFinalState()) {
            return;
        }

        if (Objects.equals(callback.status(), "SUCCESS")) {
            order.markSuccess(callback.channelTransactionNo());
            orderRepository.update(order);
            // 订单更新与通知任务创建应处于同一事务
            notifyTaskRepository.insertIfAbsent(order.id(), order.notifyUrl());
        } else {
            order.markFailed(callback.errorCode());
            orderRepository.update(order);
        }
    }
}

这段代码不能独立运行,必须配合事务、唯一索引和接口实现。生产实现还应将“订单状态更新”和“创建通知任务”放在同一事务中,通知发送由独立任务异步执行,避免在通道回调线程里直接调用商户接口。

七段业务链路

商户接入阶段保存商户状态、签名密钥、允许的支付方式和通知地址。只有审核通过且启用的商户才能调用统一下单接口,平台必须校验签名、时间戳、请求唯一标识和金额边界。

统一下单阶段先做幂等检查,再创建本地订单。通道路由根据支付方式、币种、金额、地区、优先级、权重和通道健康度筛选候选通道;没有可用通道时应明确失败,不创建无法继续处理的半成品订单。

通道回调阶段先验签,再按通道订单号定位本地订单。状态更新必须满足单向收敛:终态不能被普通回调覆盖;重复成功回调只能返回成功应答,不能重复记账或重复创建通知任务。

商户通知阶段使用任务表记录通知地址、次数、下次执行时间和最后错误。发送失败后按退避策略重试,达到上限后进入人工处理队列;商户返回约定成功标识后才把任务标记为完成。

退款阶段校验原支付订单已成功、累计退款金额未超限,并以商户退款单号保证幂等。退款成功后生成负向账务记录,但保留原支付订单成功状态。

对账阶段导入渠道账单,分别执行“本地找渠道”和“渠道找本地”的双向匹配。差异必须分类为本地单边、渠道单边、金额不一致、状态不一致或重复记录,并保留人工复核入口。

结算阶段仅汇总符合结算周期、已对账、未结算的净额,计算交易金额、退款金额、手续费和应结金额。批次生成与明细锁定应在同一事务中,避免同一笔流水进入多个结算批次。

端到端验收

下面的脚本是项目验收示例,依赖本地服务已启动在 http://localhost:<PORT>,并已准备测试商户、签名和可用通道。脚本使用 jq 读取订单号,并依次执行下单、模拟成功回调、查询订单和退款。

bash
#!/usr/bin/env bash
set -euo pipefail

BASE_URL="http://localhost:<PORT>"
MERCHANT_NO="M10001"
MERCHANT_ORDER_NO="T$(date +%s)"

# 创建统一支付订单,并保存平台订单号
pay_response=$(curl -sS -X POST "$BASE_URL/open-api/pay/orders" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: req-$MERCHANT_ORDER_NO" \
  -d "{
    \"merchantNo\": \"$MERCHANT_NO\",
    \"merchantOrderNo\": \"$MERCHANT_ORDER_NO\",
    \"amount\": 1000,
    \"currency\": \"HKD\",
    \"payMethod\": \"WECHAT\",
    \"notifyUrl\": \"https://merchant.example.com/pay/notify\"
  }")

order_no=$(echo "$pay_response" | jq -r '.data.orderNo')

# 测试环境模拟通道成功回调
curl -sS -X POST "$BASE_URL/internal/channel/callbacks/mock" \
  -H "Content-Type: application/json" \
  -d "{
    \"orderNo\": \"$order_no\",
    \"status\": \"SUCCESS\",
    \"channelTransactionNo\": \"CH-$MERCHANT_ORDER_NO\"
  }" >/dev/null

# 查询支付终态,再发起部分退款
curl -sS "$BASE_URL/open-api/pay/orders/$order_no"
echo

curl -sS -X POST "$BASE_URL/open-api/refunds" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: refund-$MERCHANT_ORDER_NO" \
  -d "{
    \"merchantNo\": \"$MERCHANT_NO\",
    \"merchantRefundNo\": \"R-$MERCHANT_ORDER_NO\",
    \"orderNo\": \"$order_no\",
    \"amount\": 300
  }"
echo

预期输出:

text
{"code":"SUCCESS","data":{"orderNo":"<ID>","status":"SUCCESS","amount":1000,"currency":"HKD"}}
{"code":"SUCCESS","data":{"refundNo":"<ID>","status":"PROCESSING","amount":300}}

<PORT>、<ID> 和订单时间为动态值。若退款通道在测试环境同步返回成功,第二个状态也可能是 SUCCESS;验收重点是订单已收敛为成功、重复回调不重复记账、退款金额正确、通知任务可查且后续能进入对账与结算。

验收清单与失败定位

项目验收至少覆盖正常支付、重复下单、重复回调、回调先于主动查询、部分退款、重复退款、通知重试、账单差异和重复生成结算批次。任何一项都应能通过订单号、商户订单号、通道流水号和追踪号串联日志。

出现问题时按链路顺序定位:先检查请求验签与幂等记录,再检查订单状态和路由结果,然后检查通道请求与回调,最后检查通知、账务、对账和结算记录。不要跳过前置状态直接修改后续表,否则会把一次业务故障扩大成账务不一致。

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

目录与阅读设置

阅读设置

17

记录一个想法

支付平台综合项目

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

登录哪都通