架构与系统设计 / 系统课时
退款通道调用
退款通道调用
本课完成一条可落地的退款调用链:业务层提交统一退款指令,通道适配器负责组装渠道请求并转换受理结果,同时把超时、拒绝和结果未知区分开,避免把“已受理”误判成“退款成功”。
学习目标
- 设计统一退款指令与通道适配器边界
- 正确转换受理、拒绝和未知结果
- 使用幂等号与原退款信息保护重复调用
统一调用边界
退款应用服务只处理平台统一字段,例如退款单号、原支付单号、退款金额和原因;渠道签名、字段命名、接口地址及响应码映射都封装在适配器中。这样新增渠道时只需实现适配器,不必修改退款主流程。
渠道返回“受理成功”通常只表示请求已进入处理队列,不能直接把平台退款单更新为成功。平台应先记录渠道退款号和受理状态,再依赖异步通知或主动查询收敛最终结果。

可运行的适配器示例
下面使用 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 |
不重复盲退,先按原退款单号查询 |
| 返回重复请求 | 原结果 | 读取已存在退款记录,保持幂等 |
统一退款单号应作为渠道幂等号长期稳定使用。重试时不得生成新的退款单号,否则渠道可能把同一业务请求识别成两笔退款。
验证与边界
提交前必须校验原支付单是否成功、可退余额是否充足、币种是否一致,以及退款单号是否已存在。调用后至少保存请求摘要、渠道响应码、渠道退款号和追踪号,但日志中不得输出密钥、完整卡号或敏感报文。
测试时应覆盖正常受理、明确拒绝、重复请求、网络超时和未知响应码。尤其要验证超时后不会立即再次发起新退款,而是进入查询与补偿流程。
按自己的节奏,确认真正理解。