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

渠道回调接收

渠道回调接收

渠道支付完成后,结果通常通过异步 HTTP 通知送达平台。本课实现一个可落地的接收入口:完整保存原始报文与请求头,只在持久化成功后快速返回渠道确认,并把耗时的订单处理留给后台任务。

学习目标

  • 设计稳定的渠道回调入口与快速响应边界
  • 原样记录请求头、请求体和接收时间,便于验签与追查
  • 使用回调收件箱隔离网络接收与业务处理

接收链路与响应边界

回调入口只承担“接收、落库、确认”三件事。订单查询、状态更新、通知商户和记账都可能访问多个服务,不应阻塞渠道请求,否则渠道会因超时重试,进一步放大流量。

渠道回调接收与异步处理链路

可靠边界应放在“原始通知已持久化”之后。只有数据库写入成功才返回成功;写入失败则返回非成功状态,让渠道按其规则重试。这样即使应用随后重启,后台仍可从收件箱继续处理。

实现持久化与接收接口

建立原始报文收件箱

原始请求体建议使用二进制字段保存,避免字符集转换或 JSON 重新序列化改变字节内容。请求头保存为 JSON,后续验签、审计和问题复现都可使用同一份证据。

sql
CREATE TABLE callback_inbox (
    id BIGINT NOT NULL AUTO_INCREMENT,
    channel VARCHAR(32) NOT NULL,
    notification_id VARCHAR(128) NULL,
    request_headers JSON NOT NULL,
    raw_body MEDIUMBLOB NOT NULL,
    process_status VARCHAR(16) NOT NULL DEFAULT 'PENDING',
    retry_count INT NOT NULL DEFAULT 0,
    received_at DATETIME(3) NOT NULL,
    processed_at DATETIME(3) NULL,
    last_error VARCHAR(500) NULL,
    PRIMARY KEY (id),
    KEY idx_status_received (process_status, received_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

预期结果

text
callback_inbox 表创建成功;待处理记录可通过 process_status=PENDING 与 received_at 索引顺序读取。

notification_id 暂时允许为空,因为不同渠道的通知编号字段并不统一。下一课会把渠道编号或稳定业务字段转换为幂等键,并增加唯一约束。

实现快速接收接口

下面是 Spring Boot 3 与 Spring JDBC 的片段示例,依赖已创建的 callback_inbox 表。控制器接收 byte[],服务在事务中保存原始内容,提交成功后立即返回渠道约定的确认文本。

java
package com.example.payment.callback;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.sql.Timestamp;
import java.time.Instant;
import java.util.Map;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/callbacks")
public class ChannelCallbackController {
    private final CallbackInboxService inboxService;

    public ChannelCallbackController(CallbackInboxService inboxService) {
        this.inboxService = inboxService;
    }

    @PostMapping(value = "/{channel}", consumes = MediaType.ALL_VALUE)
    public ResponseEntity<String> receive(
            @PathVariable String channel,
            @RequestHeader HttpHeaders headers,
            @RequestBody byte[] rawBody) {
        inboxService.capture(channel, headers.toSingleValueMap(), rawBody);
        return ResponseEntity.ok("success");
    }
}

@Service
class CallbackInboxService {
    private final JdbcTemplate jdbcTemplate;
    private final ObjectMapper objectMapper;

    CallbackInboxService(JdbcTemplate jdbcTemplate, ObjectMapper objectMapper) {
        this.jdbcTemplate = jdbcTemplate;
        this.objectMapper = objectMapper;
    }

    @Transactional
    public void capture(String channel, Map<String, String> headers, byte[] rawBody) {
        if (rawBody.length == 0) {
            throw new IllegalArgumentException("callback body must not be empty");
        }
        jdbcTemplate.update(
                "INSERT INTO callback_inbox " +
                "(channel, request_headers, raw_body, received_at) VALUES (?, ?, ?, ?)",
                channel,
                toJson(headers),
                rawBody,
                Timestamp.from(Instant.now()));
    }

    private String toJson(Map<String, String> headers) {
        try {
            return objectMapper.writeValueAsString(headers);
        } catch (JsonProcessingException exception) {
            throw new IllegalArgumentException("invalid callback headers", exception);
        }
    }
}

接口启动后可发送一条模拟通知。实际端口可能不同,请把 <PORT> 替换为应用监听端口。

bash
curl -i -X POST "http://localhost:<PORT>/callbacks/demo"   -H "Content-Type: application/json"   -H "X-Notification-Id: N1001"   --data-binary '{"notificationId":"N1001","status":"SUCCESS"}'

预期输出

text
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8

success

同时,callback_inbox 中应新增一条 PENDING 记录,raw_body 与发送字节一致。HTTP 日期、连接头等动态响应头可能因服务器配置不同而变化。

失败处理与验收

入口层应限制请求体大小、记录追踪标识,并为数据库写入设置短超时。不要在日志中直接打印完整银行卡号、密钥或个人信息;排查需要原文时,应通过受控审计查询读取收件箱。

验收时分别模拟正常请求、空请求体、数据库不可用和重复通知。正常请求应快速返回并留下记录;空请求应被拒绝;数据库写入失败不得返回成功;重复通知即使暂时产生多条原始记录,也不能在后续业务处理中重复改写订单。

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

目录与阅读设置

阅读设置

17

记录一个想法

渠道回调接收

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

登录哪都通