消息队列 / 系统课时
处理不可路由消息
处理不可路由消息
生产者把消息写进 Exchange,并不代表它一定进入了队列。本节用 mandatory=true 和返回回调识别“Exchange 存在,但没有任何绑定能够匹配”的消息,并把这种路由失败转成可记录、可告警、可补偿的明确结果。
学习目标
- 理解不可路由消息与普通发送异常的区别
- 使用
mandatory标记和 Return 回调捕获basic.return - 为返回消息建立可观测、可补偿的处理边界
不可路由发生在路由阶段
AMQP 0-9-1 发布链路可以拆成“生产者发送到 Exchange”和“Exchange 根据绑定把消息路由到 Queue”两步。Exchange 存在但没有任何 Queue 匹配 routing key 时,消息就是不可路由消息。
默认情况下,生产者如果不要求返回,不可路由消息可能被直接丢弃。把 mandatory 设为 true 后,RabbitMQ 会把这条消息通过 basic.return 返回给发布它的客户端;返回内容包含 reply code、原因、Exchange、routing key、属性和原始消息体。

这里要区分两个边界:没有匹配队列会触发返回;目标 Exchange 根本不存在通常会造成 channel 级协议错误。后者不是 mandatory 要解决的问题,应按连接或通道异常处理。
用 Return 回调捕获失败消息
下面示例要求本机 RabbitMQ 可连接,Java 项目已引入 RabbitMQ Java Client 5.x。程序声明一个没有绑定队列的 Direct Exchange,再用不存在的 routing key 发布消息,因此回调会稳定收到返回。
import com.rabbitmq.client.BuiltinExchangeType;
import com.rabbitmq.client.Channel;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.MessageProperties;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
public class UnroutableMessageDemo {
public static void main(String[] args) throws Exception {
ConnectionFactory factory = new ConnectionFactory();
factory.setHost("localhost");
factory.setUsername("guest");
factory.setPassword("guest");
CountDownLatch returned = new CountDownLatch(1);
try (Connection connection = factory.newConnection();
Channel channel = connection.createChannel()) {
String exchange = "demo.unroutable";
channel.exchangeDeclare(exchange, BuiltinExchangeType.DIRECT, false);
// 回调必须在发布前注册,否则返回消息无法进入业务处理逻辑。
channel.addReturnListener(message -> {
System.out.printf(
"RETURN code=%d text=%s exchange=%s routingKey=%s body=%s%n",
message.getReplyCode(),
message.getReplyText(),
message.getExchange(),
message.getRoutingKey(),
new String(message.getBody(), StandardCharsets.UTF_8)
);
returned.countDown();
});
byte[] body = "order-1001".getBytes(StandardCharsets.UTF_8);
// true 表示开启 mandatory;当前 Exchange 没有任何匹配绑定。
channel.basicPublish(
exchange,
"order.created.missing",
true,
MessageProperties.PERSISTENT_TEXT_PLAIN,
body
);
if (!returned.await(3, TimeUnit.SECONDS)) {
System.out.println("NO RETURN");
}
}
}
}预期输出
RETURN code=312 text=NO_ROUTE exchange=demo.unroutable routingKey=order.created.missing body=order-1001如果实际环境已有同名 Exchange 且存在能够匹配该 routing key 的绑定,就不会出现上述返回,应更换演示名称或先检查拓扑。
返回消息不能只打印日志
Return 回调的职责不是“看见错误就结束”,而是把消息重新纳入可靠投递流程。至少应记录消息唯一标识、Exchange、routing key、reply code 和 reply text,并产生可检索的错误指标。业务要求消息不能丢失时,还要把原始消息或其业务引用写入补偿存储。
不要对所有 NO_ROUTE 立即无限重试。绑定缺失、routing key 写错或发布到了错误 Exchange 都属于拓扑或配置问题,同样参数不断重发只会制造更多失败。更合理的做法是有限退避重试,同时告警并允许人工修复路由。
验证路由恢复
为 Exchange 增加一个与 order.created.missing 匹配的 Queue 绑定后,再运行同一发布代码,Return 回调不应触发。此时应继续通过队列深度、消费者日志或消费结果验证消息确实进入后续链路。
处理不可路由消息的关键不是把 mandatory 打开,而是把 basic.return 当成一种明确的失败结果:能定位是哪条消息、为什么没有路由,并能够进入告警或补偿流程。