架构与系统设计 / 系统课时
响应结果标准化
响应结果标准化
本课实现渠道响应适配层,把各渠道不同的成功码、处理中状态、错误信息和支付参数转换为统一结果。完成后,上层业务只依赖标准状态与错误码,不再直接判断渠道原始字段。
学习目标
- 区分请求受理、支付处理中、支付成功与明确失败
- 设计统一响应模型,并保留必要的渠道原始信息用于排查
- 建立错误码与支付参数映射,避免渠道差异渗透到业务层
标准化的职责边界
渠道响应适配器只负责协议翻译,不负责直接修改订单。它接收已经验签、解密并解析完成的渠道响应,输出统一受理状态、统一错误码、支付参数和可追踪信息,再由支付领域服务决定是否更新订单、发起查询或返回前端。

统一模型至少要回答四个问题:渠道是否受理请求、支付是否已经完成、失败原因是否可识别、前端下一步需要什么参数。不要用一个布尔值同时表达这些信息。
统一模型与主示例
下面示例使用 JDK 17 的嵌套类型构造一个可运行的渠道适配器。示例把渠道码 00 映射为成功,把 USERPAYING 映射为处理中,其余已知错误映射为统一错误码,未知状态统一标记为 UNKNOWN。
import java.util.Map;
public class ChannelResponseAdapterDemo {
public static void main(String[] args) {
ChannelRawResponse raw = new ChannelRawResponse(
"USERPAYING",
"等待用户完成付款",
"CH202608030001",
Map.of("qrCode", "https://pay.example/qr/<ID>")
);
UnifiedPaymentResult result = adapt(raw);
System.out.println("status=" + result.status());
System.out.println("errorCode=" + result.errorCode());
System.out.println("channelTradeNo=" + result.channelTradeNo());
System.out.println("paymentParams=" + result.paymentParams());
}
static UnifiedPaymentResult adapt(ChannelRawResponse raw) {
if (raw == null || raw.code() == null || raw.code().isBlank()) {
return new UnifiedPaymentResult(
PaymentStatus.UNKNOWN,
"CHANNEL_RESPONSE_INVALID",
"渠道响应缺少状态码",
null,
Map.of(),
null
);
}
return switch (raw.code()) {
case "00" -> new UnifiedPaymentResult(
PaymentStatus.SUCCESS,
null,
"支付成功",
raw.channelTradeNo(),
sanitizePaymentParams(raw.paymentParams()),
raw.code()
);
case "ACCEPTED" -> new UnifiedPaymentResult(
PaymentStatus.ACCEPTED,
null,
"渠道已受理",
raw.channelTradeNo(),
sanitizePaymentParams(raw.paymentParams()),
raw.code()
);
case "USERPAYING", "PROCESSING" -> new UnifiedPaymentResult(
PaymentStatus.PROCESSING,
null,
"支付处理中",
raw.channelTradeNo(),
sanitizePaymentParams(raw.paymentParams()),
raw.code()
);
case "BALANCE_NOT_ENOUGH" -> new UnifiedPaymentResult(
PaymentStatus.FAILED,
"PAYMENT_BALANCE_NOT_ENOUGH",
"余额不足",
raw.channelTradeNo(),
Map.of(),
raw.code()
);
default -> new UnifiedPaymentResult(
PaymentStatus.UNKNOWN,
"CHANNEL_STATUS_UNKNOWN",
"无法识别渠道状态",
raw.channelTradeNo(),
Map.of(),
raw.code()
);
};
}
static Map<String, String> sanitizePaymentParams(Map<String, String> source) {
if (source == null || source.isEmpty()) {
return Map.of();
}
// 只透传上层真正需要的支付参数,防止渠道内部字段泄露。
return source.entrySet().stream()
.filter(entry -> switch (entry.getKey()) {
case "qrCode", "payUrl", "token", "form" -> true;
default -> false;
})
.collect(java.util.stream.Collectors.toUnmodifiableMap(
Map.Entry::getKey,
Map.Entry::getValue
));
}
enum PaymentStatus {
ACCEPTED,
PROCESSING,
SUCCESS,
FAILED,
UNKNOWN
}
record ChannelRawResponse(
String code,
String message,
String channelTradeNo,
Map<String, String> paymentParams
) {
}
record UnifiedPaymentResult(
PaymentStatus status,
String errorCode,
String message,
String channelTradeNo,
Map<String, String> paymentParams,
String rawCode
) {
}
}预期输出如下。示例中的 URL 使用 <ID> 表示动态值,实际返回内容可能不同。
status=PROCESSING
errorCode=null
channelTradeNo=CH202608030001
paymentParams={qrCode=https://pay.example/qr/<ID>}这个结果只能说明支付仍在处理中,不能据此把订单更新为成功。业务层应保存渠道流水号,并按渠道规则安排主动查询或等待异步通知。
状态映射规则
统一状态应表达业务事实,而不是渠道文案。ACCEPTED 表示渠道已接收请求但尚未开始或完成支付;PROCESSING 表示交易正在推进;SUCCESS 表示已有明确成功证据;FAILED 表示渠道明确拒绝且当前请求不会自然转为成功;UNKNOWN 表示结果无法判断,需要查询或人工排查。
| 渠道事实 | 统一状态 | 上层动作 |
|---|---|---|
| 已受理,尚无支付结果 | ACCEPTED |
保存请求信息,等待通知或查询 |
| 用户支付中或银行处理中 | PROCESSING |
保持订单处理中,按策略查询 |
| 明确返回支付成功 | SUCCESS |
幂等更新订单并触发后续事件 |
| 明确拒绝且不可继续 | FAILED |
记录统一错误码并返回可理解提示 |
| 超时、空响应或未知代码 | UNKNOWN |
禁止判失败,优先查询真实状态 |
网络超时不能直接映射为 FAILED,因为渠道可能已经受理并扣款。此类结果通常应进入 UNKNOWN,随后使用商户订单号或渠道请求号查询。
错误码与支付参数
统一错误码面向平台业务,渠道原始码面向排查。两者应同时保留,但对外接口只暴露稳定的统一错误码,例如 PAYMENT_BALANCE_NOT_ENOUGH、CHANNEL_RATE_LIMITED、CHANNEL_CONFIG_INVALID 和 CHANNEL_STATUS_UNKNOWN。
支付参数必须采用白名单提取。二维码链接、收银台跳转地址、支付令牌和表单内容可以进入统一结果;签名串、证书序列、渠道内部路由字段和完整原始报文不得返回给前端。
统一接口响应可以保持如下结构。该 JSON 是数据结构示例,动态流水号使用 <ID> 表示。
{
"status": "PROCESSING",
"errorCode": null,
"message": "支付处理中",
"channelTradeNo": "<ID>",
"paymentParams": {
"qrCode": "https://pay.example/qr/<ID>"
}
}验证时应检查:前端能根据 paymentParams 发起下一步操作;业务层只判断统一状态;新增渠道时只增加适配器和映射表,不修改订单核心流程。
边界与验收
标准化层必须处理空响应、缺少状态码、重复字段、非法金额格式和未知支付参数。无法可靠解释的内容宁可进入 UNKNOWN,也不要猜测为成功或失败。
验收时至少覆盖成功、受理、处理中、明确失败、未知码和空响应六类用例,并确认同一个渠道码在同步响应与异步通知中的含义是否一致。若渠道文档定义不同,应分别维护映射入口,不能共用错误假设。