Kafka生产者-消费者示例：Java开发者入门实战与避坑指南

如果让我给正在学Kafka的Java开发者推荐一个入门项目，我首推的就是基于Java和Kafka的生产者-消费者示例。原因是它虽然只有两个角色，却把Kafka最核心的消息流转链路完整串了起来：生产者把消息发到Topic，Broker负责存储，消费者从Topic里拉取并处理。我见过不少人第一步就卡住——环境搭起来了但本机代码连不上，日志疯狂刷metadata报错，甚至代码写完消费端一条数据都拿不到。这篇文章就从我实际跑通一个可运行的生产者-消费者示例出发，把环境搭建、生产者和消费者的完整代码、每个关键配置背后的理由、以及实测踩过的坑都整理出来，适合正在学Kafka的Java工程师，也适合准备面试时用一个完整示例来串联知识点。

1. 为什么"生产者-消费者"是Kafka最值得先写的Demo

1.1 从一条消息的旅程理解Kafka的核心角色

很多教程一上来就画架构图：Producer、Broker、Topic、Partition、Consumer Group、Offset。图看懂了，动手时还是一头雾水。我建议反过来，先跟一条消息走一遍，再回头看概念就清晰了。

假设你有一个Topic叫demo-topic，分了3个分区（partitions=3）。生产者发送一条消息，实际上是在往某个分区追加一条记录，这条记录被赋予一个递增的offset，在这个分区内严格有序。如果消息带key，Kafka会对key做哈希决定进哪个分区，同一个key总会进同一个分区；如果不带key，就按轮询或粘性分区策略分散到各个分区。Broker的角色更像一个持久化的日志系统，消息写进去之后不会因为消费者读过就删除，而是要等保留策略（retention）到期才清理。这个设计是Kafka能支撑"多个消费组同时读"的关键。

消费者的工作方式也不是常见的"推送"，而是主动拉取（poll）。消费者加入某个消费组后，Kafka会把这个Topic下的分区分配给组内的成员，一个分区在同一时刻只会被同一个消费组内的一个消费者持有。消费者poll一批消息，处理完后提交offset，相当于在日志上做"我读到这了"的标记。这个提交位置就是之后消费恢复的起点。

关于消费组在这里特别重要。同一个groupId内的多个消费者实例共同分担分区；不同groupId的消费者互不干扰，各自都能读到全量消息。打个比方：同一个小区里有两家搬家公司，它们看到的都是整个小区所有信件，一家消费掉的消息不会影响另一家。这也是Kafka能同时服务多个下游业务的基础。

1.2 这个Demo能覆盖的面试题与生产场景

既然要写示例，先把它的价值说清楚。这个看似简单的Demo，其实把Kafka的高频面试点都卡进去了：

• 生产者为什么快：顺序写盘、页缓存、批量发送，这些会对应到batch.size、linger.ms这些参数；
• 消息可靠性：acks、retries、幂等生产者，对应"消息会不会丢"；
• 消费组与rebalance：分区分配策略、消费者数量超过分区数会空转；
• offset与重复消费：自动提交的窗口、手动提交方式、业务侧幂等。

网上很多人备考Kafka相关面试题，与其死记硬背，不如把这段Demo跑通，再对着参数试一遍，每个概念都有真实场景对照，记得更牢。

生产里这个模型同样无处不在：订单系统把消息发给Kafka，库存服务、积分服务、短信服务各自用不同消费组去订阅；高峰期流量先打到Kafka做削峰，下游按自己的处理能力消费。可以说，理解了Producer和Consumer，整个Kafka生态（SpringBoot Kafka、Canal同步、Flink消费）都是在这个底座上长出来的。后面你去看spring-boot-starter-kafka的封装，也只是把这个原生API包了一层。

2. 环境准备：从JDK到可用的Kafka，少走弯路

2.1 版本选型：Java、Kafka、客户端版本怎么配对

版本选型是第一个容易踩坑的点。我的建议非常明确：本地上Java 8或Java 11都行，Kafka Server用3.x最新稳定版，客户端依赖kafka-clients用和服务端一致的版本。这样可以把协议差异的坑降到最低。很多人喜欢客户端随便引入一个版本，结果服务端3.x、客户端2.x，虽然大部分时候能跑，但一旦遇到新特性和协议差异，排查起来非常痛苦。

我本地用的是Java 11，Kafka 3.6.x，pom里引入org.apache.kafka:kafka-clients:3.6.2。这里说明一下：3.6是带KRaft模式稳定的版本，本地单节点可以不依赖ZooKeeper直接启动，环境搭建会省很多事。如果你的环境比较老，只能上2.8之前的版本，那还需要单独跑ZooKeeper，原理不影响，但操作多一步。

对应关系可以看手头的JDK：

顺便补一句，Java环境变量（JAVA_HOME、PATH）如果没配好，IDE会报找不到主类，或者构建工具跑不起来。装JDK后把JAVA_HOME指到安装目录，PATH里加上%JAVA_HOME%/bin，终端执行java -version确认即可。这一步很基础，但我见过不少新手连编译都过不了就是卡在这。

2.2 本地开发环境搭建的两种方式

本地起Kafka，我推荐两种方式，任选其一。

方式一，Docker Compose单节点，最省事。创建一个docker-compose.yml：

yaml复制version: '3.8'
services:
  kafka:
    image: bitnami/kafka:3.6
    container_name: kafka-demo
    ports:
      - "9092:9092"
    environment:
      - KAFKA_CFG_NODE_ID=0
      - KAFKA_CFG_PROCESS_ROLES=controller,broker
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://127.0.0.1:9092
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=0@kafka:9093
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER

然后docker compose up -d，等几秒，用docker logs kafka-demo确认没有报错。这种方式用的是KRaft模式，不需要单独的ZooKeeper服务。很多人的困惑在于为什么这个配置文件里要写ADVERTISED_LISTENERS，这里先埋个伏笔：客户端连Kafka时，先连的是bootstrap.servers，拿到元数据后真正连接的是advertised.listeners暴露的地址。容器内如果把这个地址写成kafka:9092，宿主机上的Java进程就永远连不上。这是本地跑容器版Kafka最常见的坑，后面报错排查会详细讲。

方式二，二进制包直接跑。在Kafka官网下载对应版本的tgz，解压后，如果是3.x的KRaft模式，先执行：

bash复制bin/kafka-storage.sh random-uuid
bin/kafka-storage.sh format -t <uuid> -c config/kraft/server.properties
bin/kafka-server-start.sh config/kraft/server.properties

这种方式能直接看到日志文件，适合想更底层了解Kafka的同学。客户端连不上时，改config/kraft/server.properties里的listeners和advertised.listeners。

无论哪种方式，验证Kafka是否就绪，建议先列出一次topic：

bash复制bin/kafka-topics.sh --bootstrap-server 127.0.0.1:9092 --list

能返回列表（哪怕是空列表）就说明broker可以被客户端访问了。

3. 生产者实现：从最简单的send到生产级配置

3.1 工程结构

先建一个普通的Maven项目，只有一个核心依赖：

xml复制<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>3.6.2</version>
</dependency>

项目结构保持简单：

code复制kafka-demo/
├── pom.xml
└── src/main/java/com/example/kafka/
    ├── SimpleProducer.java
    └── SimpleConsumer.java

我不建议一上来就引SpringBoot，原生API更能让你理解Kafka的行为，而且之后看SpringBoot封装时，也能更明白它帮你做了什么。kafka-clients本身没有额外的传递依赖，不会污染工程。

3.2 Producer代码逐行拆解

直接贴完整代码：

java复制package com.example.kafka;

import org.apache.kafka.clients.producer.*;
import org.apache.kafka.common.serialization.StringSerializer;

import java.util.Properties;

public class SimpleProducer {

    public static void main(String[] args) {
        Properties props = new Properties();
        props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "127.0.0.1:9092");
        props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        props.put(ProducerConfig.ACKS_CONFIG, "all");
        props.put(ProducerConfig.RETRIES_CONFIG, 3);
        props.put(ProducerConfig.LINGER_MS_CONFIG, 5);
        props.put(ProducerConfig.BATCH_SIZE_CONFIG, 16384);

        Producer<String, String> producer = new KafkaProducer<>(props);

        for (int i = 0; i < 100; i++) {
            String key = "key-" + (i % 3);
            String value = "message-" + i;
            ProducerRecord<String, String> record = new ProducerRecord<>("demo-topic", key, value);

            producer.send(record, (metadata, exception) -> {
                if (exception == null) {
                    System.out.println("发送成功，topic=" + metadata.topic()
                            + ", partition=" + metadata.partition()
                            + ", offset=" + metadata.offset());
                } else {
                    System.err.println("发送失败: " + exception.getMessage());
                }
            });
        }

        producer.flush();
        producer.close();
    }
}

拆开看几个关键点：

• BOOTSTRAP_SERVERS_CONFIG是初始连接地址，写127.0.0.1:9092就能连上本机容器里的Kafka。如果你的Kafka跑在别的机器，这里写那台机器对应的地址。
• KEY_SERIALIZER_CLASS_CONFIG和VALUE_SERIALIZER_CLASS_CONFIG必须指定序列化器。字符串消息用StringSerializer，生产环境如果消息体是JSON，可以换JsonSerializer或自定义序列化器。序列化器选错，运行时会直接抛org.apache.kafka.common.errors.SerializationException。
• send()本身是异步操作。调用send时，消息先进入内部缓冲区，由后台的Sender线程批量发送。回调里的metadata包含topic、partition、offset，说明这条消息已经被broker确认写入。这里传了回调，主要是为了在示例里能直观看到发送结果。
• flush()是把缓冲区里积压的消息全部发送出去，close()会阻塞等待所有消息完成并释放资源。在main方法这种一次性程序里，如果忘了这两个调用，进程可能直接退出，你看到的现象就是"回调没执行、消息没到topic"。

3.3 关键参数的解释

我把示例里的关键参数整理成表，方便对照调整：

重点解释两个：

acks=all是最稳妥的确认级别，意味着分区leader写入成功，并且ISR（同步副本）里的所有副本都写入成功后才返回成功。它不能单独保护数据安全，还要配合broker端的min.insync.replicas。比如副本数设为3、min.insync.replicas设为2，那么至少有2个副本写入成功，消息才被确认。否则你即使acks=all，如果ISR里只有一个副本，再遇上这台机器宕机，消息照样可能丢。

linger.ms是很多新手误解的参数。它不是"延迟发送消息"，而是"为了凑批最多等多久"。批量越大，网络IO次数越少，吞吐越高。设成0表示来一条发一条，延迟最低但吞吐也低。本地Demo设5ms就很好，生产环境需要结合压测数据再调。

4. 消费者实现：消费组、offset与幂等消费

4.1 Consumer代码

生产者跑通后，下一步是消费者。完整代码如下：

java复制package com.example.kafka;

import org.apache.kafka.clients.consumer.*;
import org.apache.kafka.common.serialization.StringDeserializer;

import java.time.Duration;
import java.util.Collections;
import java.util.Properties;

public class SimpleConsumer {

    public static void main(String[] args) {
        Properties props = new Properties();
        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "127.0.0.1:9092");
        props.put(ConsumerConfig.GROUP_ID_CONFIG, "demo-group");
        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
        props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
        props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
        props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "true");
        props.put(ConsumerConfig.AUTO_COMMIT_INTERVAL_MS_CONFIG, "1000");

        try (Consumer<String, String> consumer = new KafkaConsumer<>(props)) {
            consumer.subscribe(Collections.singletonList("demo-topic"));
            while (true) {
                ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(1000));
                for (ConsumerRecord<String, String> record : records) {
                    System.out.printf("partition=%d, offset=%d, key=%s, value=%s%n",
                            record.partition(), record.offset(), record.key(), record.value());
                }
            }
        }
    }
}

这段代码的运行机制：subscribe后，消费者会先加入消费组，触发一次rebalance拿到分区分配结果，这个过程是异步的；然后不断调用poll()拉取消息。poll(Duration.ofMillis(1000))表示最多阻塞1秒，有消息就返回一批，没有就返回空集合。真正处理逻辑写在遍历records的循环里。

这里有一个很关键的点：poll循环里的处理逻辑不能太慢。因为消费者在两次poll之间的间隔不能超过max.poll.interval.ms（默认5分钟），否则会被判定为"已经卡死"，把它的分区踢出去触发rebalance；另外心跳线程也会因为处理阻塞而无法及时发送心跳。本地Demo当然没问题，但你得意识到生产环境里，处理慢导致rebalance其实是常见的故障。

4.2 消费组机制与分区分配

消费者能收到哪些消息，完全由group.id决定。我本地Demo固定用demo-group。你多起几个进程，如果它们的group.id都叫demo-group，它们会组成一个消费组，Kafka会把demo-topic的3个分区尽量平均地分给这几个进程。同一消费组内，一条消息只会被一个成员消费一次。这适用于"一个逻辑业务由多个实例水平扩展"的场景，比如订单处理服务部署3个实例，一条订单消息只会被其中一个实例处理。

再起一个group.id叫demo-group-2的消费者，它会成为另一个消费组，能收到demo-topic里的全量消息。这就是多个下游业务各自消费全量数据的基础，比如订单消息既要给库存服务，又要给数据分析服务，它们用不同group.id，互不影响。

分区分配的细节：消费组成员变化时（加入、退出、崩溃），会触发rebalance，由GroupCoordinator协调重新分配分区。常见策略有Range、RoundRobin、Sticky几种。你不需要在Demo阶段死磕每种策略，但一定要记住两个结论：第一，同一个消费组内消费者数量不能无限多，超过分区数时，多出来的消费者会分配到0个分区，白白空转；第二，rebalance期间整个消费组会短暂停止消费，频繁上下线会造成"rebalance风暴"。

4.3 offset提交的坑与幂等消费

我上面给的示例开的是自动提交，这是最省事的写法，但也是最容易埋坑的写法。自动提交的默认逻辑是：poll到一批消息之后，过auto.commit.interval.ms（默认5秒）再提交当前已拉取的最大offset，而不是处理完再提交。也就是说，如果你拉取了一批消息，还没处理完，进程崩了，offset已经被提交或马上被提交到当前拉取位置，重启后这批消息就再也不会被重新消费了——这是消息丢失的一种典型场景。

更稳的做法是手动提交。把ENABLE_AUTO_COMMIT_CONFIG设为false，然后在你确认处理完一批消息后提交：

java复制props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "false");

// 在poll循环内处理完records后
consumer.commitSync();

commitSync会阻塞直到提交成功，适合在正常路径下保证不丢offset；commitAsync是非阻塞的，失败只有日志，不会重试，所以常见组合是：处理完成后先commitAsync提升吞吐，在进程退出前再commitSync兜底。需要注意，手动提交的语义是"当前批次全部处理成功才提交"，如果处理到一半失败，你可以选择不提交，这样重启后会从上次提交点重新消费——这又引入了重复消费。

所以Kafka的默认语义是at least once，重复消息几乎必然出现。业务侧必须做幂等：用消息里的唯一业务ID作为数据库唯一约束，重复插入时捕获冲突；或者用Redis的SETNX做去重；再或者记录处理状态，处理前先查状态。我在Demo里给每条消息构造的key可以当作业务唯一键，真实项目里建议用订单号、流水号这类语义唯一的字段。

5. 实测中最容易翻车的四个报错：完整排查链路

5.1 报错一：Connection refused / 连接超时

现象：生产者在new KafkaProducer后第一次send，日志直接报Connection refused，或者一直卡到TimeoutException。

排查链路我建议按顺序来：

1. 先确认Kafka进程真的活着：docker ps 或 ps -ef | grep kafka 看进程状态。
2. 再确认端口通不通：

bash复制telnet 127.0.0.1 9092

如果不通，大概率是容器端口映射丢了，或者Kafka监听地址不是这个端口。

3. 如果端口通但代码还是连不上，仔细看Kafka的listeners和advertised.listeners配置。

我之前用Docker跑Kafka，第一次就挂在第三步。容器里默认的advertised.listeners可能是kafka:9092，这个地址只有容器内部才能解析，宿主机上的Java进程拿到它以后根本连不上。解决办法在Compose配置里显式指定ADVERTISED_LISTENERS为宿主机可访问的地址，比如127.0.0.1:9092（本机调试）或局域网IP（远程调试）。

5.2 报错二：Error while fetching metadata with correlation id

现象：生产者或消费者启动后，日志刷类似：

code复制Error while fetching metadata with correlation id 1 : {demo-topic=UNKNOWN_TOPIC_OR_PARTITION}

或者LEADER_NOT_AVAILABLE，然后一直重试。

这个问题在Kafka相关的搜索词里出现频率非常高。metadata是Kafka客户端的集群元数据（topic分区和leader信息），fetch metadata失败通常有三种原因。

第一种，bootstrap.servers连到的broker能通信，但advertised.listeners暴露了客户端访问不到的地址。连接链路是：客户端先连bootstrap.servers，请求元数据，broker返回"这些分区的leader在xxx:9092"，如果xxx:9092客户端访问不到，就会一直卡在metadata阶段。这个和5.1的表面现象不同，端口测试可能是通的，因为初始连接成功，但后续内部地址不通。

第二种，topic不存在或者不允许自动创建。默认Kafka允许自动创建topic，但有些环境会关掉auto.create.topics.enable。解决办法是提前创建topic：

bash复制bin/kafka-topics.sh --bootstrap-server 127.0.0.1:9092 --create --topic demo-topic --partitions 3 --replication-factor 1

第三种，客户端与broker版本差异过大，导致协议握手异常。所以前面强调客户端和服务端版本尽量一致。

排查时，先用命令行工具验证broker层是否正常：

bash复制bin/kafka-topics.sh --bootstrap-server 127.0.0.1:9092 --list

如果这条命令能正常列出topic，基本可以确定是客户端配置问题，重点回到advertised.listeners；如果这条命令也报同样的错，那就要去broker日志里看监听配置了。

5.3 报错三：没有报错，但消费者就是收不到消息

现象：Producer端回调打印了发送成功，Consumer启动后也没有任何异常，但控制台一条消息都不打印。

这个坑我猜不少新手都踩过，而且特别容易怀疑人生。排查链路：

1. 先确认Producer和Consumer连的是同一个Kafka集群、同一个topic。注意topic拼写，大小写和连字符都要一致。
2. 确认Consumer的消费组状态和offset。如果Consumer刚启动，且group.id是一个全新的消费组，它的起始位置由auto.offset.reset决定。默认值是latest，含义是"只消费启动之后新产生的消息"。你先跑Producer发了100条消息，再启动Consumer，这100条旧消息就注定收不到。把AUTO_OFFSET_RESET_CONFIG改成earliest，删除原消费组重新启动，就能从最早位置开始消费。
3. 还有一个容易忽略的情况：同一个group.id，你之前已经启动过一个消费者，但这次启动的另一个消费者，因为分区已经分配给了第一个实例，这个新实例可能分不到分区。查看消费组详情：

bash复制bin/kafka-consumer-groups.sh --bootstrap-server 127.0.0.1:9092 --describe --group demo-group

看LAG列，如果为0且没有待消费消息，说明消息确实消费完了；如果还有LAG但你的进程没打印，说明消息被消费组内另一个实例消费了。

5.4 报错四：cluster authorization failed

现象：启用了SASL认证的Kafka环境里，发送或消费时直接抛CLUSTER_AUTHORIZATION_FAILED，失败消息和日志里会带上topic和用户信息。

原因基本只有一个：当前认证用户对这个topic没有对应的写或读权限。Kafka的ACL是白名单机制，没有显式授权就是拒绝。解决办法是给用户授权：

bash复制bin/kafka-acls.sh --bootstrap-server 127.0.0.1:9092 \
  --add --allow-principal User:demo-user \
  --operation Read --operation Write --operation Describe \
  --topic demo-topic

如果你是本地学习环境，最简单的做法是先把SASL关掉，用PLAINTEXT跑通全流程；如果是在公司的开发环境，找管理员开通权限，而不是改代码绕过。注意ACL授权粒度可以精确到topic和消费组，容易漏配，排查时报错里的topic名和group名要仔细看。

6. 从能跑到跑稳：生产环境必经的升级

6.1 可靠性配置

Demo跑通后，下一步是把它往生产标准上靠。先看生产者侧，我把可靠性配置凝练成三个组合：

• acks=all + retries（开启幂等后retries默认会很大）；
• enable.idempotence=true，避免重试导致的重复消息。从Kafka 3.0开始，这个选项默认就是true；
• broker端设置min.insync.replicas=2，配合副本因子至少3。

消费者侧最重要的是手动提交+幂等处理。前面提过，自动提交默认5秒提交一次，时间窗口内的崩溃会造成重复消费或消息丢失，手动提交能精确控制"处理成功才提交"。处理失败的场景，不要直接抛异常让poll循环退出，而是把失败消息打到重试队列或死信队列，保证主线流程可以继续。生产上我见过很多消费堆积故障，本质都是处理逻辑里遇到一条脏数据就抛异常，消费者一直在原地重试。

6.2 消息顺序性的取舍

Kafka只能保证分区内有序，不能保证topic全局有序。这是很多人在设计时容易迷的地方。我的理解是：

• 如果业务要求严格全局有序，最简单的方案是只建一个分区。但单分区意味着完全没有并行度，吞吐受限于单消费者，这个代价要想清楚。
• 大多数业务其实只需要局部有序，比如同一个订单的多个状态变更消息必须有序，不同订单之间无所谓。这种场景给消息设置相同的key=订单号，Kafka会保证同一个key进同一个分区，而分区内天然有序。我在Producer示例里用key做哈希分配，就是这个思路的简化版。

本地Demo验证顺序性最直接的办法：生产者循环发送key-0、key-1、key-2各一批，消费者端打印分区和offset，你会看到同一个key的offset一定是递增的，而不同key之间可能是交叉的。

6.3 监控与可视化工具

最后提一下可观测性。跑Demo可以只用控制台，生产环境必须看着消费进度和堆积量。最简单的是用Kafka自带的命令行工具：

bash复制bin/kafka-consumer-groups.sh --bootstrap-server 127.0.0.1:9092 --describe --group demo-group

这个命令会输出每个分区的当前offset、log-end-offset和lag，lag就是有多少条消息积压没消费。消费堆积是反映下游健康度的及时指标，lag持续上涨通常说明消费者处理能力不够。

可视化工具我也用过几个，简单对比：

日常调试我用Offset Explorer多一点，看分区offset和消费组lag很直观；团队共享监控用Kafka UI更合适，浏览器打开就行。配置方式一般就是填bootstrap地址和认证信息，和Java客户端连的是同一套。

写到这里，这个Demo从"能跑"到"跑稳"的升级路径已经比较完整了。我个人的体会是，Kafka学习曲线最陡的地方不在API，而在理解消息从发送到消费的整个生命周期里，每个参数和机制分别在哪个环节起作用。这个生产者-消费者示例正好提供了一个可以实际操作的最小闭环，把配置参数一个个改一遍、看看现象，比刷十篇八股文都管用。你照着把代码跑通之后，再去碰SpringBoot Kafka、Canal同步、或者Flink消费，会发现它们都是在跟同一套Producer/Consumer机制打交道，只是封装方式不同罢了。