消息队列 / 系统课时
实现重试与死信流程
实现重试与死信流程
订单事件消费失败时,系统既不能无限重试拖垮消费组,也不能直接丢弃。这里用 Spring Kafka 建立“有限重试 → Dead Letter Topic → 人工检查 → 修复后重放”的闭环,并把失败次数与原始记录元数据保留下来,便于定位和恢复。
学习目标
- 为可恢复异常配置有限次数和固定退避重试
- 将最终失败记录写入 Dead Letter Topic,并保留失败上下文
- 提供受控的人工重放入口,避免毒消息形成无限循环
先区分两类失败
重试只对“稍后可能成功”的错误有价值,例如下游服务短暂超时、连接池耗尽或瞬时网络故障。参数缺失、业务状态非法这类确定性错误,重复执行通常仍会失败,应尽快进入死信流程。
在订单平台中可以把 IllegalStateException 一类临时故障留给重试,把 IllegalArgumentException 这类数据问题标记为不可重试。这样能控制恢复延迟,也不会让同一条坏消息长期占住分区。

配置有限重试和 DLT
下面的配置让监听器第一次失败后再重试 2 次,每次间隔 1 秒;三次处理机会都失败后,DeadLetterPublishingRecoverer 会把记录发送到默认的 <原主题>.DLT。IllegalArgumentException 被声明为不可重试,会直接进入恢复器。以下为片段示例,依赖应用中已有的 ConsumerFactory<String, OrderEvent>、KafkaTemplate 和 OrderEvent 类型。
package com.example.orders;
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.core.KafkaTemplate;
import org.springframework.kafka.listener.CommonErrorHandler;
import org.springframework.kafka.listener.DefaultErrorHandler;
import org.springframework.kafka.listener.DeadLetterPublishingRecoverer;
import org.springframework.util.backoff.FixedBackOff;
@Configuration
public class KafkaRetryConfig {
@Bean
CommonErrorHandler orderErrorHandler(KafkaTemplate<Object, Object> template) {
DeadLetterPublishingRecoverer recoverer =
new DeadLetterPublishingRecoverer(template);
// 1000 ms 退避、2 次重试:加上首次处理,共 3 次机会。
DefaultErrorHandler handler =
new DefaultErrorHandler(recoverer, new FixedBackOff(1000L, 2L));
handler.addNotRetryableExceptions(IllegalArgumentException.class);
return handler;
}
@Bean
ConcurrentKafkaListenerContainerFactory<String, OrderEvent> kafkaListenerContainerFactory(
ConsumerFactory<String, OrderEvent> consumerFactory,
CommonErrorHandler orderErrorHandler) {
ConcurrentKafkaListenerContainerFactory<String, OrderEvent> factory =
new ConcurrentKafkaListenerContainerFactory<>();
factory.setConsumerFactory(consumerFactory);
factory.setCommonErrorHandler(orderErrorHandler);
// 暴露 delivery attempt,便于日志和指标观测。
factory.getContainerProperties().setDeliveryAttemptHeader(true);
return factory;
}
}生效后,可恢复异常会按固定退避重试;不可恢复异常或重试耗尽的记录会进入 DLT。默认恢复器沿用原记录分区,因此生产环境应确保 DLT 的分区数不少于原主题。
消费代码应把尝试次数写进结构化日志,方便按订单号和重试次数检索。以下仍是片段示例,复用前面的 OrderEvent 和监听容器配置。
package com.example.orders;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.kafka.support.KafkaHeaders;
import org.springframework.messaging.handler.annotation.Header;
import org.springframework.stereotype.Component;
@Component
public class OrderEventListener {
@KafkaListener(topics = "orders.created", groupId = "order-platform")
public void onMessage(
OrderEvent event,
@Header(name = KafkaHeaders.DELIVERY_ATTEMPT, required = false) Integer attempt) {
int currentAttempt = attempt == null ? 1 : attempt;
System.out.printf("orderId=%s attempt=%d%n", event.orderId(), currentAttempt);
if (event.orderId() == null || event.orderId().isBlank()) {
throw new IllegalArgumentException("orderId is required");
}
process(event);
}
private void process(OrderEvent event) {
// 这里调用真实订单处理逻辑;临时故障可抛出可重试异常。
}
}预期输出
orderId=O-1001 attempt=1如果处理继续抛出可重试异常,后续日志中的 attempt 会递增;实际日志时间和线程名可能不同。
记录失败元数据
DLT 的价值不只是“存一份失败消息”,还要能回答它从哪里来、为什么失败。DeadLetterPublishingRecoverer 会在死信记录头中附带原始主题、分区、偏移量以及异常信息。不同 Spring Kafka 版本的具体 header 名可能不同,因此审计消费者最好直接枚举 ConsumerRecord.headers(),而不是只打印消息体。下面为片段示例,依赖相同的 OrderEvent 反序列化配置。
package com.example.orders;
import java.nio.charset.StandardCharsets;
import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;
@Component
public class OrderDltAuditListener {
@KafkaListener(topics = "orders.created.DLT", groupId = "order-dlt-audit")
public void onDlt(ConsumerRecord<String, OrderEvent> record) {
System.out.printf("dlt key=%s partition=%d offset=%d%n",
record.key(), record.partition(), record.offset());
record.headers().forEach(header -> System.out.printf(
"header %s=%s%n",
header.key(),
header.value() == null
? "<null>"
: new String(header.value(), StandardCharsets.UTF_8)));
}
}预期输出
dlt key=O-1001 partition=<ID> offset=<ID>
header <VALUE>=<VALUE><ID> 与 <VALUE> 会随实际分区、偏移量、Spring Kafka 版本和异常内容变化。生产环境应把 DLT 主题、原始偏移量、订单号、异常类型和首次失败时间写入日志或指标系统,形成可搜索的故障记录。
提供受控的人工重放入口
重放必须发生在根因已经修复之后,否则只是把毒消息再次送回失败链路。最小做法是提供一个仅限内部访问的管理接口,由运维人员把确认过的事件重新发布到原主题。下面为片段示例,依赖 Spring Web、KafkaTemplate<String, OrderEvent> 与已有的 OrderEvent 类型。
package com.example.orders;
import org.springframework.http.ResponseEntity;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/admin/dlt")
public class DltReplayController {
private final KafkaTemplate<String, OrderEvent> kafkaTemplate;
public DltReplayController(KafkaTemplate<String, OrderEvent> kafkaTemplate) {
this.kafkaTemplate = kafkaTemplate;
}
@PostMapping("/replay")
public ResponseEntity<Void> replay(@RequestBody OrderEvent event) {
kafkaTemplate.send("orders.created", event.orderId(), event);
return ResponseEntity.accepted().build();
}
}应用实际端口可能不同,用 <PORT> 替换。
curl -i -X POST "http://localhost:<PORT>/admin/dlt/replay" -H "Content-Type: application/json" -d '{"orderId":"O-1001","status":"CREATED"}'预期结果
HTTP/1.1 202