架构与系统设计 / 系统课时
渠道请求组装
渠道请求组装
同一笔平台订单在不同支付机构中可能使用不同金额单位、时间格式和枚举值。本课将实现可验证的请求组装器,把统一订单稳定转换为渠道字段,并在发送前完成精度、时区和必填项校验。
学习目标
- 将平台订单字段映射为渠道请求字段
- 正确处理金额最小单位、时间格式与枚举转换
- 通过确定性输出验证请求组装结果
先定义转换边界
请求组装只负责字段转换和本地校验,不负责发起网络请求。输入应是平台内部稳定模型,输出应是渠道请求对象或待签名字段集合。
组装过程建议固定为“校验平台字段、转换格式、映射枚举、补充渠道字段、生成确定顺序的数据”。签名和 HTTP 调用可以使用该结果,但不应反向修改订单对象。

完整组装示例
下面示例将元金额转换为分,将 Instant 转为 UTC 时间文本,并把平台支付方式映射为渠道枚举。TreeMap 用于保证字段顺序稳定,便于后续生成签名原文。
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));
}
}预期输出:
amount_cent=1990
expire_time=20260803123000
merchant_order_no=P202608030002
subject=测试订单
trade_type=NATIVE_QRTreeMap 按字段名排序,因此输出顺序可重复。实际渠道若要求固定字段顺序,应按渠道规范显式维护顺序,不要依赖普通 HashMap。
金额转换边界
金额转换必须使用 BigDecimal。从元转分可使用 movePointRight(2),再用 RoundingMode.UNNECESSARY 检查是否存在超过两位的小数;若出现 19.901,应直接拒绝,而不是静默四舍五入。
还要校验渠道最小金额、最大金额和币种精度。多币种场景不能默认所有币种都是两位小数,应由币种规则决定最小单位。
时间与枚举处理
平台内部建议统一保存 Instant,组装时再按渠道要求转换时区和格式。不要先转本地时间再猜测时区,否则部署区域变化后可能产生不同请求。
枚举映射必须穷举。未知平台值或渠道暂不支持的值应在发送前失败,不能使用 name() 直接透传,因为内部枚举名不属于外部协议。
发送前验证
组装完成后应执行三类检查:必填字段是否存在、字段长度是否超限、签名前字段值是否稳定。日志中可以记录订单号、通道编码和字段摘要,但敏感字段应脱敏。
验收时可使用固定订单输入做快照测试,确认金额、时间、枚举和字段顺序均未变化。渠道规范升级时,快照差异能直接暴露协议变更。