ReturnCallback在消息成功到达Exchange但无法路由到队列时触发，需同时满足publisher-returns:true、mandatory:true及setReturnCallback()三条件；关注Exchange→Queue阶段，典型错误码312（NO_ROUTE）。
ReturnCallback 在消息无法路由到队列时触发
returncallback 不是“消息发送失败”就触发，而是特指消息已成功到达 exchange，但因路由规则不匹配、队列不存在、binding 缺失或 mandatory 为 true 等原因，导致 exchange 无法将消息投递进任何队列时，rabbitmq 主动把消息退回给生产者，并调用该回调。
它和 ConfirmCallback 是两个独立阶段：前者管 Exchange → Queue，后者管 Publisher → Exchange。漏配 mandatory: true 或没开 publisher-returns，ReturnCallback 就完全不会执行。
必须同时满足的三个配置条件
缺一不可，否则即使消息路由失败，你也收不到回调：
-
spring.rabbitmq.publisher-returns: true—— 启用消息退回机制 -
spring.rabbitmq.template.mandatory: true—— 强制要求 Exchange 必须成功路由，否则退回来 -
rabbitTemplate.setReturnCallback(...)—— 显式注册回调函数（仅配置项不够，代码里也得设）
常见错误是只配了前两项，却忘了在 RabbitTemplate 实例上设置回调函数，结果日志静默，问题难以排查。
典型触发场景与对应错误日志特征
以下情况会进 ReturnCallback，你可以通过 replyCode 和 replyText 快速定位：
RabbitMQ 4.2.3 是 2026 年初发布的重要稳定更新版本，重点修复了 Khepri 元数据存储相关问题，并改进了监控性能。对于使用 Docker、Kubernetes 或微服务架构的开发团队来说，该版本兼容性和稳定性表现较好。
- 向一个不存在的
routingKey发送消息（如queue.order.pay队列未声明，且 binding 未覆盖该 key）→replyCode=312，replyText="NO_ROUTE" - Exchange 类型为
direct，但发送时routingKey与所有 binding key 都不匹配 → 同样触发NO_ROUTE - 队列被删除，但生产者未感知，仍按旧配置发消息 →
replyCode=312或404（取决于 broker 版本）
注意：ReturnCallback 是异步回调，不能阻塞主业务线程；也不保证 100% 可靠（比如 broker 在退回途中宕机），所以关键路径建议配合本地事务 + 补偿任务。
为什么你可能收不到 ReturnCallback 日志
不是代码写错了，很可能是环境或配置干扰：
- 开发时连的是默认
guest/guest账号，而该账号在 RabbitMQ 3.13+ 默认禁用publisher_returns权限 → 需手动开启sudo rabbitmqctl set_permissions -p / guest ".*" ".*" ".*" "publisher_returns" - 使用了
@RabbitListener自动声明队列，但声明时机晚于消息发送（尤其在应用刚启动时）→ 消息先到，队列还没建好，直接被退回 - 测试时用
curl或管理界面发消息，绕过了你的RabbitTemplate，自然不会走你写的ReturnCallback
最易忽略的一点：ReturnCallback 只对设置了 mandatory=true 的消息生效，而 Spring Boot 的 template 默认不带这个 flag，必须显式调用 setMandatory(true)。
