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

退款通道调用

退款通道调用

本课完成一条可落地的退款调用链:业务层提交统一退款指令,通道适配器负责组装渠道请求并转换受理结果,同时把超时、拒绝和结果未知区分开,避免把“已受理”误判成“退款成功”。

学习目标

  • 设计统一退款指令与通道适配器边界
  • 正确转换受理、拒绝和未知结果
  • 使用幂等号与原退款信息保护重复调用

统一调用边界

退款应用服务只处理平台统一字段,例如退款单号、原支付单号、退款金额和原因;渠道签名、字段命名、接口地址及响应码映射都封装在适配器中。这样新增渠道时只需实现适配器,不必修改退款主流程。

渠道返回“受理成功”通常只表示请求已进入处理队列,不能直接把平台退款单更新为成功。平台应先记录渠道退款号和受理状态,再依赖异步通知或主动查询收敛最终结果。

统一退款通道调用时序

可运行的适配器示例

下面使用 Java 17 编写单文件示例。示例通道返回 ACCEPTED,应用服务将其转换为平台内部的 PROCESSING;如果调用抛出超时类异常,则转换为 UNKNOWN,等待后续查询,而不是直接判定失败。

java
import java.math.BigDecimal;
import java.util.Objects;

public class RefundChannelDemo {

    enum RefundState {
        PROCESSING, FAILED, UNKNOWN
    }

    record RefundCommand(
            String refundNo,
            String originalPaymentNo,
            BigDecimal amount,
            String currency,
            String reason) {
    }

    record ChannelRefundRequest(
            String merchantRefundNo,
            String channelPaymentNo,
            BigDecimal amount,
            String currency,
            String reason) {
    }

    record ChannelRefundResponse(
            String code,
            String channelRefundNo,
            String message) {
    }

    record RefundAcceptance(
            RefundState state,
            String channelRefundNo,
            String message) {
    }

    interface ChannelRefundAdapter {
        ChannelRefundResponse refund(ChannelRefundRequest request);
    }

    static final class DemoChannelAdapter implements ChannelRefundAdapter {
        @Override
        public ChannelRefundResponse refund(ChannelRefundRequest request) {
            Objects.requireNonNull(request.merchantRefundNo());
            if (request.amount().signum() <= 0) {
                return new ChannelRefundResponse(
                        "REJECTED", null, "退款金额必须大于 0");
            }
            // 渠道退款号只表示渠道已受理,不代表资金已经退回。
            return new ChannelRefundResponse(
                    "ACCEPTED", "CR-" + request.merchantRefundNo(), "已受理");
        }
    }

    static final class RefundApplicationService {
        private final ChannelRefundAdapter adapter;

        RefundApplicationService(ChannelRefundAdapter adapter) {
            this.adapter = adapter;
        }

        RefundAcceptance submit(
                RefundCommand command,
                String channelPaymentNo) {
            ChannelRefundRequest request = new ChannelRefundRequest(
                    command.refundNo(),
                    channelPaymentNo,
                    command.amount(),
                    command.currency(),
                    command.reason());

            try {
                ChannelRefundResponse response = adapter.refund(request);
                return switch (response.code()) {
                    case "ACCEPTED" -> new RefundAcceptance(
                            RefundState.PROCESSING,
                            response.channelRefundNo(),
                            response.message());
                    case "REJECTED" -> new RefundAcceptance(
                            RefundState.FAILED,
                            response.channelRefundNo(),
                            response.message());
                    default -> new RefundAcceptance(
                            RefundState.UNKNOWN,
                            response.channelRefundNo(),
                            "未识别的渠道结果");
                };
            } catch (RuntimeException ex) {
                // 网络超时无法证明渠道未处理,因此进入结果未知状态。
                return new RefundAcceptance(
                        RefundState.UNKNOWN, null, ex.getMessage());
            }
        }
    }

    public static void main(String[] args) {
        RefundCommand command = new RefundCommand(
                "<REFUND_ID>",
                "<PAYMENT_ID>",
                new BigDecimal("88.00"),
                "CNY",
                "用户取消订单");

        RefundApplicationService service =
                new RefundApplicationService(new DemoChannelAdapter());

        RefundAcceptance result =
                service.submit(command, "<CHANNEL_PAYMENT_ID>");

        System.out.printf(
                "state=%s, channelRefundNo=%s, message=%s%n",
                result.state(),
                result.channelRefundNo(),
                result.message());
    }
}

预期输出:

text
state=PROCESSING, channelRefundNo=CR-<REFUND_ID>, message=已受理

实际渠道退款号、请求时间和日志追踪号会不同,应以渠道响应和平台记录为准。

结果转换规则

渠道表现 平台受理结果 后续动作
明确受理并返回渠道退款号 PROCESSING 保存渠道退款号,等待通知或查询
明确拒绝且确认未受理 FAILED 记录失败码和原因,允许按规则重试
超时、连接中断、响应无法解析 UNKNOWN 不重复盲退,先按原退款单号查询
返回重复请求 原结果 读取已存在退款记录,保持幂等

统一退款单号应作为渠道幂等号长期稳定使用。重试时不得生成新的退款单号,否则渠道可能把同一业务请求识别成两笔退款。

验证与边界

提交前必须校验原支付单是否成功、可退余额是否充足、币种是否一致,以及退款单号是否已存在。调用后至少保存请求摘要、渠道响应码、渠道退款号和追踪号,但日志中不得输出密钥、完整卡号或敏感报文。

测试时应覆盖正常受理、明确拒绝、重复请求、网络超时和未知响应码。尤其要验证超时后不会立即再次发起新退款,而是进入查询与补偿流程。

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

目录与阅读设置

阅读设置

17

记录一个想法

退款通道调用

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

登录哪都通