5.5 与 Spring Boot 集成

5.5 与 Spring Boot 集成

本节摘要：Spring AMQP 把前几章的手工代码翻译成注解与自动配置：连接池化自动恢复、RabbitTemplate 托管发送、监听容器托管消费、重试与死信声明式配置。本节用 Java 重写全册的可靠链路——同一套机制，两种语言的对照，也让 Spring 团队能直接落地第 3 章的方案。

工程化整理的后两站是"框架落地"。前面所有示例都是 Python 手写的裸调用——连接要自己复用、确认要自己等、重试要自己数。Java 团队不必如此：Spring AMQP 已把这些样板全部托管。本节把第 3 章的可靠链路用 Spring 风格重写一遍，看"托管"到底省掉了什么。

依赖与自动配置

起步只要一个依赖加一段配置，连接工厂、模板、监听容器全部自动就位：

// 构建配置：引入 spring-boot-starter-amqp 后，以下 yaml 即可工作
// spring:
//   rabbitmq:
//     host: mq.internal
//     port: 5672
//     username: orders_svc
//     password: ${MQ_PASSWORD}      // 从环境变量或密钥系统注入
//     virtual-host: /orders
//     publisher-confirm-type: correlated   // 发布确认（第 3 章三件套之三）
//     publisher-returns: true
//     listener:
//       simple:
//         acknowledge-mode: manual        // 手动签收（三件套配套）
//         prefetch: 20                    // 限流（3.1 节）
//         retry:
//           enabled: true
//           max-attempts: 3               // 声明式重试
//           initial-interval: 2000
​

对照第 3 章的 Python 版本：连接单例、通道管理、心跳协商、消费者线程模型，这些手写时最容易出错的底座，自动配置全部接管。被托管的不是代码，是出错的自由度——这就是框架集成的真实价值。

发送侧：模板加确认回调

RabbitTemplate 对应 pika 的通道，发布确认通过回调表达：

@Component
public class OrderEventPublisher {

    private final RabbitTemplate rabbit;

    public OrderEventPublisher(RabbitTemplate rabbit) {
        this.rabbit = rabbit;
        // correlated 确认模式的回执：成功与丢失各有一条通道
        this.rabbit.setConfirmCallback((data, ack, cause) -> {
            if (!ack) {
                log.error("Broker 未确认，转入补偿: {}", cause);
                compensation.save(data);
            }
        });
        this.rabbit.setReturnsCallback(returned ->
            // mandatory 退回：路由失败在此接住（2.6 节三岔口）
            log.error("消息不可路由: {}", returned.getMessage()));
    }

    public void publishOrderCreated(OrderCreatedEvent event) {
        rabbit.convertAndSend("order.events", "order.created", event,
            msg -> {
                msg.getMessageProperties().setDeliveryMode(
                    MessageDeliveryMode.PERSISTENT);      // 持久化（三件套之二）
                msg.getMessageProperties().setMessageId(event.getEventId());
                return msg;
            });
    }
}
​

结果与解读：三件套在 Java 里化作了两个配置项加两个回调。特别提示 setMandatory(true) 需要显式开启（或配置 publisher-returns 加 template 的 mandatory 属性），退回回调才会生效——第 2 章讲过"回执要主动要"，框架里同样成立。

消费侧：注解监听加死信

消费端的核心是 @RabbitListener 注解，手动签收与死信配合成完整防线：

@Component
public class OrderEventConsumer {

    @RabbitListener(bindings = @QueueBinding(
        value = @org.springframework.amqp.rabbit.annotation.Queue(
            value = "orders.events.q", durable = "true",
            arguments = @Argument(name = "x-dead-letter-exchange",
                                  value = "orders.dlx")),   // 死信出口（3.3 节）
        exchange = @Exchange(value = "order.events",
                             type = ExchangeTypes.TOPIC),
        key = "order.#"))
    public void onOrderEvent(OrderCreatedEvent event, Channel channel,
                             @Header(AmqpHeaders.DELIVERY_TAG) long tag)
            throws IOException {
        try {
            orderService.handle(event);
            channel.basicAck(tag, false);                    // 处理成功才签收
        } catch (BusinessException e) {
            // 业务性错误：不重试，直接进死信人工处理
            channel.basicNack(tag, false, false);
        }
    }
}
​

结果与解读：队列声明、绑定、监听容器、线程池，一个注解全部带上；重试配置在 yaml 里声明式完成，max-attempts 用尽后的消息按配置进入死信流程。对照 3.1 节的 Python 手写版：逻辑一一对应，样板少了一半以上。变式：幂等防线在框架下同样要自己写——监听器收到重复投递（至少一次语义的必然结果）时，靠消息 ID 去重表挡住，框架不替你做业务幂等。

集成测试与联调

Spring 提供的测试支撑让消息代码可测：测试配置里连一个本地 Broker（或 Testcontainers 拉起的容器），用模板发、监听器收、再断言落库结果，链路级测试不到十行。团队实践建议：把"发一条测试事件走全链路"做成健康检查端点，上线巡检与 4.4 节的业务探针共用同一套代码。

💡 关键直觉：框架接管的是"机制"，不是"决策"。签收时机、重试次数、死信策略这些第 3 章想清楚的取舍，在 Spring 里只是换个语法重新表达——先想清楚再写注解，顺序反了就是灾难现场。

⚠️ 常见坑：自动重试与手动签收混用时的语义陷阱。声明式 retry 在监听器抛异常时于容器层重试，重试耗尽后消息被拒绝——若此时没配死信，消息直接蒸发。retry 配置必须与死信队列成对出现，这是一条结对纪律。

本节要点回顾

• 托管清单：连接池化与恢复、线程模型、重试框架，由自动配置接管；
• 发送三件套：correlated 确认加回调、persistent 属性、mandatory 退回；
• 消费注解：QueueBinding 一注解完成声明绑定监听，签收仍要手动；
• 结对纪律：retry 必配死信，幂等必须自写，框架不管业务语义；
• 测试支撑：容器化 Broker 加模板收发断言，链路测试成本极低。

框架层落地完成。最后一站进平台层：Docker 与 Kubernetes 上把这套系统部署成型。