SpringBoot整合RabbitMQ实现接发消息

做后端这些年，消息队列几乎是每个项目都躲不开的东西。SpringBoot整合RabbitMQ可以算是这个组合里最经典的方案之一，脚手架一拉依赖就能跑，但很多人的项目止步于把消息发出去、把消息收进来，一旦涉及到交换机选型、消息可靠性、虚拟主机权限这些生产级问题，就开始懵了。这篇文章把我从环境搭建到代码落地、再到线上排障的完整经验整理出来，适合刚接触RabbitMQ的SpringBoot开发者，也适合已经跑通Demo但想在项目里用得踏实一点的同学。

先说说为什么选RabbitMQ而不是Kafka或RocketMQ。如果你的业务是异步任务、流量削峰、系统解耦、延迟消息这类场景，RabbitMQ的延迟低、路由灵活、生态完善，上手成本也低；Kafka强在吞吐量和大数据管道，RocketMQ强在事务消息和顺序消息的可靠性。大部分常规业务系统用RabbitMQ完全够了。这个选型问题，我放到第四部分展开讲，先把基础链路跑通。

1. 先把环境跑起来：RabbitMQ安装与后台管理里最容易被卡住的环节

1.1 本地开发环境怎么装最省心

先说Windows环境下怎么装RabbitMQ。RabbitMQ是Erlang语言写的，所以装之前必须先装Erlang，而且版本要对上。很多人栽跟头的第一站就是这里——装了一个太新的Erlang，结果RabbitMQ启动直接失败，日志里全是init相关的报错。

我建议直接用RabbitMQ官方维护的版本对照表来选，比如RabbitMQ 3.13.x对应Erlang 26.x，RabbitMQ 4.0.x对应Erlang 27.x。装的时候注意两点：

• Erlang安装路径不要带空格，装到C:\erl这种简单路径，避免后续环境变量解析出问题。
• 装完Erlang后，手动确认一下erl -version能正常输出，再继续装RabbitMQ。

安装包直接去GitHub的releases页面下载对应的Windows安装程序，下载慢的话可以找国内镜像站。Mac用户直接brew install rabbitmq一条命令搞定，管理员权限都帮你配置好了，比Windows省心得多。

最省心的方式是Docker。本地只要装了Docker Desktop，一条命令就跑起来了：

docker run -d --name rabbitmq \ -p 5672:5672 -p 15672:15672 \ -e RABBITMQ_DEFAULT_USER=admin \ -e RABBITMQ_DEFAULT_PASS=admin123 \ rabbitmq:4.0-management

这里解释一下端口：5672是AMQP协议端口，服务端和客户端通信走这个；15672是Web管理界面端口，浏览器访问http://localhost:15672看到的那个控制台。management后缀的镜像自带管理插件，不带的版本进去还要手动rabbitmq-plugins enable rabbitmq_management，多一步操作没必要。

1.2 管理界面能打开，但admin账号不能创建虚拟主机怎么办

这个问题在相关热词里出现了，我猜你们肯定有人遇到：Docker部署完RabbitMQ之后，浏览器能打开管理界面，用admin账号也能登录，但点进Virtual Hosts创建新虚拟主机，它就提示没有权限或者按钮直接是灰的。

先说结论：镜像通过RABBITMQ_DEFAULT_USER和RABBITMQ_DEFAULT_PASS创建的这个admin用户，默认只被赋予了根虚拟主机/的权限，并没有管理员级别的全部权限。管理界面里很多管理操作——比如创建虚拟主机、管理其他用户、查看全局统计——都需要用户拥有administrator标签才能做。

排查和修复步骤：

# 进入容器 docker exec -it rabbitmq bash # 查看admin用户当前权限和标签 rabbitmqctl list_users # 给admin用户打上administrator标签 rabbitmqctl set_user_tags admin administrator # 查看默认虚拟主机权限 rabbitmqctl list_permissions # 给admin配置根虚拟主机权限（如果缺失） rabbitmqctl set_permissions -p / admin ".*" ".*" ".*"

设置完之后回管理界面刷新，创建虚拟主机的入口就恢复了。这里也解释一下，set_permissions -p后面那个".*" ".*" ".*"分别代表配置权限、写权限、读权限，全给.*就是允许所有操作。生产环境按需收窄，开发环境图省事全放开。

还有一种情况：你用的是rabbitmqctl add_user创建的用户，Web管理界面却报"不能连接到服务器"。这种问题多半不是用户本身的问题，而是节点名解析异常。RabbitMQ的节点在启动时会以主机名生成一个标识，如果你改过机器名或者hosts文件里没有对应映射，CLI连节点就会出现unable to connect to node这类错误。解决方法是把主机名写进hosts，比如127.0.0.1 你的主机名，然后重启RabbitMQ服务。

1.3 Erlang版本太高或太低，RabbitMQ启动失败

再补充一个启动失败的常见原因：RabbitMQ和Erlang版本不兼容。启动失败时的现象是服务起不来，Windows事件查看器里能看到Erlang崩溃记录，Docker容器则是反复重启。如果真是版本问题，日志里一般会提示RabbitMQ is configured to use more than X GB memory或者直接出现The Erlang cookie相关的报错（后者多半是cookie不一致）。

快速判断方法：

• 如果是Windows，打开命令行执行erl -version，和RabbitMQ版本对照表比对。
• 如果是Docker，检查一下镜像标签和对应Erlang版本的匹配关系，官方镜像一般不会配错，你只要别用过旧的Erlang镜像去跑新RabbitMQ就行。

这里再提一个我踩过的坑：Windows上如果之前装过Erlang，后来升级RabbitMQ时忘了同步升级Erlang，最容易出现这种问题。升级RabbitMQ之前，先确认版本对照表。

2. SpringBoot工程搭建：依赖、配置与序列化风格的取舍

2.1 依赖引入和关键配置项

SpringBoot整合RabbitMQ的接入成本非常低，核心依赖就一个：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-amqp</artifactId> </dependency>

版本不用指定，跟着SpringBoot的父依赖走。我是用SpringBoot 2.7.x和3.x都验证过这段代码是可以跑的，Spring Boot 3.x注意JDK要17以上。

然后在application.yml里写连接配置：

spring: rabbitmq: host: localhost port: 5672 username: admin password: admin123 virtual-host: / publisher-confirm-type: correlated publisher-returns: true listener: simple: acknowledge-mode: manual prefetch: 10 concurrency: 3 max-concurrency: 10

这里的配置项一个一个说清楚：

• virtual-host：指定连接哪个虚拟主机。RabbitMQ的虚拟主机是资源隔离单元，不同业务可以创建不同的虚拟主机，互不干扰。开发环境用/就够了，生产环境建议按业务拆分，比如/order-service、/payment-service，避免消息互相串。
• publisher-confirm-type: correlated：开启发布确认。这条配置保证消息从生产者发到Broker时，Broker会回调确认——这是解决消息丢失的第一道保险，后面第五部分还会细讲。
• listener.simple.acknowledge-mode: manual：消费者手动ACK。默认是自动ACK，消息一被接收到就确认，如果消费逻辑没处理完就抛异常，消息会丢。手动ACK的意思是你在代码里确认这条消息处理成功了，才告诉Broker可以删了。
• prefetch: 10：每个消费者一次性预取的消息条数。这个参数直接影响消费吞吐量，设太大会导致消息分不到其他消费者，设太小浪费网络往返。
• concurrency和max-concurrency：消费者线程数量。还记得配置里那个listener.simple吗，它就是控制@RabbitListener注解监听器线程池的。

2.2 为什么要把默认的消息转换器换成JSON

SpringBoot的AMQP starter默认带的SimpleMessageConverter用的是Java序列化，也就是消息在传输前会被序列化成Java二进制格式。这个方案有两个硬伤：

• Java序列化体积大、效率低，跨语言基本没法用。
• RabbitMQ管理界面看到的消息内容是一堆乱码，排查问题非常痛苦。

所以实际项目里，我第一步一定是把消息转换器替换成Jackson2JsonMessageConverter，让消息在管道里以JSON文本的形式流转。操作起来很简单，在配置类里声明一个MessageConverter的Bean：

@Bean public MessageConverter jacksonMessageConverter() { return new Jackson2JsonMessageConverter(); }

SpringBoot会自动检测到这个Bean并注入到RabbitTemplate和监听器容器里。配置了JSON转换器之后，无论发送还是接收，消息体都会统一走JSON序列化/反序列化。管理界面上点开一条消息，能直接看到可读的JSON内容，排错的时候省下无数脑细胞。

还有个细节：如果你接收消息用的DTO类，JSON反序列化时要注意类必须有默认构造函数，或者用@JsonProperty标注字段名。我遇到过同事把字段名从messageId改成msgId后，消费方没同步改，结果反序列化出来一堆null——问题就出在Jackson的字段映射上。

2.3 CachingConnectionFactory的隐性能力

配置里我们不需要显式声明连接工厂，SpringBoot自动配置的CachingConnectionFactory已经帮我们创建好了。它的核心能力是缓存——它在RabbitTemplate、@RabbitListener消费者之间共享一个物理连接，但这个共享不是简单复用一个Connection，而是维护了一组Channel。RabbitMQ的信道模型是这样的：建立一条TCP长连接（Connection），在这条连接上开很多轻量的Channel做消息收发，Channel复用远比每次都建TCP连接高效得多。

你可以在代码里通过自定义ConnectionFactory来调整缓存参数：

@Bean public CachingConnectionFactory connectionFactory(ConnectionFactoryConfigurer configurer) { CachingConnectionFactory factory = new CachingConnectionFactory(); factory.setHost("localhost"); factory.setPort(5672); factory.setUsername("admin"); factory.setPassword("admin123"); factory.setVirtualHost("/"); factory.setPublisherConfirmType(CachingConnectionFactory.ConfirmType.CORRELATED); factory.setChannelCacheSize(25); return factory; }

channelCacheSize默认是25，如果并发量比较高，可以适当调大。这里提醒一句话：开发的时候发现一条消息收得慢，先别急着调并发和prefetch，先看看是不是连接工厂的缓存设置不合适，再去看代码逻辑。

3. 接发消息的核心代码：从最简单的Hello World到带交换机路由的完整实现

3.1 最基础的队列收发：Hello World版本

先写一个最简单的版本，让消息能发出去、能收进来。这种方式不需要声明交换机，消息直接发到队列里，本质上用的是RabbitMQ默认的直连交换机（默认交换机绑定每个队列，路由键就是队列名）。

// 发送端 @Component public class MessageSender { @Autowired private RabbitTemplate rabbitTemplate; public void sendSimple(String message) { rabbitTemplate.convertAndSend("hello.queue", message); } }

// 接收端 @Component public class MessageReceiver { @RabbitListener(queues = "hello.queue") public void onMessage(String message) { System.out.println("收到消息: " + message); } }

这里有个隐含约定：convertAndSend("hello.queue", message)实际上发给默认交换机，路由键是hello.queue，然后默认交换机会精确匹配同名的队列hello.queue。所以如果队列不存在，消息会直接丢失，这一点生产环境千万不要这么用。上面的写法只适合本地练手，理解一下消息怎么流转就行。

如果队列不存在，接收端会报Reply queue not found这种错。所以实际项目中，队列、交换机、绑定关系都是在配置类里预先声明的，没有隐式创建这一说。

3.2 完整版：声明队列、交换机、绑定关系

生产环境里我习惯把队列和交换机显式声明在配置类中：

@Configuration public class RabbitConfig { public static final String EXCHANGE_NAME = "order.exchange"; public static final String QUEUE_NAME = "order.queue"; public static final String ROUTING_KEY = "order.create"; @Bean public DirectExchange orderExchange() { return new DirectExchange(EXCHANGE_NAME, true, false); } @Bean public Queue orderQueue() { return QueueBuilder.durable(QUEUE_NAME) .deadLetterExchange(EXCHANGE_NAME.concat(".dlx")) .deadLetterRoutingKey("order.dead") .build(); } @Bean public Binding orderBinding() { return BindingBuilder.bind(orderQueue()) .to(orderExchange()) .with(ROUTING_KEY); } }

这里面有几个细节：

• new DirectExchange(EXCHANGE_NAME, true, false)的三个参数分别是名称、是否持久化、是否自动删除。生产环境交换机持久化设为true，自动删除设为false。为什么持久化这么重要？因为如果交换机不是持久化的，Broker重启后交换机就没了，队列和交换机的绑定关系也就断了，消息就发不进去了。
• QueueBuilder.durable(QUEUE_NAME)表示队列持久化。队列持久化同样是为了应对RabbitMQ重启，不持久化的队列重启就消失。
• deadLetterExchange和deadLetterRoutingKey是死信配置，消息被消费者拒绝、或者TTL过期、或者队列长度溢出时，会被转投到这个死信交换机上，方便做失败兜底。这个后面第五部分详细展开。

3.3 发送端：RabbitTemplate的用法和确认回调

声明好队列和交换机之后，发送端就可以用路由键来指定消息去向：

@Service public class OrderMessageSender { @Autowired private RabbitTemplate rabbitTemplate; public void sendOrderMessage(OrderDTO order) { CorrelationData correlationData = new CorrelationData(UUID.randomUUID().toString()); rabbitTemplate.convertAndSend( RabbitConfig.EXCHANGE_NAME, RabbitConfig.ROUTING_KEY, order, correlationData ); } }

CorrelationData是发布确认的关键。publisher-confirm-type: correlated开启模式下，RabbitTemplate会在Broker确认消息之后回调CorrelationData里的ConfirmCallback。写法如下：

@PostConstruct public void init() { rabbitTemplate.setConfirmCallback((correlationData, ack, cause) -> { if (ack) { log.info("消息确认成功: {}", correlationData.getId()); } else { log.error("消息确认失败: {}，原因: {}", correlationData.getId(), cause); } }); rabbitTemplate.setReturnsCallback(returned -> { log.error("消息路由失败: {} -> {}", returned.getExchange(), returned.getRoutingKey()); }); }

这里要区分两个概念：

• ConfirmCallback：Broker收到了消息，返回确认（ack）。代表消息到了交换机。但这不保证消息一定进了队列，如果路由键配错了，消息会在交换机里"迷路"。
• ReturnsCallback：消息从交换机路由不到任何队列时，RabbitMQ会把消息退回给生产者，并回调这个接口。所以完整的风控是：Confirm确认到交换机，Returns确认路由到队列，两边都正常，消息才算真正安全。

3.4 接收端：@RabbitListener的几种姿势

接收端最常见的写法：

@Component public class OrderMessageConsumer { @RabbitListener( queues = RabbitConfig.QUEUE_NAME, containerFactory = "rabbitListenerContainerFactory" ) public void onOrderMessage(OrderDTO order, Channel channel, Message message) throws IOException { long deliveryTag = message.getMessageProperties().getDeliveryTag(); try { // 业务处理，比如写库、调接口、更新状态 process(order); // 处理成功后手动确认 channel.basicAck(deliveryTag, false); } catch (Exception e) { // 业务失败，否定确认，但不重新入队，等死信处理 channel.basicNack(deliveryTag, false, false); } } }

这里有几个关键点：

• 方法签名可以从String message升级为OrderDTO order，这个升级非常推荐，因为前面配置了Jackson消息转换器，框架会自动把JSON反序列化成你指定的DTO类型。这算SpringBoot为开发者省的最大的心。
• Channel channel这个参数不是必须的，但如果你配置了手动ACK，就必须接收它，因为basicAck和basicNack都是通过Channel调用的。
• deliveryTag是消息投递标签，Broker用它来定位是哪条消息。调basicAck时传false表示只确认这一条，不批量确认。
• basicNack(deliveryTag, false, false)三个参数分别表示：投递标签、是否批量、是否重新入队。我这里传的是false, false，即不批量拒绝、不重新入队。为什么不重新入队？因为如果消息一直消费失败，重新入队会造成无限循环。正确做法是让它转死信队列，后面单独处理。

如果不想每次手写basicAck，也可以把acknowledge-mode设为auto，让Spring容器自动确认。但自动确认没法精细控制失败重投，而且异常处理的语义比较隐蔽，我强烈建议生产环境用手动ACK。

3.5 消费者异常重试策略

手动ACK模式下，消息处理抛异常，会走你catch里的basicNack逻辑。但你想过这个场景吗：代码刚升级，消费者突然连不上数据库，每条消息进来都会抛异常，如果你每次都basicNack并且不重新入队，消息全跑到死信队列里了。这个情况下更合理的做法是：让临时性故障导致的失败消息重新排队，等数据库恢复了再处理。

SpringBoot提供了一个优雅的重试机制，在application.yml里配置：

spring: rabbitmq: listener: simple: retry: enabled: true max-attempts: 3 initial-interval: 1000 multiplier: 2 max-interval: 10000

开启重试后，消费者方法抛出异常时，消息不会立刻走basicNack，而是按延迟间隔重试。initial-interval: 1000表示第一次重试等1秒，multiplier: 2表示每次间隔翻倍，最多重试3次。

重试次数耗尽之后，Spring会把消息标记为失败。如果还配置了defaultRequeueRejected: false，消息会继续进入死信队列。这个配置组合是生产环境的黄金搭档：临时故障自动重试，重试无望转入死信，由专门的补偿程序去处理。

4. 四种交换机不是随便选的：场景、绑定关系与配置实例

4.1 从RabbitMQ和Kafka的选型对比看交换机的价值

网上讨论得最多的通常是RabbitMQ、Kafka、RocketMQ怎么选。我的经验是：先看业务模型，再看技术需求。

RabbitMQ的核心竞争力是灵活的路由模型——发布/订阅、按路由键匹配、按主题匹配，一套交换机机制可以覆盖很多消息分发模式；Kafka更强调高吞吐日志流，数据管道、实时计算场景往往依赖Kafka的分区和消费者组机制；RocketMQ在事务消息、延迟消息方面做得更完善。

如果只是"把消息从A发给B"这种简单场景，Kafka其实并没有优势，反而增加了学习成本和运维负担。大多数业务系统里，RabbitMQ就是最优解。

在RabbitMQ里，交换机才决定了消息的分发方式。下面把这四种交换机讲透。

4.2 Direct Exchange：精确匹配

直接交换机在绑定队列时需要指定一个路由键，发送消息时也要指定路由键，两者完全匹配，消息才会进队列。

适用场景：订单处理、支付回调、业务类型明确的点对点通信。比如订单创建、订单支付、订单取消，各绑定自己的路由键，发送端用不同路由键，消息就精确分流到对应消费者。

@Bean public Binding orderCreateBinding() { return BindingBuilder.bind(orderCreateQueue()) .to(orderDirectExchange()) .with("order.create"); }

Direct是默认的交换机类型，也是初学者最好理解的，我建议没有特殊需求之前先用它。

4.3 Fanout Exchange：广播

扇形交换机不关心路由键，它会把消息广播到所有绑定的队列上。路由键传什么都无所谓，绑定多少队列，消息就会复制多少份。

适用场景：全局通知、库存更新、缓存刷新。比如商品价格改了，需要同步通知搜索服务、推荐服务、详情页缓存服务，用fanout一条消息全搞定。

@Bean public FanoutExchange cacheFanoutExchange() { return new FanoutExchange("cache.refresh.exchange", true, false); } @Bean public Binding searchCacheBinding() { return BindingBuilder.bind(searchCacheQueue()) .to(cacheFanoutExchange()); } @Bean public Binding recommendCacheBinding() { return BindingBuilder.bind(recommendCacheQueue()) .to(cacheFanoutExchange()); }

4.4 Topic Exchange：模糊匹配

主题交换机是按主题模式匹配的。路由键由点号分隔，绑定关系中的路由键支持两种通配符：

• *：匹配一个单词。
• #：匹配零个或多个单词。

举例：order.*能匹配order.create、order.pay，order.#还能匹配order.pay.success。

适用场景：按业务维度灵活订阅。比如运维平台，log.info.*订阅所有info日志，log.error.*订阅所有error日志，#.system订阅系统级所有事件，组合起来非常灵活。

4.5 Headers Exchange：按Header匹配

头部交换机不按路由键匹配，而是按消息Header头里的键值对匹配。这个交换机用到的场景极少，消息头匹配不如路由键直观，性能和可读性都一般，建议除非是遗留系统、协议兼容等问题，不要选它。

排个优先级：能用Direct就用Direct，多目标广播用Fanout，需要模糊匹配用Topic，Headers除非没得选否则放弃。

4.6 关于Quorum Queue的补充

RabbitMQ 4.0开始，官方把Quorum Queue的定位提到了很高的位置。它是基于Raft协议实现的队列类型，比经典队列（Classic Queue）更强的一致性保证。生产环境里，我建议优先考虑Quorum队列，尤其是在需要高可用、防数据丢失的金融、订单类业务里。

声明Quorum队列的写法：

@Bean public Queue orderQuorumQueue() { return QueueBuilder.durable(QUEUE_NAME) .quorum() .build(); }

Quorum队列注意三点：

• 不支持事务消息，但发布确认是天然支持的。
• 消息只能由主副本处理，不像Kafka那样多副本分摊读流量，所以不要指望它解决读扩展。
• 和Classic队列混用时，交换机绑定关系都要显式声明，避免隐式绑定行为不一致。

5. 消息可靠性：从三个环节保住消息不丢

5.1 消息从生产到消费的完整链路，哪里可能丢

我在前面的配置里做了一堆可靠性的铺垫：发布确认、持久化队列、手动ACK、死信队列。现在把这三个环节串起来讲清楚。

一条消息从生产者到消费者，完整经过三段：

• 第一段：生产者把消息发到RabbitMQ Broker（交换机/队列）。这一段丢了怎么办？靠发布确认。
• 第二段：消息在队列中存储，等待消费者消费。这一段丢了怎么办？靠队列和消息持久化。
• 第三段：消费者拿到消息后处理。这一段丢了怎么办？靠消费者手动ACK。

任何一个环节出了问题，消息就可能悄悄消失。我一个一个来说。

5.2 发布确认：确保消息到Broker

前面已经配置了publisher-confirm-type: correlated和setConfirmCallback。这是生产者侧的第一道保险。确认回调里如果收到失败（ack=false），可以考虑把消息存进本地一张表，启动一个定时任务重发。这是非常实用的生产模式：本地消息表+定期补发，性价比极高，不需要引入复杂的分布式事务框架。

5.3 队列持久化和消息持久化：确保消息不随Broker重启消失

队列持久化（durable）在前面的配置里已经做了，但注意一点：队列持久化不意味着消息持久化。只有在发送消息时把消息的deliveryMode设置为PERSISTENT，消息才会被持久化到磁盘。

如果用SpringBoot的RabbitTemplate.convertAndSend发送消息，默认消息就是可持久化的。但如果你手动构造MessageProperties，就要注意设置：

MessageProperties props = new MessageProperties(); props.setDeliveryMode(MessageDeliveryMode.PERSISTENT);

不设置的话，消息只存在内存里，一旦RabbitMQ宕机重启，内存消息全部丢失。这个坑比较隐蔽，因为开发环境机器一般不重启，不容易暴露。

5.4 消费端手动ACK和幂等性：确保消息不重复消费

手动ACK保证了"消息处理成功才确认"，但分布式系统里，"处理成功"和"确认成功"之间裂了一道缝：消息处理完了，还没来得及ACK，消费者进程崩了，这条消息会被重新投递给其他消费者。于是业务被重复执行了。

这就是重复消费问题的根源。解决重复消费的核心，不是靠MQ（MQ只能保证at-least-once，也就是至少一次投递，没法保证恰好一次），而是靠消费端幂等。

我在项目里最常用的方案是给业务加上唯一下标幂等判断。比如订单消息里带一个orderMessageId，消费时先查Redis里这个ID有没有处理过：

String messageId = order.getMessageId(); Boolean firstConsumed = stringRedisTemplate.opsForValue() .setIfAbsent("order:msg:" + messageId, "1", Duration.ofDays(1)); if (firstConsumed == null || !firstConsumed) { log.warn("重复消息，跳过处理: {}", messageId); channel.basicAck(deliveryTag, false); return; }

setIfAbsent这个操作是原子性的，成功返回true说明是第一次，返回false说明已经处理过了。主键唯一约束也是类似思路：先查是否存在，再处理，存在就直接ACK跳过。幂等这一层必须做，不做等于给生产环境埋雷。

5.5 死信队列：给处理失败的消息一个收容所

死信（Dead Letter）这个概念前面已经出现好几次了，现在完整说明一下。消息进入死信队列有三种情况：

• 消费者调用basicNack或basicReject，且requeue=false。
• 消息设置了TTL过期时间，超时未被消费。
• 队列长度达到上限，新消息无法入队。

死信交换机和普通交换机没什么区别，只是它专门接收"死信"消息。配置方式：

@Bean public Queue orderDeadLetterQueue() { return QueueBuilder.durable(QUEUE_NAME + ".dlq") .build(); } @Bean public DirectExchange orderDeadLetterExchange() { return new DirectExchange(EXCHANGE_NAME + ".dlx", true, false); } @Bean public Binding orderDeadLetterBinding() { return BindingBuilder.bind(orderDeadLetterQueue()) .to(orderDeadLetterExchange()) .with("order.dead"); }

然后在原队列声明里加上死信参数：

QueueBuilder.durable(QUEUE_NAME) .deadLetterExchange(EXCHANGE_NAME + ".dlx") .deadLetterRoutingKey("order.dead") .build();

死信队列的消费者可以做的处理包括：

• 记日志、告警，让值班人员介入。
• 把失败消息落库，补偿程序定期重放。
• 人工排查业务逻辑或代码缺陷，修好之后手动搬运消息回原队列。

死信队列不建议只接一个消费异常就什么都不做，它的价值在于让失败消息"可见、可控、可处理"。

6. 生产环境排障手册：账号权限、连接问题与消息异常

6.1 常见问题的现象、原因和处理手段

把这些年在RabbitMQ上遇到的故障整理成了一张排查速查表。表里的每一行都来自真实线上事故，供你参考。

6.2 从日志到管理界面的一套排查顺序

遇到RabbitMQ相关问题，我最推荐的排查顺序是固定的，按照这个顺序走，大多数问题都能定位在几分钟内：

第一步，看SpringBoot应用日志。消费者异常会打堆栈，ConfirmCallback失败会打ack=false和原因，消息丢失如果是代码问题，日志里基本都会暴露。应用日志是最先也最快的线索来源。

第二步，看管理界面。重点看三个地方：Exchange列表里有没有对应的交换机，Queue列表里有没有对应队列，点击队列进去看Consumers、Messages里的Ready/Unacked状态。

下面这几个指标重点说明一下：

• Ready：已经进入队列，等待消费的消息数。持续增长说明消费者没有消费或消费速度跟不上。
• Unacked：已经被消费者拉走，但还没有确认的消息数。如果Unacked一直居高不下，说明消费者处理很慢，或者卡在某个阻塞操作上（比如同步调接口超时）。
• Total：Ready + Unacked的总和。这个数字和预期业务量级对比，能很快判断是否消息积压。

第三步，如果业务日志和管理界面都看不出问题，就用命令行直接查：

rabbitmqctl list_queues name messages_ready messages_unacknowledged rabbitmqctl list_exchanges name type rabbitmqctl list_bindings source_name destination_name routing_key rabbitmqctl list_consumers queue_name

第四步，抓包或开Debug日志。如果到了这步还没定位，就把SpringBoot的日志级别调成Debug，重点看com.rabbitmq.client.impl包的日志，它能打印AMQP协议层的数据帧，能判断消息是不是真的在网络上发送成功了。

6.3 关于虚拟主机的一个常见误区

最后单独说一句虚拟主机。很多新手把虚拟主机和队列的概念混在一起，创建了一个虚拟主机，然后在里面声明队列，就跑不通，因为连接配置里的virtual-host没有改。

SpringBoot连接配置里的virtual-host必须指向你创建的那个虚拟主机。如果连接时没有指定或指错了，你会看到ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN的错误。排错的时候，优先确认虚拟主机名拼写和权限分配——用户名在某个虚拟主机下要有对应的权限，否则连接照样拒绝。

我在项目里通常这样规划：开发环境一个虚拟主机，测试环境另一个，生产环境按业务模块再细分。这样消息在环境之间天然隔离，权限控制也不容易出问题。

6.4 运维上的一些经验总结

• 队列名字要带业务前缀，比如order.create.queue，别用无意义的test1。这个在管理界面排障时真的能救命，一眼就看出是哪个业务链路的问题。
• 死信队列一定要配。没有死信队列的消息如果消费失败，会无限重试（如果requeue=true），或者直接消失（如果requeue=false），两种都不是好结果。
• 发布确认和ReturnsCallback一定要接。它们不是性能敏感操作，对生产环境的排障价值却是最大的。
• 消息DTO的字段变更要灰度发布。消费者和生产者版本不一致时，旧版本消费者反序列化新字段会得到null或不报错但静默丢数据。我建议DTO增加版本号字段，字段变更时保证消费者先升级兼容，再升级生产者。

坦率地说，RabbitMQ本身的定位就是可靠、灵活、易用，但"能用"和"用得稳"之间相差了一整套兜底设计。把发布确认当标配、把死信队列当默认、把幂等消费当刚需，你的RabbitMQ才是真正敢上生产环境的。