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

响应结果标准化

响应结果标准化

本课实现渠道响应适配层,把各渠道不同的成功码、处理中状态、错误信息和支付参数转换为统一结果。完成后,上层业务只依赖标准状态与错误码,不再直接判断渠道原始字段。

学习目标

  • 区分请求受理、支付处理中、支付成功与明确失败
  • 设计统一响应模型,并保留必要的渠道原始信息用于排查
  • 建立错误码与支付参数映射,避免渠道差异渗透到业务层

标准化的职责边界

渠道响应适配器只负责协议翻译,不负责直接修改订单。它接收已经验签、解密并解析完成的渠道响应,输出统一受理状态、统一错误码、支付参数和可追踪信息,再由支付领域服务决定是否更新订单、发起查询或返回前端。

渠道响应标准化流程

统一模型至少要回答四个问题:渠道是否受理请求、支付是否已经完成、失败原因是否可识别、前端下一步需要什么参数。不要用一个布尔值同时表达这些信息。

统一模型与主示例

下面示例使用 JDK 17 的嵌套类型构造一个可运行的渠道适配器。示例把渠道码 00 映射为成功,把 USERPAYING 映射为处理中,其余已知错误映射为统一错误码,未知状态统一标记为 UNKNOWN。

java
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> 表示动态值,实际返回内容可能不同。

text
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> 表示。

json
{
  "status": "PROCESSING",
  "errorCode": null,
  "message": "支付处理中",
  "channelTradeNo": "<ID>",
  "paymentParams": {
    "qrCode": "https://pay.example/qr/<ID>"
  }
}

验证时应检查:前端能根据 paymentParams 发起下一步操作;业务层只判断统一状态;新增渠道时只增加适配器和映射表,不修改订单核心流程。

边界与验收

标准化层必须处理空响应、缺少状态码、重复字段、非法金额格式和未知支付参数。无法可靠解释的内容宁可进入 UNKNOWN,也不要猜测为成功或失败。

验收时至少覆盖成功、受理、处理中、明确失败、未知码和空响应六类用例,并确认同一个渠道码在同步响应与异步通知中的含义是否一致。若渠道文档定义不同,应分别维护映射入口,不能共用错误假设。

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

目录与阅读设置

阅读设置

17

记录一个想法

响应结果标准化

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

登录哪都通