死信队列需手动声明并绑定,RabbitMQ仅转发消息而不自动创建DLQ;必须显式声明队列、交换器并正确绑定,且队列参数须用amqp.Table传入,Reject(false)才触发死信。

死信队列不是自动创建的,得手动声明并绑定
很多人以为只要设置了 x-dead-letter-exchange,消息超时或拒收后就会“自动飞”去某个神秘队列——其实 RabbitMQ 根本不帮你建那个死信队列,它只负责把消息发过去,前提是目标 Exchange 和 Queue 都已存在、且绑定关系正确。
实操建议:
- 必须显式声明一个普通队列(比如
dlq.order.processing),并确保它没有被设置为auto-delete - 声明一个 Exchange(如
dlx.order)作为死信交换器,类型通常用direct或topic - 把死信队列绑定到该 Exchange,Routing Key 要和生产者发往原队列时设置的
x-dead-letter-routing-key一致 - 原业务队列声明时,通过
args设置三个关键参数:x-dead-letter-exchange、x-dead-letter-routing-key、x-message-ttl(可选)或x-max-length(可选)
Go 客户端里设置死信参数要用 Table 类型传参
RabbitMQ 的死信配置属于队列的 arguments,在 amqp-go 库中对应的是 amqp.Table 类型,不是字符串或结构体字段。直接写错类型会导致参数被忽略,但不会报错——消息照常入队,就是永远不会进 DLQ。
常见错误现象:消息 TTL 到期后消失,没进 DLQ;或者 Reject(true) 后也石沉大海。
立即学习“go语言免费学习笔记(深入)”;
实操建议:
- 用
map[string]interface{}构造参数,再转成amqp.Table -
x-dead-letter-exchange值必须是已存在的 Exchange 名字(字符串) -
x-dead-letter-routing-key如果不设,默认沿用原消息的 routing key;设了就要确保和 DLQ 的绑定 key 匹配 - TTL 单位是毫秒,别误写成秒(比如想设 30 秒,写成
30就是 30 毫秒)
示例片段:
args := amqp.Table{
"x-dead-letter-exchange": "dlx.order",
"x-dead-letter-routing-key": "order.dlq",
"x-message-ttl": 30000,
"x-max-length": 1000,
}
消息进 DLQ 前可能被丢弃,取决于拒绝方式和 requeue 设置
不是所有 “拒绝” 都会触发死信。关键看消费者调用 Delivery.Reject() 时第二个参数 requeue 是 true 还是 false。只有 false 才可能进 DLQ;true 会重新入队,反复失败就卡住或堆积。
使用场景:你想让处理失败的订单进入人工复核流程,而不是无限重试。
实操建议:
- 避免在业务逻辑里无条件
Reject(true),尤其在有死信需求时 - 如果用了
Nack(),同样注意requeue参数 - 确认 Broker 端没有开启
dead-letter-routing-key覆盖逻辑(某些插件或自定义策略可能干扰) - 测试时用
BasicGet手动拉一条消息,然后Reject(false),观察是否进 DLQ,比等 TTL 更快验证链路
DLQ 消息自带原始属性,但部分字段会被重写
死信消息进入 DLQ 后,RabbitMQ 会添加几个新 header:x-death(记录死亡原因、次数、时间等)、original-expiration(原 TTL),但也会覆盖掉一些原始字段,比如 delivery_mode 可能变成 2(持久化),routing_key 变成 x-dead-letter-routing-key 的值。
性能 / 兼容性影响:这些 header 是 AMQP 协议扩展,老客户端可能解析失败;x-death 是数组,多次死信会追加条目,体积增大。
实操建议:
- 消费 DLQ 时优先检查
delivery.Headers["x-death"],判断是超时、拒收还是队列满 - 不要依赖原始
Headers里的自定义字段做路由决策,它们可能被截断或丢失 - 如果需要保留完整上下文,建议在原始消息 body 里嵌套元数据,而不是全靠 headers


















