spring boot 的全局异常处理机制(如 @controlleradvice)默认只能捕获 web 请求线程中的异常,无法直接捕获 kafka 消费者组在后台线程中抛出的异常。要解决这个问题,必须为每个 kafkalistenercontainerfactory 配置一个自定义的 errorhandler,通常使用 seektocurrenterrorhandler 来记录日志、发送告警或执行补偿逻辑,从而将消费者组的错误纳入统一的管理流程。

如何配置全局 Kafka 错误处理器
通过实现 ConsumerAwareErrorHandler 接口并注入到 KafkaListenerContainerFactory 中,可以拦截所有消费失败的事件。核心做法是创建一个全局的 SeekToCurrentErrorHandler Bean,并在其中定义具体的处理逻辑,例如将异常信息持久化到数据库或发送到监控系统。

import org.apache.kafka.clients.consumer.Consumer;
import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.springframework.kafka.listener.ConsumerAwareErrorHandler;
import org.springframework.stereotype.Component;
@Component
public class GlobalKafkaErrorHandler implements ConsumerAwareErrorHandler {
@Override
public void handle(Exception thrownException, ConsumerRecord<?, ?> record,
Consumer<?, ?> consumer, Object listenerBean) {
// 1. 记录详细日志
System.err.println("Global Error Handler triggered for topic: " +
record.topic() + ", partition: " + record.partition());
// 2. 业务逻辑:保存异常记录到 DB 或发送告警
saveErrorRecord(record, thrownException);
}
private void saveErrorRecord(ConsumerRecord<?, ?> record, Exception e) {
// 模拟保存逻辑
System.out.println("Saving error to DB: " + e.getMessage());
}
}
上述代码定义了一个全局的错误处理器。接下来需要在配置类中将这个处理器应用到所有的监听器工厂中。这样,任何由 @KafkaListener 触发的方法如果抛出未捕获的异常,都会经过这个全局处理器。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.kafka.config.ConcurrentKafkaListenerContainerFactory;
import org.springframework.kafka.core.ConsumerFactory;
import org.springframework.kafka.listener.ContainerProperties;
import org.springframework.kafka.listener.SeekToCurrentErrorHandler;
@Configuration
public class KafkaConfig {
@Bean
public ConcurrentKafkaListenerContainerFactory<String, String> kafkaListenerContainerFactory(
ConsumerFactory<String, String> consumerFactory,
GlobalKafkaErrorHandler globalErrorHandler) {
ConcurrentKafkaListenerContainerFactory<String, String> factory =
new ConcurrentKafkaListenerContainerFactory<>();
factory.setConsumerFactory(consumerFactory);
// 关键步骤:设置全局错误处理器
SeekToCurrentErrorHandler errorHandler = new SeekToCurrentErrorHandler(globalErrorHandler);
factory.setErrorHandler(errorHandler);
return factory;
}
}
运行这段配置后,当消费者发生反序列化错误或业务逻辑异常时,控制台会打印出对应的主题和分区信息,并触发 saveErrorRecord 方法。这确保了即使在没有 Web 请求上下文的情况下,异常也能被集中捕获和处理。
如何处理死信队列与重试策略
除了简单的错误记录,实际生产中通常需要结合重试机制和死信队列(DLQ)来处理暂时性故障。通过在 SeekToCurrentErrorHandler 中配置 RetryTemplate,可以实现指数退避重试。如果重试次数耗尽,则可以将消息发送到指定的死信主题,防止消息丢失。

import org.springframework.kafka.listener.SeekToCurrentErrorHandler;
import org.springframework.retry.backoff.ExponentialBackOffPolicy;
import org.springframework.retry.policy.SimpleRetryPolicy;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.kafka.listener.DeadLetterPublishingRecoverer;
// 在之前的 KafkaConfig 中修改 Bean 定义
@Bean
public SeekToCurrentErrorHandler seekToCurrentErrorHandler(
GlobalKafkaErrorHandler globalErrorHandler,
ProducerTemplate<String, String> producerTemplate) {
// 1. 配置重试策略:最多重试 3 次,每次间隔翻倍
RetryTemplate retryTemplate = new RetryTemplate();
SimpleRetryPolicy retryPolicy = new SimpleRetryPolicy(3);
ExponentialBackOffPolicy backOffPolicy = new ExponentialBackOffPolicy();
backOffPolicy.setInitialInterval(1000);
backOffPolicy.setMultiplier(2.0);
retryTemplate.setRetryPolicy(retryPolicy);
retryTemplate.setBackOffPolicy(backOffPolicy);
// 2. 配置死信恢复器:重试失败后发送到 DLQ
DeadLetterPublishingRecoverer recoverer = new DeadLetterPublishingRecoverer(
producerTemplate, (r, e) -> new org.apache.kafka.common.TopicPartition(r.topic() + ".DLQ", r.partition()));
// 3. 组合错误处理器
return new SeekToCurrentErrorHandler(globalErrorHandler, recoverer, retryTemplate);
}
在这个配置中,DeadLetterPublishingRecoverer 负责将最终失败的消息转发到名为 {topic}.DLQ 的主题。这种处理方式避免了因个别坏消息导致整个消费者组停滞的问题。同时,globalErrorHandler 依然会在每次重试前被调用,允许你在重试间隙进行监控数据的更新。这种组合策略既保证了系统的健壮性,又提供了完整的可观测性。
特定 Topic 的异常处理差异
在实际项目中,不同 Topic 的业务重要性不同,可能需要针对特定 Topic 应用不同的异常处理策略。可以通过创建多个 KafkaListenerContainerFactory Bean,并为它们分别绑定不同的 ErrorHandler 来实现差异化处理。例如,对于订单类 Topic,可以使用更严格的重试策略;而对于日志类 Topic,可以直接丢弃或快速进入死信队列。


















