@KafkaHandler 注解

https://docs.spring.io/spring-kafka/api/org/springframework/kafka/annotation/KafkaHandler.html

1. @KafkaHandler 的背景和意义

• 在使用 Spring for Apache Kafka 时，为了消费 Kafka 中的消息，通常可以直接在方法上使用 @KafkaListener 注解。
• 然而，在一些场景下，同一个 Kafka 主题可能会传输多种不同类型的消息，此时如果为每种类型单独定义一个 @KafkaListener 方法，不仅容易导致代码冗余，而且管理上不够灵活。
• Spring 提供了类级别的 @KafkaListener 结合 方法上的 @KafkaHandler 机制，让我们能够在一个类中定义多个消息处理方法，根据消息内容或反序列化后的数据类型自动分派到对应方法进行处理，从而达到统一管理和灵活扩展的效果。

---

2. @KafkaHandler 的基本原理

• 当你在一个类上标注了 @KafkaListener 注解时，Spring Kafka 会为该类创建一个统一的消息监听容器，该容器负责接收 Kafka 发来的消息。
• 而该类中用 @KafkaHandler 注解标记的方法则作为实际处理消息的候选方法。

消息分派逻辑：

• 类型匹配：

• 当消息抵达时，会先由反序列化器将原始数据转换为 Java 对象（这要求反序列化设置必须正确）。
• 在类级别的 @KafkaListener 配置下，Spring 会根据“消息负载”（即反序列化后的对象）的具体类型，
• 扫描该类中所有使用了 @KafkaHandler 注解的方法，然后选择参数类型与消息类型匹配的那个方法进行调用。匹配的规则是：
  • 方法的参数（或者带 @Payload 注解的参数）的类型必须与反序列化得到的消息类型一致。
  • 如果存在多个方法都符合（出现歧义）时，会抛出异常，所以必须保证对于任一消息类型只有一个方法能够接收。

• 默认处理： 为了应对那些没有与任何特定方法完全匹配的消息，可以在类中指定一个“默认”方法，即在 @KafkaHandler 注解上设置属性 isDefault = true。如果没有找到合适的匹配方法，就会调用这个默认方法。注意，一个类中最多只能存在一个默认处理方法。

这样，通过消息类型与方法签名的严格匹配，Spring Kafka 就能智能地将不同类型的消息分发到相应的 @KafkaHandler 方法中处理。

参考 Spring Kafka 的[官方文档]( (@KafkaListener on a Class :: Spring Kafka))可知，这种分发机制使得代码更为模块化，并能够很容易地扩展新增消息类型处理方法而无需改变整体监听配置。

3. 示例说明

下面给出一个简单的示例，以说明如何使用 @KafkaHandler 来处理不同类型的消息：

@KafkaListener(topics = "myTopic", groupId = "myGroup")
@Component
public class MultiMessageListener {

    // 处理 String 类型的消息
    @KafkaHandler
    public void handleStringMessage(@Payload String message) {
        System.out.println("接收到 String 消息: " + message);
    }

    // 处理 Integer 类型的消息
    @KafkaHandler
    public void handleIntegerMessage(@Payload Integer number) {
        System.out.println("接收到 Integer 消息: " + number);
    }

    // 默认处理方法：当消息类型与上面两种都不匹配时调用
    @KafkaHandler(isDefault = true)
    public void defaultHandler(@Payload Object payload) {
        System.out.println("使用默认处理器，接收到未知类型消息: " + payload);
    }
}

在此示例中：

• 如果生产者发送的消息经过反序列化后是 String 类型，则由 handleStringMessage 处理；
• 如果是 Integer 类型，则调用 handleIntegerMessage；
• 否则则调用 defaultHandler 作为后备方案。

需要注意，确保消息在到达监听方法前已经正确反序列化为预期的 Java 类型。如果反序列化的配置不正确（例如配置问题导致反序列化为 LinkedHashMap），则可能无法正确触发特定的处理方法，从而落到默认处理器或者引发异常。