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

统一下单模型

统一下单模型

本课把不同支付产品收敛为一套稳定的下单契约,最终得到统一请求对象、分层校验规则和一致响应结构。完成后,业务端无需感知微信、银行卡或其他通道的字段差异,支付平台也能在受理阶段尽早拒绝无效请求。

学习目标

  • 设计覆盖金额、产品、场景和回调信息的统一请求对象
  • 区分基础校验、业务校验与通道校验的职责
  • 返回可追踪、可幂等处理的统一受理结果

统一模型解决什么问题

统一下单模型不是把所有通道字段简单拼进一个大对象,而是先描述平台层稳定语义,再把少量产品差异放入扩展字段。核心字段应长期稳定,通道专属参数则在路由完成后转换,避免商户接口随通道变化而频繁升级。

请求进入平台后,依次经过参数校验、幂等检查、订单创建、产品路由和响应组装。任何通道适配都发生在统一模型之后,因此上游系统只需要维护一套接口。

统一下单请求处理链路

请求字段与边界

建议把字段分为四组:商户身份与幂等标识、交易金额与币种、产品与场景、通知与附加信息。merchantOrderNo 保证商户侧订单唯一,requestId 标识一次调用;两者职责不同,不能互相替代。

amount 应使用十进制类型并要求大于零,禁止使用浮点数。currency 使用 ISO 货币代码,payMethod 表示支付方式,productType 表示具体产品,scene 描述扫码、H5、App 等使用场景。extra 只承载少量产品扩展信息,不能绕过正式字段校验。

下面是一个可直接运行的 Java 主示例,它定义统一请求、校验器和受理响应。示例只演示平台入口校验,不包含数据库落单与真实通道调用。

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 + " 不能为空");
        }
    }
}

预期输出:

text
ACCEPTED orderNo=P202608030000000001 status=CREATED requestId=req-001

校验应分三层完成

基础校验只检查非空、格式、长度、金额精度和枚举范围,适合在接口入口立即执行。业务校验检查商户状态、支付产品是否开通、金额是否落在商户限额内;它依赖平台数据,不能写进简单注解。

通道校验在路由完成后执行,例如某通道只支持特定币种、某产品要求 extra 中存在门店号。这样既能保持统一模型稳定,又不会把全部通道规则耦合到公共 DTO 中。

Tips:校验错误应返回稳定错误码和明确字段名,但不要把内部路由、密钥或通道原始报文暴露给调用方。

响应、幂等与状态约定

统一响应至少包含平台结果码、说明、订单数据和原始 requestId。下单成功只表示平台已经受理,初始状态通常是 CREATED 或 PROCESSING;只有收到可靠的同步结果或异步通知后,订单才能进入支付成功状态。

幂等键建议使用“商户号 + 商户订单号”建立唯一约束。相同键且关键字段一致时返回原订单;金额、币种或产品不同则拒绝,防止调用方误把同一个业务订单改成另一笔交易。requestId 主要用于链路追踪,也可辅助识别短时间重试。

验收时至少覆盖正常受理、金额为零、非法币种、非 HTTPS 回调地址,以及相同商户订单号重复提交但金额不同这五类场景。

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

目录与阅读设置

阅读设置

17

记录一个想法

统一下单模型

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

登录哪都通