4. API设计总纲：RESTful vs gRPC vs GraphQL选型、Kafka原生AdminClient API概览、自定义诊断API的定位

诊断系统的API层是连接运维人员、自动化工具与Kafka集群的桥梁。选型错误会导致诊断命令延迟高、数据过载或维护成本激增。本节从协议对比、原生能力、自定义定位三个维度，建立诊断API的设计坐标系。

4.1 协议选型：RESTful / gRPC / GraphQL 对比

三种主流API协议在诊断场景下的核心差异如下表所示：

下图展示了三种协议在诊断系统中的典型调用链路：

4.2 Kafka原生AdminClient API概览

Kafka 原生 AdminClient 是诊断系统获取集群元数据、配置、状态的核心工具。以下列出与堆积诊断直接相关的关键API：

以下代码片段展示了使用AdminClient获取消费组偏移量的标准模式：

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

try (AdminClient admin = AdminClient.create(props)) {
    // 异步获取所有消费组
    ListConsumerGroupsResult groupsResult = admin.listConsumerGroups();
    Collection<ConsumerGroupListing> groups = groupsResult.all().get(10, TimeUnit.SECONDS);

    for (ConsumerGroupListing group : groups) {
        // 获取该组各分区的消费位移
        ListConsumerGroupOffsetsSpec spec = new ListConsumerGroupOffsetsSpec()
                .groupid(group.groupId());
        Map<TopicPartition, OffsetAndMetadata> offsets = admin
                .listConsumerGroupOffsets(Map.of(group.groupId(), spec))
                .all()
                .get(10, TimeUnit.SECONDS);

        // 此处可结合 describeTopics 获取 LOG_END_OFFSET 计算堆积
        offsets.forEach((tp, offsetMeta) -> {
            System.out.printf("Group: %s, Partition: %s, Offset: %d%n",
                    group.groupId(), tp, offsetMeta.offset());
        });
    }
} catch (InterruptedException | ExecutionException | TimeoutException e) {
    // 诊断系统应记录异常并降级，而非抛出
    logger.error("AdminClient call failed", e);
}

4.3 自定义诊断API的定位

原生AdminClient提供的是“原始数据”，而诊断系统需要的是“诊断结论”。自定义诊断API的定位是在原生API之上构建一层语义化、聚合化的接口，解决以下三个核心问题：

• 数据聚合：将多次AdminClient调用（如offsets + topics + groups）合并为一次诊断结果，减少客户端网络开销。
• 状态推导：将原始数值转化为诊断状态（如“堆积严重”、“分区倾斜”、“消费者停滞”），而非暴露裸指标。
• 策略封装：内置重试、超时、降级、缓存策略，避免调用方重复实现容错逻辑。

下图展示了自定义诊断API在整体架构中的定位与数据流：

4.4 自定义诊断API接口设计示例

以下是一个面向堆积诊断的RESTful接口设计示例，展示如何将原生API封装为语义化接口：