消息队列 / 系统课时

实现重试与死信流程

实现重试与死信流程

订单事件消费失败时,系统既不能无限重试拖垮消费组,也不能直接丢弃。这里用 Spring Kafka 建立“有限重试 → Dead Letter Topic → 人工检查 → 修复后重放”的闭环,并把失败次数与原始记录元数据保留下来,便于定位和恢复。

学习目标

  • 为可恢复异常配置有限次数和固定退避重试
  • 将最终失败记录写入 Dead Letter Topic,并保留失败上下文
  • 提供受控的人工重放入口,避免毒消息形成无限循环

先区分两类失败

重试只对“稍后可能成功”的错误有价值,例如下游服务短暂超时、连接池耗尽或瞬时网络故障。参数缺失、业务状态非法这类确定性错误,重复执行通常仍会失败,应尽快进入死信流程。

在订单平台中可以把 IllegalStateException 一类临时故障留给重试,把 IllegalArgumentException 这类数据问题标记为不可重试。这样能控制恢复延迟,也不会让同一条坏消息长期占住分区。

订单事件重试、死信与人工重放流程

配置有限重试和 DLT

下面的配置让监听器第一次失败后再重试 2 次,每次间隔 1 秒;三次处理机会都失败后,DeadLetterPublishingRecoverer 会把记录发送到默认的 <原主题>.DLT。IllegalArgumentException 被声明为不可重试,会直接进入恢复器。以下为片段示例,依赖应用中已有的 ConsumerFactory<String, OrderEvent>、KafkaTemplate 和 OrderEvent 类型。

java
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 和监听容器配置。

java
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) {
        // 这里调用真实订单处理逻辑;临时故障可抛出可重试异常。
    }
}

预期输出

text
orderId=O-1001 attempt=1

如果处理继续抛出可重试异常,后续日志中的 attempt 会递增;实际日志时间和线程名可能不同。

记录失败元数据

DLT 的价值不只是“存一份失败消息”,还要能回答它从哪里来、为什么失败。DeadLetterPublishingRecoverer 会在死信记录头中附带原始主题、分区、偏移量以及异常信息。不同 Spring Kafka 版本的具体 header 名可能不同,因此审计消费者最好直接枚举 ConsumerRecord.headers(),而不是只打印消息体。下面为片段示例,依赖相同的 OrderEvent 反序列化配置。

java
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)));
    }
}

预期输出

text
dlt key=O-1001 partition=<ID> offset=<ID>
header <VALUE>=<VALUE>

<ID> 与 <VALUE> 会随实际分区、偏移量、Spring Kafka 版本和异常内容变化。生产环境应把 DLT 主题、原始偏移量、订单号、异常类型和首次失败时间写入日志或指标系统,形成可搜索的故障记录。

提供受控的人工重放入口

重放必须发生在根因已经修复之后,否则只是把毒消息再次送回失败链路。最小做法是提供一个仅限内部访问的管理接口,由运维人员把确认过的事件重新发布到原主题。下面为片段示例,依赖 Spring Web、KafkaTemplate<String, OrderEvent> 与已有的 OrderEvent 类型。

java
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> 替换。

bash
curl -i -X POST "http://localhost:<PORT>/admin/dlt/replay" -H "Content-Type: application/json" -d '{"orderId":"O-1001","status":"CREATED"}'

预期结果

text
HTTP/1.1 202
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现重试与死信流程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通