类级别@RabbitListener需配合@RabbitHandler方法使用，否则消息无法处理；方法级别@RabbitListener自身即为完整处理器，不可加@RabbitHandler。
@RabbitListener 标注在类上时必须配 @RabbitHandler
类级别 @RabbitListener 是入口开关，但不会自动调用任意方法——它只负责把消息路由到该类，具体由哪个方法处理，得靠 @RabbitHandler 标记的候选方法来承接。漏掉 @RabbitHandler，Spring AMQP 找不到可执行的方法，日志里会报 NoSuchMethodException 或静默丢弃消息。
常见错误现象：
- 消息已入队，消费者没任何日志输出
- 控制台抛出
org.springframework.amqp.rabbit.listener.exception.ListenerExecutionFailedException，内嵌No suitable method found
正确写法示例：
@Component
@RabbitListener(queues = "multi.type.queue")
public class OrderMessageHandler {
@RabbitHandler
public void handleString(String msg) { /* ... */ }
<pre class="brush:php;toolbar:false;">@RabbitHandler
public void handleOrder(Order order) { /* ... */ }}
注意：@RabbitHandler 方法不能是 private，且参数类型必须能被当前 MessageConverter 解析成功（比如发的是 JSON，但没配 Jackson2JsonMessageConverter，就会 fallback 到 SimpleMessageConverter，导致反序列化失败）。
方法级 @RabbitListener 不需要 @RabbitHandler
当 @RabbitListener 直接标在方法上，它自己就是完整的消息处理单元，不需要、也不能加 @RabbitHandler。强行加会导致启动时报错：Annotation @RabbitHandler is not allowed on methods with @RabbitListener。
使用场景：
- 单队列单逻辑，比如纯日志消费、状态同步等简单任务
- 需要对不同队列做完全隔离的处理（避免类内方法间干扰）
- 想显式控制并发、重试、容器工厂等细粒度配置（每个方法可配独立
containerFactory）
示例：
@Component
public class SimpleConsumer {
@RabbitListener(queues = "log.queue")
public void logHandler(String line) { /* ... */ }
<pre class="brush:php;toolbar:false;">@RabbitListener(queues = "alarm.queue")
public void alarmHandler(Alarm alarm) { /* ... */ }}
这里两个方法彼此无关，各自绑定队列，互不干扰，也不共享 MessageConverter 的类型分发逻辑。
@RabbitHandler 类型分发依赖 MessageConverter 和 content-type
@RabbitHandler 的“按类型路由”不是靠反射猜，而是严格依赖消息头里的 content-type 和当前注册的 MessageConverter 实际解析出的 Java 类型。如果发送端没设 content-type，或设错了（比如发 JSON 却标成 text/plain），@RabbitHandler 就会找不到匹配方法。
关键点：
-
SimpleMessageConverter默认只支持String、byte[]、Serializable，且对对象用 JDK 序列化（不推荐） - 要支持
Order、User等 POJO，必须配Jackson2JsonMessageConverter，并确保发送端设置content-type: application/json - 发送端若用
rabbitTemplate.convertAndSend()，默认不带content-type；需显式设置：message.getMessageProperties().setContentType("application/json")
否则即使你写了 @RabbitHandler public void handle(Order o)，收到的仍是 byte[] 或 String，触发类型不匹配异常。
混合使用：类级监听 + 方法级监听共存要小心
一个类里既标了类级 @RabbitListener，又在内部方法上标了方法级 @RabbitListener，Spring 会全部注册，但容易引发歧义和维护混乱。更严重的是，如果类级监听绑定了队列 A，方法级又绑了队列 B，而两个监听器用了同一套 MessageConverter，可能因类型冲突导致某条消息被重复消费或路由失败。
建议做法：
- 保持风格统一：要么全用类级 +
@RabbitHandler（适合多类型同队列） - 要么全用方法级
@RabbitListener（适合单类型单队列） - 真要混用，务必为不同监听器指定不同
containerFactory，并确认MessageConverter配置互不干扰
最容易被忽略的一点：类级 @RabbitListener 的 queues 属性值，会被所有该类下的 @RabbitHandler 方法共享；而方法级 @RabbitListener 的队列是独占的。这个差异在动态队列名（如 SpEL 表达式）场景下尤其容易出错。
