架构与系统设计 / 系统课时
统一下单模型
统一下单模型
本课把不同支付产品收敛为一套稳定的下单契约,最终得到统一请求对象、分层校验规则和一致响应结构。完成后,业务端无需感知微信、银行卡或其他通道的字段差异,支付平台也能在受理阶段尽早拒绝无效请求。
学习目标
- 设计覆盖金额、产品、场景和回调信息的统一请求对象
- 区分基础校验、业务校验与通道校验的职责
- 返回可追踪、可幂等处理的统一受理结果
统一模型解决什么问题
统一下单模型不是把所有通道字段简单拼进一个大对象,而是先描述平台层稳定语义,再把少量产品差异放入扩展字段。核心字段应长期稳定,通道专属参数则在路由完成后转换,避免商户接口随通道变化而频繁升级。
请求进入平台后,依次经过参数校验、幂等检查、订单创建、产品路由和响应组装。任何通道适配都发生在统一模型之后,因此上游系统只需要维护一套接口。

请求字段与边界
建议把字段分为四组:商户身份与幂等标识、交易金额与币种、产品与场景、通知与附加信息。merchantOrderNo 保证商户侧订单唯一,requestId 标识一次调用;两者职责不同,不能互相替代。
amount 应使用十进制类型并要求大于零,禁止使用浮点数。currency 使用 ISO 货币代码,payMethod 表示支付方式,productType 表示具体产品,scene 描述扫码、H5、App 等使用场景。extra 只承载少量产品扩展信息,不能绕过正式字段校验。
下面是一个可直接运行的 Java 主示例,它定义统一请求、校验器和受理响应。示例只演示平台入口校验,不包含数据库落单与真实通道调用。
import java.math.BigDecimal;
import java.net.URI;
import java.util.Map;
import java.util.Set;
public class UnifiedOrderDemo {
record UnifiedOrderRequest(
String merchantNo,
String merchantOrderNo,
BigDecimal amount,
String currency,
String payMethod,
String productType,
String scene,
String subject,
String notifyUrl,
String clientIp,
Integer expireMinutes,
String requestId,
Map<String, String> extra) {
}
record OrderData(String orderNo, String status) {
}
record OrderResponse(String code, String message, OrderData data, String requestId) {
}
static final Set<String> CURRENCIES = Set.of("CNY", "HKD", "USD");
static final Set<String> SCENES = Set.of("QR", "H5", "APP");
public static void main(String[] args) {
UnifiedOrderRequest request = new UnifiedOrderRequest(
"M10001",
"SHOP-20260803-001",
new BigDecimal("88.50"),
"HKD",
"QR_CODE",
"WECHAT",
"QR",
"测试订单",
"https://merchant.example.com/payment/notify",
"203.0.113.10",
15,
"req-001",
Map.of("storeNo", "S001"));
validate(request);
OrderResponse response = new OrderResponse(
"ACCEPTED",
"订单已受理",
new OrderData("P202608030000000001", "CREATED"),
request.requestId());
System.out.printf("%s orderNo=%s status=%s requestId=%s%n",
response.code(),
response.data().orderNo(),
response.data().status(),
response.requestId());
}
static void validate(UnifiedOrderRequest request) {
requireText(request.merchantNo(), "merchantNo");
requireText(request.merchantOrderNo(), "merchantOrderNo");
requireText(request.requestId(), "requestId");
requireText(request.payMethod(), "payMethod");
requireText(request.productType(), "productType");
requireText(request.subject(), "subject");
requireText(request.notifyUrl(), "notifyUrl");
if (request.amount() == null || request.amount().signum() <= 0) {
throw new IllegalArgumentException("amount 必须大于 0");
}
if (request.amount().scale() > 2) {
throw new IllegalArgumentException("amount 最多保留两位小数");
}
if (!CURRENCIES.contains(request.currency())) {
throw new IllegalArgumentException("不支持的 currency");
}
if (!SCENES.contains(request.scene())) {
throw new IllegalArgumentException("不支持的 scene");
}
if (request.expireMinutes() == null
|| request.expireMinutes() < 1
|| request.expireMinutes() > 1440) {
throw new IllegalArgumentException("expireMinutes 必须在 1~1440 之间");
}
URI notifyUri = URI.create(request.notifyUrl());
if (!"https".equalsIgnoreCase(notifyUri.getScheme())) {
throw new IllegalArgumentException("notifyUrl 必须使用 HTTPS");
}
}
static void requireText(String value, String field) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(field + " 不能为空");
}
}
}预期输出:
ACCEPTED orderNo=P202608030000000001 status=CREATED requestId=req-001校验应分三层完成
基础校验只检查非空、格式、长度、金额精度和枚举范围,适合在接口入口立即执行。业务校验检查商户状态、支付产品是否开通、金额是否落在商户限额内;它依赖平台数据,不能写进简单注解。
通道校验在路由完成后执行,例如某通道只支持特定币种、某产品要求 extra 中存在门店号。这样既能保持统一模型稳定,又不会把全部通道规则耦合到公共 DTO 中。
Tips:校验错误应返回稳定错误码和明确字段名,但不要把内部路由、密钥或通道原始报文暴露给调用方。
响应、幂等与状态约定
统一响应至少包含平台结果码、说明、订单数据和原始 requestId。下单成功只表示平台已经受理,初始状态通常是 CREATED 或 PROCESSING;只有收到可靠的同步结果或异步通知后,订单才能进入支付成功状态。
幂等键建议使用“商户号 + 商户订单号”建立唯一约束。相同键且关键字段一致时返回原订单;金额、币种或产品不同则拒绝,防止调用方误把同一个业务订单改成另一笔交易。requestId 主要用于链路追踪,也可辅助识别短时间重试。
验收时至少覆盖正常受理、金额为零、非法币种、非 HTTPS 回调地址,以及相同商户订单号重复提交但金额不同这五类场景。