这一篇用 Spring Boot 完成一个可以观察结果的练习:发布一条订单创建事件,让通知和分析两个消费者分别处理,再故意制造两类失败,看看消息最终去了哪里。
练习接口只负责发布事件,不创建真实订单。通知和分析动作也只写日志。这样可以先集中理解 RabbitMQ 的链路,避免把一个省略数据库事务的示例误当作完整下单系统。
1. 工程、环境与运行顺序
示例固定使用以下版本,便于复现,不代表生产环境应选择这些版本:
| 组件 | 练习版本 |
|---|---|
| Java | 17 或更高 |
| Spring Boot | 3.3.1 |
| Spring AMQP | 由 Boot 管理,为 3.1.6 |
| RabbitMQ | 4.1.0-management |
解压后,在 rabbitmq-order 目录运行:
docker compose up -ddocker compose psmvn testmvn 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 中的声明方法如下,其中常量值与上图一致:
@BeanDeclarables 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 转换器:
@BeanJackson2JsonMessageConverter 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 是:
server: address: 127.0.0.1 port: 8083spring: 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。预期现象是:
- 发布端仍可返回 HTTP 202,因为消息被 Broker 接受。
- 分析消费者记录正常日志。
- 通知消费者抛出教学异常,不重新入队。
- 在 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 基础模型
If this article helped you, please share it with others!
Some information may be outdated






