Spring Boot 3 + Kafka 消息重试与死信队列实战
一、为什么需要重试与死信队列
在订单、支付、通知这类业务里,生产者把消息写入 Kafka 只是第一步,真正的风险在消费端:下游接口超时、数据库瞬间不可用、消息体本身有脏数据。消费失败时如果直接提交位移丢弃消息,业务数据就丢了;如果无限重试,又会堵住整个分区。重试 + 死信队列(DLT)就是在两者之间取一个折中:先按退避策略重试几次,仍失败再转入死信主题,由人工或补偿任务处理。
需要先说清一个事实:Kafka 本身没有像 RabbitMQ 那样的原生死信队列概念,死信主题是应用层(这里是 Spring Kafka)在消费端实现出来的。理解这一点,就能明白下面配置里每个组件的职责。
二、两种主流做法:怎么选
1. DefaultErrorHandler + DeadLetterPublishingRecoverer(推荐)
Spring Kafka 3.x(Spring Boot 3.x 对应版本)中,DefaultErrorHandler 是消费端异常处理的默认入口:它按配置的退避策略对同一条记录做 seek 重试,重试耗尽后把记录交给 DeadLetterPublishingRecoverer,由它把记录原样发送到死信主题。默认的死信主题名是原主题名加 .DLT 后缀,例如 order-events 的死信主题就是 order-events.DLT。
2. @RetryableTopic(声明式)
在监听方法上加 @RetryableTopic 注解,Spring Kafka 会自动创建带 -retry- 后缀的重试主题和带 -dlt 后缀的死信主题,并用延时把失败消息逐级转发。写法更简洁,适合快速落地;缺点是主题数量会随着重试级数翻倍,运维上要多留意主题清单和分区数。
本文以第一种方式为主写完整代码,因为它对重试次数、退避间隔、死信去向的控制最直接;第二种方式只在文末给出关键注解示例,方便对照。
三、实战:一个订单事件消费者的完整实现
场景:订单服务把订单创建事件写入 order-events 主题,消费者负责把事件写入订单明细库并调用库存服务预占库存。示例代码使用 Spring Boot 3.x + spring-kafka,版本号以项目实际使用的为准;下面出现的重试间隔、次数均为示例值,请按业务容忍度调整。
1. 依赖与配置
<!-- 示例:仅列出与本文相关的依赖,版本由 Spring Boot 依赖管理统一控制 -->
<dependency>
<groupId>org.springframework.kafka</groupId>
<artifactId>spring-kafka</artifactId>
</dependency>
spring:
kafka:
bootstrap-servers: localhost:9092 # 示例地址
consumer:
group-id: order-consumer-group
enable-auto-commit: false
auto-offset-reset: earliest
max-poll-records: 10 # 示例值
key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
producer:
key-serializer: org.apache.kafka.common.serialization.StringSerializer
value-serializer: org.apache.kafka.common.serialization.StringSerializer
listener:
ack-mode: manual_immediate
要点:enable-auto-commit: false + manual_immediate,让位移提交完全由消费结果驱动;否则还没处理完就提交了位移,失败的消息再也回不来。
2. 消费者与错误处理器
@Component
public class OrderEventListener {
// 示例:监听订单事件主题
@KafkaListener(topics = "order-events", groupId = "order-consumer-group")
public void onOrderCreated(ConsumerRecord<String, String> record,
Acknowledgment ack) {
// 1. 按业务主键做幂等判断(见第五节)
// 2. 写库 + 调用库存预占
// 3. 成功后手动提交位移
ack.acknowledge();
}
// 死信主题的消费者:只记录与告警,不再做业务处理
@KafkaListener(topics = "order-events.DLT", groupId = "order-dlt-group")
public void onDeadLetter(ConsumerRecord<String, String> record) {
// 示例:记录死信消息的 key、分区、offset 与原始异常头信息,
// 落库到死信登记表并触发告警,等待人工处理
}
}
@Configuration
public class KafkaErrorHandlerConfig {
@Bean
public DefaultErrorHandler errorHandler(KafkaTemplate<String, String> kafkaTemplate) {
// 失败记录的去向:默认发送到“原主题名 + .DLT”的主题
DeadLetterPublishingRecoverer recoverer =
new DeadLetterPublishingRecoverer(kafkaTemplate);
// 指数退避:示例值,初始 1 秒、倍数 2、最大 10 秒、最多重试 3 次
ExponentialBackOff backOff = new ExponentialBackOff(1000L, 2.0);
backOff.setMaxInterval(10_000L);
backOff.setMaxElapsedTime(60_000L);
DefaultErrorHandler handler = new DefaultErrorHandler(recoverer, backOff);
// 不可重试的异常直接进死信,不浪费重试次数
handler.addNotRetryableExceptions(IllegalArgumentException.class);
return handler;
}
}
3. 生产者:给消息一个业务唯一键
// 示例:用订单号作为 key,同一订单的消息固定落到同一分区,保证分区内顺序
kafkaTemplate.send("order-events", orderNo, payload);
4. @RetryableTopic 的关键注解示例(对照)
// 示例:声明式重试,attempts 含首次消费;
// backoff 为示例值;dltStrategy 决定重试耗尽后是否进入死信主题
@RetryableTopic(
attempts = "4",
backoff = @Backoff(delay = 1000, multiplier = 2.0, maxDelay = 10_000),
dltStrategy = DltStrategy.FAIL_ON_ERROR)
@KafkaListener(topics = "order-events", groupId = "order-consumer-group")
public void onOrderCreated(String payload) {
// 业务处理
}
@DltHandler
public void handleDlt(String payload) {
// 死信处理:登记 + 告警
}
四、重试时最容易踩的四个坑
- 重试会打乱分区顺序:
DefaultErrorHandler的重试是对同一条记录做 seek 回放,重试期间同分区的后续消息都会被阻塞;对顺序敏感的业务,要评估重试间隔与次数对延迟的影响。 - 不可重试异常要立刻放行:消息体格式错误、业务校验失败这类重试多少次都不会成功的异常,应通过
addNotRetryableExceptions直接进死信,否则等于用重试次数换延迟。 - 死信不是垃圾箱:死信主题需要配套的消费、登记与告警,否则失败消息只是换了个地方躺着。建议至少做到:死信入库登记 + 达到阈值告警 + 人工重放入口。
- 重试次数与 max-poll-interval 的关系:单次重试链路的总耗时不要超过
max.poll.interval.ms,否则消费者会被判定死亡并触发重平衡。
五、幂等:重试的前提条件
重试意味着同一条消息可能被处理多次,所以消费逻辑必须是幂等的。常见做法:用业务唯一键(示例:订单号)做数据库唯一约束,重复写入时依赖约束去重;或者先查后写时用 Redis 的 SETNX 占位。两种方式都要保证“查 + 写”是原子的,示例中用唯一约束是最稳妥的一层兜底。
六、小结
- Kafka 没有原生死信队列,死信主题是 Spring Kafka 在应用层实现的。
- Spring Boot 3.x 下优先使用
DefaultErrorHandler+DeadLetterPublishingRecoverer,退避策略与死信去向都可控;想少写配置时可用@RetryableTopic。 - 手动提交位移、区分可重试与不可重试异常、给死信配登记与告警、保证消费幂等,这四件事缺一不可。
- 点赞
- 收藏
- 关注作者
评论(0)