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

渠道请求组装

渠道请求组装

同一笔平台订单在不同支付机构中可能使用不同金额单位、时间格式和枚举值。本课将实现可验证的请求组装器,把统一订单稳定转换为渠道字段,并在发送前完成精度、时区和必填项校验。

学习目标

  • 将平台订单字段映射为渠道请求字段
  • 正确处理金额最小单位、时间格式与枚举转换
  • 通过确定性输出验证请求组装结果

先定义转换边界

请求组装只负责字段转换和本地校验,不负责发起网络请求。输入应是平台内部稳定模型,输出应是渠道请求对象或待签名字段集合。

组装过程建议固定为“校验平台字段、转换格式、映射枚举、补充渠道字段、生成确定顺序的数据”。签名和 HTTP 调用可以使用该结果,但不应反向修改订单对象。

渠道请求组装流程

完整组装示例

下面示例将元金额转换为分,将 Instant 转为 UTC 时间文本,并把平台支付方式映射为渠道枚举。TreeMap 用于保证字段顺序稳定,便于后续生成签名原文。

java
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.time.Instant;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.util.Map;
import java.util.TreeMap;

public class ChannelRequestAssemblerDemo {
    enum PayMethod {
        APP, QR_CODE
    }

    record PlatformOrder(String orderNo, BigDecimal amount,
                         Instant expireAt, PayMethod payMethod,
                         String subject) {}

    static final class ChannelRequestAssembler {
        private static final DateTimeFormatter TIME_FORMAT =
                DateTimeFormatter.ofPattern("yyyyMMddHHmmss")
                        .withZone(ZoneOffset.UTC);

        Map<String, String> assemble(PlatformOrder order) {
            validate(order);

            Map<String, String> fields = new TreeMap<>();
            fields.put("merchant_order_no", order.orderNo());
            fields.put("amount_cent", toCent(order.amount()));
            fields.put("expire_time", TIME_FORMAT.format(order.expireAt()));
            fields.put("trade_type", mapPayMethod(order.payMethod()));
            fields.put("subject", order.subject().trim());
            return fields;
        }

        private void validate(PlatformOrder order) {
            if (order.orderNo() == null || order.orderNo().isBlank()) {
                throw new IllegalArgumentException("orderNo is required");
            }
            if (order.amount() == null || order.amount().signum() <= 0) {
                throw new IllegalArgumentException("amount must be positive");
            }
            if (order.expireAt() == null || order.payMethod() == null) {
                throw new IllegalArgumentException("expireAt and payMethod are required");
            }
            if (order.subject() == null || order.subject().isBlank()) {
                throw new IllegalArgumentException("subject is required");
            }
        }

        private String toCent(BigDecimal amount) {
            // 精确移动小数点,禁止使用 double 参与金额计算
            return amount.movePointRight(2)
                    .setScale(0, RoundingMode.UNNECESSARY)
                    .toPlainString();
        }

        private String mapPayMethod(PayMethod payMethod) {
            return switch (payMethod) {
                case APP -> "APP_PAY";
                case QR_CODE -> "NATIVE_QR";
            };
        }
    }

    public static void main(String[] args) {
        PlatformOrder order = new PlatformOrder(
                "P202608030002",
                new BigDecimal("19.90"),
                Instant.parse("2026-08-03T12:30:00Z"),
                PayMethod.QR_CODE,
                "测试订单");

        Map<String, String> request =
                new ChannelRequestAssembler().assemble(order);

        request.forEach((key, value) ->
                System.out.println(key + "=" + value));
    }
}

预期输出:

text
amount_cent=1990
expire_time=20260803123000
merchant_order_no=P202608030002
subject=测试订单
trade_type=NATIVE_QR

TreeMap 按字段名排序,因此输出顺序可重复。实际渠道若要求固定字段顺序,应按渠道规范显式维护顺序,不要依赖普通 HashMap。

金额转换边界

金额转换必须使用 BigDecimal。从元转分可使用 movePointRight(2),再用 RoundingMode.UNNECESSARY 检查是否存在超过两位的小数;若出现 19.901,应直接拒绝,而不是静默四舍五入。

还要校验渠道最小金额、最大金额和币种精度。多币种场景不能默认所有币种都是两位小数,应由币种规则决定最小单位。

时间与枚举处理

平台内部建议统一保存 Instant,组装时再按渠道要求转换时区和格式。不要先转本地时间再猜测时区,否则部署区域变化后可能产生不同请求。

枚举映射必须穷举。未知平台值或渠道暂不支持的值应在发送前失败,不能使用 name() 直接透传,因为内部枚举名不属于外部协议。

发送前验证

组装完成后应执行三类检查:必填字段是否存在、字段长度是否超限、签名前字段值是否稳定。日志中可以记录订单号、通道编码和字段摘要,但敏感字段应脱敏。

验收时可使用固定订单输入做快照测试,确认金额、时间、枚举和字段顺序均未变化。渠道规范升级时,快照差异能直接暴露协议变更。

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

目录与阅读设置

阅读设置

17

记录一个想法

渠道请求组装

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

登录哪都通