Spring Boot 集成 Kafka 实战：生产者确认 + 消费者重试 + 死信队列实现-优快云博客

在分布式系统中，消息队列是实现异步通信、解耦服务、削峰填谷的核心组件，而 Kafka 凭借其高吞吐、高可用、高容错的特性，成为企业级应用的首选。Spring Boot 作为主流的微服务开发框架，提供了对 Kafka 的便捷集成能力。

本文将聚焦 Kafka 集成中的三个核心痛点：生产者消息可靠性（避免消息丢失）、消费者异常处理（避免消息消费失败直接丢弃）、死信队列机制（隔离处理无法修复的异常消息），通过实战代码演示完整实现方案，帮助开发者构建健壮的 Kafka 消息链路。

一、环境准备

1.1 基础环境

JDK 1.8+（Spring Boot 2.x 推荐）
Spring Boot 2.7.x（稳定版本，兼容性好）
Kafka 2.8.x（单机/集群均可，本文以单机为例）
Maven 3.6+

1.2 Kafka 环境搭建（单机）

下载 Kafka 安装包：从 Kafka 官网下载对应版本，解压至本地目录。
启动 Zookeeper（Kafka 依赖 Zookeeper 管理元数据）：


# 进入 Kafka 根目录
cd kafka_2.13-2.8.2
# 启动 Zookeeper（后台运行）
nohup bin/zookeeper-server-start.sh config/zookeeper.properties

启动 Kafka 服务：


# 启动 Kafka 服务（后台运行）
nohup bin/kafka-server-start.sh config/server.properties

验证 Kafka 启动成功：通过 jps 命令查看是否存在 Kafka 和QuorumPeerMain（Zookeeper 进程）。

1.3 项目依赖配置

在 Spring Boot 项目的 pom.xml 中引入 Kafka Starter 依赖：


<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Kafka 集成依赖 -->
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>
<!-- 工具类依赖（可选，用于 JSON 序列化） -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version>
</dependency>
<!-- 测试依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

二、核心概念梳理

在动手编码前，先明确三个核心功能的设计目标，避免理解偏差：

生产者确认（Producer ACK）：Kafka 生产者发送消息后，通过配置 ACK 级别，确保消息被 Broker 接收并持久化后再返回成功，避免因网络波动、Broker 宕机导致消息丢失。
消费者重试（Consumer Retry）：消费者处理消息时若出现临时异常（如数据库连接超时、接口临时不可用），不直接丢弃消息，而是通过重试机制重新消费，提高消息处理成功率。
死信队列（Dead-Letter Queue, DLQ）：当消息重试达到最大次数仍处理失败（如消息格式错误、业务逻辑无法兼容），将消息转发至专门的死信队列，避免阻塞正常消息消费，同时便于后续人工排查。

三、完整实现方案

3.1 全局配置（application.yml）

集中配置 Kafka 连接信息、生产者确认机制、消费者重试策略及死信队列规则，核心配置已添加注释说明：


spring:
  kafka:
    # Kafka 集群地址（单机填 localhost:9092）
    bootstrap-servers: localhost:9092
    # 生产者配置
    producer:
      # 消息键序列化方式
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      # 消息值序列化方式（使用 FastJSON 自定义序列化器）
      value-serializer: com.example.kafka.serializer.FastJsonSerializer
      # 生产者确认级别：acks=1 表示消息被 Leader 副本接收并持久化后确认
      # 可选值：0（发送即返回，可能丢失）、1（Leader 确认，默认）、all（所有 ISR 副本确认，最可靠）
      acks: 1
      # 重试次数：消息发送失败时的重试次数
      retries: 3
      # 批次大小：达到批次大小后发送消息（单位：字节）
      batch-size: 16384
      # 缓冲区大小：生产者缓冲区大小（单位：字节）
      buffer-memory: 33554432
    # 消费者配置
    consumer:
      # 消息键反序列化方式
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      # 消息值反序列化方式
      value-deserializer: com.example.kafka.serializer.FastJsonDeserializer
      # 消费者组 ID（同一组内消费者分摊消费，不同组重复消费）
      group-id: kafka-demo-group
      # 自动提交偏移量：false 表示手动提交，确保消息处理完成后再提交
      enable-auto-commit: false
      # 自动提交偏移量的间隔（enable-auto-commit=true 时生效）
      auto-commit-interval: 1000
      # 偏移量重置策略：earliest 表示无偏移量时从头消费，latest 表示从最新消息开始
      auto-offset-reset: earliest
    # Kafka 监听器配置（消费者相关）
    listener:
      # 手动提交偏移量模式：RECORD 表示每条消息处理完成后提交
      ack-mode: MANUAL_IMMEDIATE
      # 并发消费数：根据 Topic 分区数配置（建议不超过分区数）
      concurrency: 2
      # 重试配置
      retry:
        # 开启重试
        enabled: true
        # 最大重试次数（包括首次消费，共 3 次）
        max-attempts: 3
        # 重试间隔（单位：毫秒）
        initial-interval: 1000
# 自定义配置：Topic 名称和死信队列 Topic 名称
kafka:
  topic:
    normal: kafka-normal-topic  # 正常业务 Topic
    dead: kafka-dead-topic      # 死信队列 Topic

3.2 自定义 JSON 序列化器

Kafka 默认的序列化器不支持复杂 Java 对象，这里使用 FastJSON 实现自定义序列化/反序列化器，确保消息能正确转换：

3.2.1 序列化器（FastJsonSerializer）


package com.example.kafka.serializer;

import com.alibaba.fastjson.JSON;
import org.apache.kafka.common.serialization.Serializer;
import java.util.Map;

/**
 * Kafka 消息 JSON 序列化器
 */
public class FastJsonSerializer implements Serializer<Object> {

    @Override
    public void configure(Map<String, ?> configs, boolean isKey) {
        // 初始化配置（可选）
    }

    @Override
    public byte[] serialize(String topic, Object data) {
        if (data == null) {
            return null;
        }
        // 将 Java 对象转为 JSON 字节数组
        return JSON.toJSONBytes(data);
    }

    @Override
    public void close() {
        // 资源释放（可选）
    }
}

3.2.2 反序列化器（FastJsonDeserializer）


package com.example.kafka.serializer;

import com.alibaba.fastjson.JSON;
import org.apache.kafka.common.serialization.Deserializer;
import java.util.Map;

/**
 * Kafka 消息 JSON 反序列化器
 */
public class FastJsonDeserializer implements Deserializer<Object> {

    @Override
    public void configure(Map<String, ?> configs, boolean isKey) {
        // 初始化配置（可选）
    }

    @Override
    public Object deserialize(String topic, byte[] data) {
        if (data == null) {
            return null;
        }
        // 将 JSON 字节数组转为 Object（实际使用时可指定具体类型）
        return JSON.parse(data);
    }

    @Override
    public void close() {
        // 资源释放（可选）
    }
}

3.3 Topic 与死信队列配置

通过 Spring 配置类自动创建 Topic 和死信队列，避免手动执行 Kafka 命令创建，提高项目可移植性：


package com.example.kafka.config;

import org.apache.kafka.clients.admin.NewTopic;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.kafka.config.TopicBuilder;

/**
 * Kafka Topic 配置类
 */
@Configuration
public class KafkaTopicConfig {

    // 正常业务 Topic 名称
    @Value("${kafka.topic.normal}")
    private String normalTopic;

    // 死信队列 Topic 名称
    @Value("${kafka.topic.dead}")
    private String deadTopic;

    /**
     * 创建正常业务 Topic
     * 分区数：3（提高并发消费能力）
     * 副本数：1（单机环境，集群环境建议设为 2-3）
     */
    @Bean
    public NewTopic normalTopic() {
        return TopicBuilder.name(normalTopic)
                .partitions(3)
                .replicas(1)
                .build();
    }

    /**
     * 创建死信队列 Topic
     * 分区数与正常 Topic 一致，便于排查
     */
    @Bean
    public NewTopic deadTopic() {
        return TopicBuilder.name(deadTopic)
                .partitions(3)
                .replicas(1)
                .build();
    }
}

3.4 生产者实现（消息发送）

封装 Kafka 生产者工具类，提供同步发送和异步发送两种方式，满足不同业务场景需求：


package com.example.kafka.producer;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.kafka.support.SendResult;
import org.springframework.stereotype.Component;
import org.springframework.util.concurrent.ListenableFuture;
import org.springframework.util.concurrent.ListenableFutureCallback;

/**
 * Kafka 生产者工具类
 */
@Component
public class KafkaProducer {

    // 注入 Kafka 模板
    @Autowired
    private KafkaTemplate<String, Object> kafkaTemplate;

    // 正常业务 Topic 名称
    @Value("${kafka.topic.normal}")
    private String normalTopic;

    /**
     * 同步发送消息
     * 特点：阻塞等待结果，适合需要立即知道发送状态的场景
     */
    public boolean sendSync(String key, Object message) {
        try {
            // 同步发送，返回发送结果
            SendResult<String, Object> result = kafkaTemplate.send(normalTopic, key, message).get();
            // 打印发送成功日志
            System.out.printf("同步发送成功 - Topic: %s, Partition: %d, Offset: %d%n",
                    result.getRecordMetadata().topic(),
                    result.getRecordMetadata().partition(),
                    result.getRecordMetadata().offset());
            return true;
        } catch (Exception e) {
            // 处理发送异常（如 Broker 不可用、网络异常等）
            System.err.printf("同步发送失败 - Key: %s, Message: %s, Error: %s%n", key, message, e.getMessage());
            return false;
        }
    }

    /**
     * 异步发送消息
     * 特点：非阻塞，通过回调获取结果，适合高吞吐场景
     */
    public void sendAsync(String key, Object message) {
        // 异步发送，获取 Future 对象
        ListenableFuture<SendResult<String, Object>> future = kafkaTemplate.send(normalTopic, key, message);
        
        // 添加发送结果回调
        future.addCallback(new ListenableFutureCallback<SendResult<String, Object>>() {
            @Override
            public void onSuccess(SendResult<String, Object> result) {
                // 发送成功回调
                System.out.printf("异步发送成功 - Topic: %s, Partition: %d, Offset: %d%n",
                        result.getRecordMetadata().topic(),
                        result.getRecordMetadata().partition(),
                        result.getRecordMetadata().offset());
            }

            @Override
            public void onFailure(Throwable ex) {
                // 发送失败回调
                System.err.printf("异步发送失败 - Key: %s, Message: %s, Error: %s%n", key, message, ex.getMessage());
            }
        });
    }
}

3.5 消费者实现（重试 + 死信队列）

这是核心模块，通过 @KafkaListener 注解监听消息，结合 SeekToCurrentErrorHandler 实现重试机制，并将重试失败的消息转发至死信队列：

3.5.1 消费者配置类（重试与死信逻辑）


package com.example.kafka.config;

import org.springframework.beans.factory.annotation.Value;
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.DeadLetterPublishingRecoverer;
import org.springframework.kafka.listener.SeekToCurrentErrorHandler;
import org.springframework.kafka.support.converter.RecordMessageConverter;
import org.springframework.kafka.support.converter.StringJsonMessageConverter;

/**
 * Kafka 消费者配置类（重试 + 死信队列）
 */
@Configuration
public class KafkaConsumerConfig {

    // 死信队列 Topic 名称
    @Value("${kafka.topic.dead}")
    private String deadTopic;

    /**
     * 消息转换器：将 JSON 字符串转为 Java 对象
     */
    @Bean
    public RecordMessageConverter messageConverter() {
        return new StringJsonMessageConverter();
    }

    /**
     * 配置 Kafka 监听容器工厂
     * 核心：添加错误处理器，实现重试和死信转发
     */
    @Bean
    public ConcurrentKafkaListenerContainerFactory<String, Object> kafkaListenerContainerFactory(
            ConsumerFactory<String, Object> consumerFactory,
            DeadLetterPublishingRecoverer deadLetterPublishingRecoverer) {
        
        ConcurrentKafkaListenerContainerFactory<String, Object> factory = new ConcurrentKafkaListenerContainerFactory<>();
        factory.setConsumerFactory(consumerFactory);
        // 设置消息转换器
        factory.setMessageConverter(messageConverter());
        // 设置手动提交偏移量
        factory.getContainerProperties().setAckMode(org.springframework.kafka.listener.ContainerProperties.AckMode.MANUAL_IMMEDIATE);
        
        // 配置错误处理器：SeekToCurrentErrorHandler 实现重试，重试失败后转发至死信队列
        SeekToCurrentErrorHandler errorHandler = new SeekToCurrentErrorHandler(deadLetterPublishingRecoverer);
        // 禁止重试时回溯偏移量（避免重复消费其他消息）
        errorHandler.setResetOffsets(false);
        factory.setErrorHandler(errorHandler);
        
        return factory;
    }

    /**
     * 死信发布恢复器：将重试失败的消息转发至死信队列
     */
    @Bean
    public DeadLetterPublishingRecoverer deadLetterPublishingRecoverer(
            org.springframework.kafka.core.KafkaTemplate<String, Object> kafkaTemplate) {
        // 自定义死信队列转发逻辑：将消息发送至指定的死信 Topic
        return (record, exception) -> {
            System.err.printf("消息转发至死信队列 - Topic: %s, Key: %s, Error: %s%n",
                    deadTopic, record.key(), exception.getMessage());
            // 发送消息到死信队列
            return kafkaTemplate.send(deadTopic, record.key(), record.value());
        };
    }
}

3.5.2 消费者监听类（消息处理逻辑）


package com.example.kafka.consumer;

import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.kafka.support.Acknowledgment;
import org.springframework.stereotype.Component;

/**
 * Kafka 消费者监听类
 * 包含：正常消息消费 + 死信消息消费
 */
@Component
public class KafkaConsumer {

    // 正常业务 Topic 名称
    @Value("${kafka.topic.normal}")
    private String normalTopic;

    // 死信队列 Topic 名称
    @Value("${kafka.topic.dead}")
    private String deadTopic;

    /**
     * 监听正常业务 Topic，处理消息
     * topics：监听的 Topic 名称
     * containerFactory：指定上文配置的容器工厂（包含重试和死信逻辑）
     */
    @KafkaListener(topics = "${kafka.topic.normal}", containerFactory = "kafkaListenerContainerFactory")
    public void consumeNormalMessage(ConsumerRecord<String, Object> record, Acknowledgment acknowledgment) {
        try {
            // 1. 获取消息内容
            String key = record.key();
            Object value = record.value();
            System.out.printf("接收到正常消息 - Topic: %s, Partition: %d, Offset: %d, Key: %s, Value: %s%n",
                    record.topic(), record.partition(), record.offset(), key, value);
            
            // 2. 模拟业务逻辑（这里故意抛出异常，测试重试和死信）
            // 实际场景中替换为真实业务代码（如数据库操作、接口调用等）
            if ("error-key".equals(key)) {
                throw new RuntimeException("模拟业务异常：消息处理失败");
            }
            
            // 3. 业务处理成功，手动提交偏移量
            acknowledgment.acknowledge();
            System.out.printf("正常消息处理成功 - Key: %s%n", key);
        } catch (Exception e) {
            // 4. 业务处理失败，抛出异常（由容器工厂的错误处理器接管，进行重试）
            System.err.printf("正常消息处理失败 - Key: %s, Error: %s%n", record.key(), e.getMessage());
            throw e; // 必须抛出异常，否则重试机制不生效
        }
    }

    /**
     * 监听死信队列 Topic，处理无法修复的异常消息
     * 实际场景中可在此进行人工通知、日志记录、数据备份等操作
     */
    @KafkaListener(topics = "${kafka.topic.dead}", groupId = "kafka-dead-group")
    public void consumeDeadLetterMessage(ConsumerRecord<String, Object> record, Acknowledgment acknowledgment) {
        // 1. 获取死信消息内容
        String key = record.key();
        Object value = record.value();
        System.err.printf("接收到死信消息 - Topic: %s, Partition: %d, Offset: %d, Key: %s, Value: %s%n",
                record.topic(), record.partition(), record.offset(), key, value);
        
        // 2. 死信消息处理逻辑（示例：记录日志、发送告警邮件等）
        // sendAlarmEmail(key, value); // 模拟发送告警
        // saveToDB(key, value); // 保存死信消息到数据库
        
        // 3. 死信消息处理完成，手动提交偏移量
        acknowledgment.acknowledge();
        System.out.printf("死信消息处理完成 - Key: %s%n", key);
    }
}

3.6 测试接口（便于快速验证）

创建一个简单的 REST 接口，通过 HTTP 请求触发消息发送，方便测试生产者、消费者、重试及死信队列的完整链路：


package com.example.kafka.controller;

import com.example.kafka.producer.KafkaProducer;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * 测试控制器：用于发送 Kafka 消息
 */
@RestController
public class KafkaTestController {

    @Autowired
    private KafkaProducer kafkaProducer;

    /**
     * 同步发送消息接口
     * 访问示例：http://localhost:8080/kafka/send/sync?key=test-key&message=hello-kafka
     */
    @GetMapping("/kafka/send/sync")
    public String sendSync(@RequestParam String key, @RequestParam String message) {
        boolean success = kafkaProducer.sendSync(key, message);
        return success ? "同步发送成功" : "同步发送失败";
    }

    /**
     * 异步发送消息接口
     * 访问示例：http://localhost:8080/kafka/send/async?key=error-key&message=error-message
     */
    @GetMapping("/kafka/send/async")
    public String sendAsync(@RequestParam String key, @RequestParam String message) {
        kafkaProducer.sendAsync(key, message);
        return "异步发送请求已提交（请查看控制台日志）";
    }
}

四、实战验证

4.1 启动项目

启动 Spring Boot 项目，观察控制台日志，确认 Kafka 连接成功，Topic 自动创建完成。

4.2 测试正常消息流程

访问同步发送接口，发送正常消息：


http://localhost:8080/kafka/send/sync?key=normal-key&message=这是一条正常消息

观察控制台日志，应输出以下内容（流程：生产者发送成功 → 消费者接收并处理 → 提交偏移量）：


同步发送成功 - Topic: kafka-normal-topic, Partition: 1, Offset: 0
接收到正常消息 - Topic: kafka-normal-topic, Partition: 1, Offset: 0, Key: normal-key, Value: 这是一条正常消息
正常消息处理成功 - Key: normal-key

4.3 测试重试与死信队列流程

访问异步发送接口，发送触发异常的消息（Key 为 “error-key”，消费者会故意抛出异常）：


http://localhost:8080/kafka/send/async?key=error-key&message=这是一条会触发异常的消息

观察控制台日志，应输出以下内容（流程：生产者发送成功 → 消费者接收并抛出异常 → 重试 2 次（共 3 次） → 转发至死信队列 → 死信消费者处理）：


异步发送成功 - Topic: kafka-normal-topic, Partition: 2, Offset: 0
接收到正常消息 - Topic: kafka-normal-topic, Partition: 2, Offset: 0, Key: error-key, Value: 这是一条会触发异常的消息
正常消息处理失败 - Key: error-key, Error: 模拟业务异常：消息处理失败
// 第 1 次重试
接收到正常消息 - Topic: kafka-normal-topic, Partition: 2, Offset: 0, Key: error-key, Value: 这是一条会触发异常的消息
正常消息处理失败 - Key: error-key, Error: 模拟业务异常：消息处理失败
// 第 2 次重试（达到最大重试次数 3 次）
接收到正常消息 - Topic: kafka-normal-topic, Partition: 2, Offset: 0, Key: error-key, Value: 这是一条会触发异常的消息
正常消息处理失败 - Key: error-key, Error: 模拟业务异常：消息处理失败
// 转发至死信队列
消息转发至死信队列 - Topic: kafka-dead-topic, Key: error-key, Error: 模拟业务异常：消息处理失败
// 死信消费者处理
接收到死信消息 - Topic: kafka-dead-topic, Partition: 2, Offset: 0, Key: error-key, Value: 这是一条会触发异常的消息
死信消息处理完成 - Key: error-key