@Header 拿不到自定义消息头（如 x-custom-id）是因为 Spring AMQP 默认不自动暴露所有 AMQP 协议头，仅支持标准头、手动声明的 headers 映射或合法命名的 BasicProperties.headers；需验证原始 Message 的 headers 并优先用 Message 入参手动获取。
为什么 @Header 拿不到自定义消息头（比如 x-custom-id）？
默认情况下，rabbitmq 客户端（spring amqp）不会把所有消息属性原样映射到方法参数。@header 只能获取 spring amqp 显式暴露的「标准头」或通过 headers 属性显式传递的键——不是所有 amqp 协议层的 header 字段都会自动出现在 spring 的 header map 中。
常见错误现象：@Header("x-custom-id") String id 报 IllegalArgumentException: No header with name 'x-custom-id'，哪怕生产者确实在 MessageProperties 里 set 了。
- 确认生产者是否真的用
MessageProperties.setHeader("x-custom-id", "123")设置（而非写进 body 或用其他方式伪造） - 检查是否启用了
spring.rabbitmq.listener.simple.missing-queues-fatal=false等干扰配置（虽不直接相关，但常伴生调试问题） - Spring AMQP 2.4+ 默认会过滤掉非 ASCII 字符开头或含特殊符号的 header 名——确保 key 是合法标识符风格（如避免
X-Custom-ID大小写混用或带中划线，优先用x_custom_id）
@Header 能直接绑定哪些值？
它支持三类来源：
- AMQP 协议层
BasicProperties.headers中的键值（前提是未被 RabbitAdmin 或中间件拦截/清洗） - Spring AMQP 自动注入的标准头：如
amqp_receivedRoutingKey、amqp_deliveryTag、amqp_consumerQueue - 手动在
@RabbitListener上通过headers = {"x-custom-id=x-custom-id"}声明的映射（这是最稳的兜底方式）
示例写法：
@RabbitListener(queues = "my.queue", headers = {"x_custom_id=x_custom_id"})
public void listen(String body, @Header("x_custom_id") String customId) {
// 此时 customId 非 null
}
注意：headers 属性是 key=value 形式，左边是目标参数名（可任意），右边必须严格匹配发送方设置的 header key。
如何验证消息头是否真被送达消费者？
别猜，直接看原始 Message 对象：
- 把方法签名改成接收
Message：public void listen(Message message) - 打印
message.getMessageProperties().getHeaders()—— 这是最权威的“落地快照” - 如果这里都为空，问题一定出在生产者或网络链路（比如代理插件重写了 headers）；如果这里有值但
@Header拿不到，就是 Spring 绑定机制的问题
常见陷阱：某些 RabbitMQ 插件（如 shovel、federation）或云厂商封装 SDK 会 strip 非标准 header，务必在消费者侧先做 Message 原始校验。
替代方案：用 Message + 手动取值更可控
当 header 名动态、含特殊字符、或需批量读取时，硬靠 @Header 绑定反而增加维护成本：
- 放弃注解，改用
Message入参，调用message.getMessageProperties().getHeaders().get("x_custom_id") - 类型转换自己负责（
String.class、Long.class等），避免 Spring 类型推导失败 - 配合
@Payload分离 body 和元数据：public void listen(@Payload String body, Message message)
这种方式绕过所有 header 绑定黑盒逻辑，适合对元数据可靠性要求高的场景（比如幂等 ID、灰度标记、追踪 traceId）。
真正麻烦的从来不是怎么写那行 @Header，而是消息在跨系统流转时，header 被谁悄悄改了、删了、编码错了——所以第一步永远是抓原始 Message 看真相。
