mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
2923 words
8 minutes
MQ 从 0 到 1(三):Spring Boot 集成 RabbitMQ
2025-09-06
2026-09-28

这一篇用 Spring Boot 完成一个可以观察结果的练习:发布一条订单创建事件,让通知和分析两个消费者分别处理,再故意制造两类失败,看看消息最终去了哪里。

练习接口只负责发布事件,不创建真实订单。通知和分析动作也只写日志。这样可以先集中理解 RabbitMQ 的链路,避免把一个省略数据库事务的示例误当作完整下单系统。

1. 工程、环境与运行顺序#

下载完整 Spring Boot 工程

示例固定使用以下版本,便于复现,不代表生产环境应选择这些版本:

组件练习版本
Java17 或更高
Spring Boot3.3.1
Spring AMQP由 Boot 管理,为 3.1.6
RabbitMQ4.1.0-management

解压后,在 rabbitmq-order 目录运行:

docker compose up -d
docker compose ps
mvn test
mvn spring-boot:run

先等 RabbitMQ 容器 healthy,再启动应用。首次执行需要下载镜像和 Maven 依赖;单独运行 mvn test 不需要启动 Broker。

三个本地端口各有用途:

  • 5673:应用连接 RabbitMQ。
  • 15673:浏览器打开 RabbitMQ 管理界面。
  • 8083:调用练习应用的 HTTP 接口。

Compose 创建 mq-demo vhost,账号为 mq_demo / local-demo-only。这些配置仅用于本机教学。完整文件已在 第二篇 展示。

工程中的主要文件如下:

rabbitmq-order/
├── pom.xml
├── compose.yaml
├── event.json
├── failure-event.json
└── src/
├── main/
│ ├── java/example/mq/
│ │ ├── RabbitOrderApplication.java
│ │ ├── RabbitOrderConfig.java
│ │ ├── OrderCreatedEvent.java
│ │ ├── OrderPublisher.java
│ │ ├── OrderConsumers.java
│ │ └── DemoController.java
│ └── resources/application.yml
└── test/java/example/mq/
├── MessagingTest.java
└── WiringTest.java

正文解释关键代码,完整类、导入和异常响应均在下载包内。

2. 先明确我们要创建的拓扑#

这一篇使用 demo. 前缀,不复用第二篇手工创建的 lab. 资源:

demo.order.events(topic)
├─ order.created → demo.order.sms
└─ order.# → demo.order.audit
上述两个业务队列处理失败且不重入队
→ demo.order.dlx(direct)
→ order.failed
→ demo.order.failed

这里有两个独立消费目的,因此使用两个业务队列。失败队列暂时不设置消费者,便于在管理界面保留并观察失败消息。

RabbitOrderConfig 中的声明方法如下,其中常量值与上图一致:

@Bean
Declarables topology() {
TopicExchange events = new TopicExchange(EXCHANGE, true, false);
DirectExchange deadLetters = new DirectExchange(DLX, true, false);
Queue sms = businessQueue(SMS);
Queue audit = businessQueue(AUDIT);
Queue failed = QueueBuilder.durable(FAILED).build();
return new Declarables(events, deadLetters, sms, audit, failed,
BindingBuilder.bind(sms).to(events).with(CREATED),
BindingBuilder.bind(audit).to(events).with("order.#"),
BindingBuilder.bind(failed).to(deadLetters).with("order.failed"));
}
private Queue businessQueue(String name) {
return QueueBuilder.durable(name)
.deadLetterExchange(DLX)
.deadLetterRoutingKey("order.failed")
.build();
}

Spring 的管理组件会在建立 Broker 连接时声明这些资源。声明不是“强制覆盖”:已有同名队列的 durable 或参数不一致时,通常会得到 PRECONDITION_FAILED。因此,不要给旧业务队列随意追加声明参数再期待应用替你迁移它。

代码中把死信参数写在队列声明上,是为了让下载示例自包含。需要动态调整的生产配置可以使用 Broker policy;调整已有队列时也要考虑消息迁移。RabbitMQ 死信配置说明

3. 消息使用 JSON,并保留稳定的事件标识#

工程使用 record 表达事件,并在构造时检查基本约定:

public record OrderCreatedEvent(
UUID eventId, String eventType, int schemaVersion,
long orderId, long userId, Instant occurredAt) {
public OrderCreatedEvent {
if (eventId == null || !"ORDER_CREATED".equals(eventType) || schemaVersion != 1
|| orderId <= 0 || userId <= 0 || occurredAt == null) {
throw new IllegalArgumentException("Invalid ORDER_CREATED v1 event");
}
}
}

eventId 是业务事件的身份,重复发布同一事件时保留它。schemaVersion = 1 与 ORDER_CREATED 是本例支持的消息契约;扩展其他事件时,要定义对应结构和处理方式。

配置 JSON 转换器:

@Bean
Jackson2JsonMessageConverter messageConverter(ObjectMapper mapper) {
return new Jackson2JsonMessageConverter(mapper, "example.mq");
}

这里复用 Spring Boot 配置的 ObjectMapper,让 Instant 等时间字段按一致方式处理;example.mq 是示例消息类型所在包。此转换器供发送模板与监听容器使用。

默认的简单转换器不会自动把所有业务对象都变成 JSON。显式配置后,消息体及 application/json 内容类型才有清楚的约定。本文使用 Spring AMQP 3.1 的类名,迁移大版本时应重新核对 API。消息转换器说明

4. 配置确认模式与失败行为#

工程里的 application.yml 是:

application.yml
server:
address: 127.0.0.1
port: 8083
spring:
rabbitmq:
host: localhost
port: 5673
username: mq_demo
password: local-demo-only
virtual-host: mq-demo
connection-timeout: 5s
publisher-confirm-type: correlated
publisher-returns: true
template:
mandatory: true
listener:
simple:
acknowledge-mode: auto
default-requeue-rejected: false
prefetch: 10
concurrency: 1
max-concurrency: 1
retry:
enabled: false

先看发送侧的三个设置:

correlated 为每次发布提供可关联的确认;publisher-returns 启用返回处理;mandatory 使没有路由到任何队列的消息能够退回给发布方。

再看消费侧:acknowledge-mode: auto 表示同步监听方法正常完成后,由 Spring 容器确认。它不等于 RabbitMQ 的协议自动确认,也不需要再手写一次 basicAck。

本例把 default-requeue-rejected 设为 false,并关闭监听重试,让失败路径容易观察:失败后不立即重新入队,交给已配置的死信路由。这不是生产环境的通用重试策略。

prefetch: 10 限制每个消费者未确认的投递数量,并不表示“每秒只处理十条”;并发数为 1,便于观察单个监听器。两个监听方法仍对应两个独立消费者。Spring 监听容器配置

5. 发送后,判断 Broker 到底有没有接受#

RabbitTemplate.convertAndSend 方法返回,不代表消费者完成业务,甚至不能独自作为可靠发布的证据。

工程通过 CorrelationData 等待发布确认,再判断是否发生退回:

public void publish(OrderCreatedEvent event, boolean unroutable) {
// Separate a publication attempt from the stable business event ID.
CorrelationData correlation = new CorrelationData(UUID.randomUUID().toString());
try {
template.convertAndSend(
RabbitOrderConfig.EXCHANGE,
unroutable ? "unmatched.created" : RabbitOrderConfig.CREATED,
event,
message -> {
message.getMessageProperties().setMessageId(event.eventId().toString());
message.getMessageProperties().setDeliveryMode(MessageDeliveryMode.PERSISTENT);
return message;
},
correlation);
CorrelationData.Confirm confirm = correlation.getFuture().get(5, TimeUnit.SECONDS);
if (correlation.getReturned() != null) {
throw new PublishFailure("UNROUTABLE", event.eventId());
}
if (!confirm.isAck()) {
throw new PublishFailure("BROKER_NACK", event.eventId());
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new PublishFailure("UNKNOWN", event.eventId());
} catch (TimeoutException | ExecutionException | AmqpException e) {
// A lost confirmation does not prove that publication failed.
throw new PublishFailure("UNKNOWN", event.eventId());
}
}

这里有两个不同的 ID:消息属性中的 messageId 使用稳定的 eventId;CorrelationData 使用本次发布尝试的唯一 ID。重发同一业务事件时,可以有新的发布尝试编号,但不能随意换掉业务事件编号。

最容易漏掉的是:Broker 的 ack 与消息退回可以同时发生。当交换机发现没有队列匹配时,仍可能确认本次发布,但 mandatory 消息已被退回。因此代码先检查 getReturned(),再决定是否当作成功。

Spring AMQP 在同时开启确认与返回时,保证返回信息先于对应 ack future 的完成可用;这也是本例采用此判断顺序的依据。发布确认与返回说明

确认等待超时、连接异常时,代码返回 UNKNOWN。这表示结果不确定,而不是证明消息从未到达。生产者盲目重发,可能造成重复消费。

为了便于理解,本例在 HTTP 线程中最多等待 5 秒的确认。高吞吐发布通常需要异步确认与持久化待发记录,不宜照搬这个阻塞等待方式。

6. 消费者保持简单,让异常表达真实结果#

通知监听器的核心代码如下:

@RabbitListener(queues = RabbitOrderConfig.SMS)
public void notifyOrder(OrderCreatedEvent event) {
if (event.orderId() == 999L) {
throw new AmqpRejectAndDontRequeueException(
"Teaching fixture: notification failure");
}
log.info("SMS_SIMULATED eventId={} orderId={}",
event.eventId(), event.orderId());
}

orderId = 999 是专门设计的失败样例,不代表真实业务规则。普通事件只记录模拟通知日志,然后正常返回,由容器确认;失败样例抛出“不重新入队”的异常,便于观察死信。

分析监听器独立监听 demo.order.audit:

@RabbitListener(queues = RabbitOrderConfig.AUDIT)
public void auditOrder(OrderCreatedEvent event) {
log.info("AUDIT_SIMULATED eventId={} orderId={}",
event.eventId(), event.orderId());
}

通知失败不会自动让分析队列里的那份消息失败。两者通过各自的队列、处理逻辑和确认独立推进。

不要在 AUTO 模式中把业务异常只打印一下就吞掉;方法正常返回,容器就可能确认消息。也不要把工作提交到普通线程池后立刻返回,让容器先于实际业务完成确认。

7. 用三个请求验证三条路径#

以下命令在解压后的工程目录执行。Windows PowerShell 使用 curl.exe;macOS 或 Linux 将它替换成 curl。

正常发布:两个消费者分别处理#

event.json 已经包含第一篇使用的合法事件。执行:

curl.exe -i -H "Content-Type: application/json" --data-binary "@event.json" http://localhost:8083/demo/events

在 Broker 和绑定正常时,预期返回 HTTP 202:

{
"eventId": "a836314d-c371-4c56-bbde-d6e9a6a6a001",
"status": "BROKER_ACCEPTED",
"note": "Consumer processing is asynchronous"
}

随后应能找到同一 eventId 的两条业务日志:SMS_SIMULATED 和 AUDIT_SIMULATED,出现顺序不固定。

消费者处理很快时,Ready 可能始终看起来是 0,所以不要只靠队列数字判断是否收到消息。

这里的成功表示发布已被 Broker 接受且没有发生无路由退回,不表示两个业务都成功。它也不检查“应该存在的所有业务绑定是否齐全”:例如通知绑定缺失而分析绑定仍匹配,发布仍可能被接受。

无法路由:退回不应被当成发布成功#

执行:

curl.exe -i -H "Content-Type: application/json" --data-binary "@event.json" "http://localhost:8083/demo/events?unroutable=true"

这个仅用于教学的开关,将 routing key 换成 unmatched.created,不匹配两条业务绑定。预期返回 HTTP 503,状态为 UNROUTABLE。

不要换成 order.unknown 测试无路由,因为它仍然匹配分析队列的 order.#。

消费失败:发布成功,通知消息进入失败队列#

执行:

curl.exe -i -H "Content-Type: application/json" --data-binary "@failure-event.json" http://localhost:8083/demo/events

该文件使用新的 eventId,订单号为 999。预期现象是:

  1. 发布端仍可返回 HTTP 202,因为消息被 Broker 接受。
  2. 分析消费者记录正常日志。
  3. 通知消费者抛出教学异常,不重新入队。
  4. 在 Broker 健康、死信路由可用的情况下,demo.order.failed 的 Ready 增加 1。

在管理界面查看失败消息的 x-death 信息,可以进一步确认原队列和原因。获取消息时注意 requeue 选项,避免观察动作本身把练习消息移除。

以上属于 真实 Broker 环境中的预期结果。当前配套工程已编译并通过离线测试,但本文重构环境未找到可用 Docker 命令,尚未执行上述 Broker 联调。

8. 重复发送、重试和死信,分别是什么#

把同一个 event.json 再发一次,本例仍会打印新的通知与分析日志。它刻意没有实现去重,方便看到:消息里有 eventId,并不等于业务已经幂等。

准备替换成真实数据库操作时,需要实现消费记录与业务更新的原子性;准备替换成真实短信时,还需要处理外部调用的幂等与结果查询。不能用内存集合给这个示例贴上“生产级可靠消费”的标签。

本例也没有自动重试。对于短暂网络故障,可以另行设计有限次数、带间隔的重试;对于不支持的消息结构等固定错误,立即重试通常没有帮助。

死信队列只是一个可以观察和处置失败消息的出口。它不会自动修复数据,也不应该无限回灌。本文使用单节点普通队列,普通死信转发的故障保障有限,不能据此宣称高可用或恰好处理一次。死信转发的边界

9. 已验证什么,还缺什么#

下载工程的 11 项测试覆盖:

检查验证范围
JSON 往返与字段约束事件身份、时间和版本约定
队列与绑定声明两类订阅及死信出口
发布确认与消息退回ack 伴随退回时不能误报成功
连接与确认异常结果不确定时返回 UNKNOWN
监听器与 Spring 装配JSON 转换器、AUTO 模式、独立监听

这些测试不连接 RabbitMQ。Mock 的发布结果能检查分支判断,不能证明实际 Broker 的投递、确认和死信行为;第二篇的管理界面实验与本篇的三个请求仍需在可用环境中验证。

接入真实业务前,还要补数据库 Outbox、消费者幂等、有界重试、失败处置和监控。可以回看 第一篇中的可靠性边界,逐项决定实现位置。

结束练习时先停止 Java 应用,再运行:

docker compose stop

此命令保留容器与数据卷。下次继续练习可以运行 docker compose start,不需要为了重跑示例清空已有消息。

上一篇:RabbitMQ 基础模型

Share

If this article helped you, please share it with others!

MQ 从 0 到 1(三):Spring Boot 集成 RabbitMQ
https://mizuki.mysqil.com/posts/message-queue-03-springboot-rabbitmq/
Author
梦幻晨风
Published at
2025-09-06
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents