2. Kafka 核心 API 设计：Producer API、Consumer API、AdminClient API 的设计哲学与使用模式

Kafka 的三大核心客户端 API——Producer、Consumer 与 AdminClient——各自承载着不同的设计哲学。理解它们的底层抽象与使用模式，是诊断堆积问题、优化吞吐与延迟的前提。本章从 API 设计意图出发，剖析每个客户端的核心抽象、关键参数与典型使用模式。

2.1 Producer API：异步、批量与幂等性

Producer API 的设计哲学围绕 高吞吐异步发送 与 精确一次语义 展开。其核心抽象是 KafkaProducer<K, V>，通过 send() 方法将 ProducerRecord 放入内部缓冲区，由后台 I/O 线程批量发送。

2.1.1 幂等性与事务

启用 enable.idempotence=true 后，Producer 自动为每个批次分配序列号（PID + 序列号），Broker 端去重，确保分区内精确一次。事务 API 则通过 initTransactions()、beginTransaction()、commitTransaction() 实现跨分区原子写入。

// 幂等 Producer 配置示例
Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer");
props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer");
props.put("acks", "all");
props.put("enable.idempotence", true);   // 开启幂等
props.put("max.in.flight.requests.per.connection", 5);

KafkaProducer<String, String> producer = new KafkaProducer<>(props);
producer.send(new ProducerRecord<>("topic-a", "key1", "value1"),
    (metadata, exception) -> {
        if (exception != null) {
            // 重试或记录失败
        }
    });
producer.close();

2.2 Consumer API：分区再平衡与消费语义

Consumer API 的设计核心是 分区再平衡 与 消费位移管理。Kafka 通过 KafkaConsumer<K, V> 配合 subscribe() 实现组管理，或通过 assign() 手动指定分区。

2.2.1 手动位移提交与暂停/恢复

在堆积场景下，推荐使用 手动同步提交 结合 pause()/resume() 控制消费速率。当消费者处理能力不足时，暂停分区拉取，避免内存溢出。

// 手动提交 + 暂停恢复示例
consumer.subscribe(Arrays.asList("topic-b"));
while (true) {
    ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(1000));
    if (records.count() > 1000) {
        // 堆积预警：暂停所有分区，降低拉取速率
        consumer.pause(consumer.assignment());
    }
    for (ConsumerRecord<String, String> record : records) {
        processRecord(record);  // 业务处理
    }
    consumer.commitSync();      // 同步提交，确保位移不丢失
    if (!consumer.paused().isEmpty()) {
        consumer.resume(consumer.paused()); // 恢复拉取
    }
}

2.3 AdminClient API：集群元数据管理

AdminClient 是 Kafka 0.11.0 引入的管理客户端，用于替代旧版 kafka.admin.AdminClient 和命令行工具。其设计哲学是 异步非阻塞 + 幂等操作，所有返回结果均为 Future 或 KafkaFuture。

2.3.1 使用模式：Lag 诊断

通过 listConsumerGroupOffsets() 获取当前消费位移，结合 describeTopics() 获取分区最新偏移，即可计算每个分区的堆积 Lag。这是诊断堆积问题的核心数据源。

// 使用 AdminClient 查询消费组 Lag
try (AdminClient admin = AdminClient.create(props)) {
    // 获取消费组位移
    ListConsumerGroupOffsetsResult offsetsResult =
        admin.listConsumerGroupOffsets("my-consumer-group");
    Map<TopicPartition, OffsetAndMetadata> offsets =
        offsetsResult.partitionsToOffsetAndMetadata().get(10, TimeUnit.SECONDS);

    // 获取分区最新偏移
    Set<TopicPartition> partitions = offsets.keySet();
    Map<TopicPartition, OffsetSpec> requestLatest = partitions.stream()
        .collect(Collectors.toMap(tp -> tp, tp -> OffsetSpec.latest()));
    Map<TopicPartition, ListOffsetsResultInfo> latestOffsets =
        admin.listOffsets(requestLatest).all().get(10, TimeUnit.SECONDS);

    // 计算 Lag
    for (TopicPartition tp : partitions) {
        long committed = offsets.get(tp).offset();
        long latest = latestOffsets.get(tp).offset();
        long lag = latest - committed;
        System.out.printf("Partition %s: Lag = %d%n", tp, lag);
    }
}

2.4 三大 API 设计哲学对比