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

Kafka 的三大核心 API——Producer、Consumer 与 AdminClient——分别对应数据写入、数据读取与集群管理。理解它们的设计哲学，是诊断堆积问题、进行性能调优的前提。本章从 API 的抽象层次、异步/同步模型、分区策略与偏移量管理四个维度，拆解每个 API 的核心机制与适用场景。

2.1 Producer API：异步批量的写入哲学

Producer API 的设计核心是 高吞吐异步批量。它不追求单条消息的即时确认，而是通过缓冲区、批量发送与压缩来最大化网络与磁盘利用率。

2.1.1 三种确认模式 (acks)

2.2 Consumer API：拉模式与偏移量管理

Consumer API 采用 拉模式 (Pull)，由消费者主动向 Broker 请求数据。这种设计让消费者可以自主控制消费速率，避免推送模式下的背压问题。但拉模式也带来了偏移量管理、再均衡与消费滞后监控等挑战。

2.2.1 消费组与分区分配策略

2.2.2 手动提交 vs 自动提交

2.3 AdminClient API：集群管理的统一入口

AdminClient 是 Kafka 0.11.0 引入的集群管理 API，替代了旧版 TopicCommand、ConsumerGroupCommand 等命令行工具。它提供编程方式管理主题、分区、配置、消费者组与 ACL。

2.3.1 核心操作与使用场景

2.3.2 堆积诊断中的 AdminClient 应用

在堆积诊断场景中，AdminClient 是获取集群状态的核心工具。以下代码片段展示如何通过 AdminClient 获取消费者组滞后信息：

Properties props = new Properties();
props.put(AdminClientConfig.BOOTSTRAP_SERVERS_CONFIG, "broker1:9092,broker2:9092");
props.put(AdminClientConfig.REQUEST_TIMEOUT_MS_CONFIG, 30000);

try (AdminClient admin = AdminClient.create(props)) {
    // 列出所有消费者组
    ListConsumerGroupsResult groupsResult = admin.listConsumerGroups();
    Collection<ConsumerGroupListing> groups = groupsResult.all().get();
    
    for (ConsumerGroupListing group : groups) {
        // 获取组内各分区的偏移量
        ListConsumerGroupOffsetsResult offsetsResult = 
            admin.listConsumerGroupOffsets(group.groupId());
        Map<TopicPartition, OffsetAndMetadata> offsets = 
            offsetsResult.partitionsToOffsetAndMetadata().get();
        
        // 获取每个分区的最新偏移量（日志末尾）
        Set<TopicPartition> partitions = offsets.keySet();
        ListOffsetsResult endOffsets = admin.listOffsets(
            partitions.stream()
                .collect(Collectors.toMap(
                    tp -> tp, 
                    tp -> OffsetSpec.latest()
                ))
        );
        
        // 计算滞后
        for (TopicPartition tp : partitions) {
            long consumerOffset = offsets.get(tp).offset();
            long endOffset = endOffsets.partitionResult(tp).get().offset();
            long lag = endOffset - consumerOffset;
            System.out.printf("Group: %s, Partition: %s, Lag: %d%n", 
                group.groupId(), tp, lag);
        }
    }
}

2.4 三大 API 的设计哲学对比