架构与系统设计 / 系统课时
支付平台综合项目
支付平台综合项目
本课用一个最小但完整的项目闭环串联商户接入、统一下单、通道路由、异步通知、退款、对账和结算,最终形成可运行、可追踪、可核对、可验收的支付平台主链路。
学习目标
- 设计覆盖支付全生命周期的最小业务模型与状态边界
- 串联下单、路由、回调、通知、退款、对账和结算处理
- 使用接口验收脚本验证主流程、幂等性与最终一致性
项目目标与最小范围
项目只实现一条可闭环的主链路:商户完成接入后提交统一下单请求,平台选择可用通道并创建支付,通道回调推动订单成功,平台异步通知商户;之后可发起退款,并在日终完成对账和结算批次生成。
最小数据对象包括商户、支付订单、通道路由规则、退款订单、通知任务、对账明细和结算批次。所有金额使用最小货币单位整数保存,所有外部请求都携带幂等键,所有状态变更都记录时间与追踪号。

统一状态与一致性边界
支付订单建议使用 CREATED、PROCESSING、SUCCESS、FAILED、CLOSED 五个主状态。退款订单独立使用 CREATED、PROCESSING、SUCCESS、FAILED,不能把退款成功直接改写成支付失败。
关键一致性规则如下:统一下单按“商户号 + 商户订单号”幂等;通道回调按通道流水号去重;订单成功后再创建通知任务;退款累计金额不得超过支付成功金额;对账只修复账务差异,不直接伪造支付成功;结算只汇总已支付、已对账且未结算的数据。
核心编排实现
下面是核心应用服务的片段示例,依赖已实现的订单仓储、路由器、通道适配器和通知任务仓储。它展示下单与回调之间的职责边界:下单负责创建订单并发起通道请求,回调负责幂等更新状态并创建商户通知任务。
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 读取订单号,并依次执行下单、模拟成功回调、查询订单和退款。
#!/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预期输出:
{"code":"SUCCESS","data":{"orderNo":"<ID>","status":"SUCCESS","amount":1000,"currency":"HKD"}}
{"code":"SUCCESS","data":{"refundNo":"<ID>","status":"PROCESSING","amount":300}}<PORT>、<ID> 和订单时间为动态值。若退款通道在测试环境同步返回成功,第二个状态也可能是 SUCCESS;验收重点是订单已收敛为成功、重复回调不重复记账、退款金额正确、通知任务可查且后续能进入对账与结算。
验收清单与失败定位
项目验收至少覆盖正常支付、重复下单、重复回调、回调先于主动查询、部分退款、重复退款、通知重试、账单差异和重复生成结算批次。任何一项都应能通过订单号、商户订单号、通道流水号和追踪号串联日志。
出现问题时按链路顺序定位:先检查请求验签与幂等记录,再检查订单状态和路由结果,然后检查通道请求与回调,最后检查通知、账务、对账和结算记录。不要跳过前置状态直接修改后续表,否则会把一次业务故障扩大成账务不一致。