Spring Kafka非阻塞重试场景下@DltHandler方法无法正确接收头部问题

你使用的Spring Kafka 2.7.6版本中，@DltHandler默认支持接收以下几类头部：

• 自定义业务头部：原消息携带的自定义业务头部（如你代码中的event）会原样透传，不需要额外前缀即可直接读取
• 原消息原生属性头部：对应KafkaHeaders常量，分别为：
  • KafkaHeaders.ORIGINAL_TOPIC：原消息所属主题，String类型
  • KafkaHeaders.ORIGINAL_PARTITION：原消息所在分区，Integer类型
  • KafkaHeaders.ORIGINAL_OFFSET：原消息偏移量，Long类型
  • KafkaHeaders.ORIGINAL_TIMESTAMP：原消息生产时间戳，Long类型
  • KafkaHeaders.ORIGINAL_TIMESTAMP_TYPE：原消息时间戳类型，String类型
• 重试过程头部：对应RetryTopicHeaders常量，分别为：
  • RetryTopicHeaders.DEFAULT_HEADER_ATTEMPTS：已完成的重试次数，Integer类型
  • RetryTopicHeaders.DEFAULT_HEADER_BACKOFF_TIMESTAMP：重试触发时间戳，Long类型
• 异常信息头部：对应KafkaHeaders常量，分别为：
  • KafkaHeaders.EXCEPTION_FQCN：抛出异常的全限定类名，String类型
  • KafkaHeaders.EXCEPTION_MESSAGE：异常的简要信息，String类型
  • KafkaHeaders.EXCEPTION_STACKTRACE：异常堆栈信息，String类型

你遇到的问题是2.7.x版本的常见问题，核心原因有两个：

1. 类型不匹配导致反序列化乱码
   你代码中将ORIGINAL_OFFSET这类数值类型的头部定义为String接收，但Spring Kafka转发到DLT时，这类头部是按照byte[]序列化的数值类型存储的，直接用String类型读取会触发反序列化错误，出现乱码。你观测到的kafka_前缀是Kafka客户端暴露的原始头部标识，正常使用KafkaHeaders常量时Spring会自动处理映射，不需要手动添加前缀。

所有数值类头部都必须用对应数值类型接收，不能用String类型，否则都会出现乱码、空值问题。

2. 版本内置默认配置限制
   Spring Kafka 2.7.x版本的非阻塞重试功能还处于早期迭代阶段，存在两处默认限制：

• 异常堆栈头部默认最大长度为1500字符，超出部分会自动截断
• 部分头部序列化逻辑存在bug，数值类型透传时容易出现转换错误

1. 修正@DltHandler方法的参数类型，示例如下：

@DltHandler
fun processaDlt(
    @Payload mensagem: String,
    @Header("event") eventName: String,
    @Header(KafkaHeaders.ORIGINAL_OFFSET) offset: Long,
    @Header(KafkaHeaders.EXCEPTION_FQCN) descException: String,
    @Header(KafkaHeaders.EXCEPTION_STACKTRACE) stacktrace: String,
    @Header(KafkaHeaders.EXCEPTION_MESSAGE) errorMessage: String
) {
    // 你的DLT处理逻辑
}

2. 如果需要完整的异常堆栈，可通过自定义RetryTopicConfiguration调整堆栈长度限制：

@Bean
fun retryTopicConfig(kafkaTemplate: KafkaTemplate<String, String>): RetryTopicConfiguration {
    return RetryTopicConfigurationBuilder
        .newInstance()
        .maxAttempts(3) // 替换为你的重试次数配置
        .exponentialBackoff(1000, 2, 10000) // 替换为你的退避策略
        .dltHandlerCustomizer { dltHandler ->
            dltHandler.setStackTraceHeaderMaxLength(10000) // 自定义堆栈最大长度
        }
        .create(kafkaTemplate)
}

3. 条件允许的话建议升级到Spring Kafka 2.8.x及以上版本，该版本修复了大量非阻塞重试的头部透传问题，稳定性更好。

内容的提问来源于stack exchange，提问作者etc