3. OpenAPI 接口全景：诊断 API 分类

在 Kafka 堆积诊断场景中，OpenAPI 接口是连接运维人员与集群内部状态的桥梁。根据诊断目标的不同，这些接口可划分为四大核心类别：堆积查询、消费组状态、分区元数据与延迟监控。每一类接口对应不同的数据源与响应特征，理解其分类是进行性能验证的前提。

3.1 诊断 API 分类总览

下表从接口职责、核心指标、典型端点与性能敏感度四个维度，对四类 API 进行横向对比：

3.2 接口调用关系与数据流

四类 API 并非孤立存在，它们在一次完整的堆积诊断流程中形成上下游依赖关系。下图展示了从触发告警到定位根因的接口调用链路：

3.3 各分类接口详解

3.3.1 堆积查询 API

堆积查询 API 是诊断流程的第一入口。其核心逻辑是：获取消费组在每个分区上的 current_offset（当前消费偏移）与 log_end_offset（日志末端偏移），计算差值得到 lag。

• 响应体结构示例：

{
  "group": "clickstream-consumer",
  "lag_summary": {
    "total_lag": 152340,
    "max_lag": 45000,
    "max_lag_partition": "clickstream-7"
  },
  "partitions": [
    {
      "partition": 0,
      "current_offset": 120000,
      "log_end_offset": 125000,
      "lag": 5000
    }
  ]
}

• 性能瓶颈点：当 Topic 分区数超过 1000 或消费组数量超过 500 时，单次全量扫描可能耗时超过 5 秒，需引入 分区级并行查询 或 缓存策略。

3.3.2 消费组状态 API

该接口返回消费组的运行时状态，包括 Stable、Rebalancing、Empty、Dead 等。在堆积诊断中，Rebalancing 状态常导致消费暂停，引发瞬时堆积。

• 关键字段：

3.3.3 分区元数据 API

分区元数据 API 提供 Topic 分区的物理分布信息。在堆积诊断中，主要用于判断是否存在 Leader 倾斜或 ISR 收缩导致的写入瓶颈。

• 典型响应片段：

{
  "topic": "clickstream",
  "partitions": [
    {
      "partition_id": 0,
      "leader": 2,
      "replicas": [2, 3, 1],
      "isr": [2, 3],
      "log_end_offset": 125000
    }
  ]
}

• 诊断价值：当 isr 数量小于 replicas 时，表明副本同步延迟，可能影响生产端写入速度，间接导致堆积。

3.3.4 延迟监控 API

延迟监控 API 测量消息从生产到被消费的端到端延迟。该接口通常需要 Broker 端开启 message.timestamp.type=LogAppendTime，并在消费端记录消费时间戳。

• 计算方式：

end_to_end_latency_ms = consumer_timestamp - producer_timestamp

• 性能特征：该接口需要扫描最近 N 条消息的时间戳，对 Broker 的 Page Cache 和磁盘 I/O 有一定压力。建议设置 采样率（如每 100 条采样 1 条）以降低开销。

3.4 接口调用优先级策略

在实际运维中，面对堆积告警，建议按以下优先级调用 API：

1. 第一步：调用 堆积查询 API，确认堆积总量与最大堆积分区。
2. 第二步：调用 消费组状态 API，检查消费组是否处于 Rebalancing 或 Dead 状态。
3. 第三步：调用 分区元数据 API，分析堆积分区的 Leader 分布与 ISR 健康度。
4. 第四步：调用 延迟监控 API，评估端到端延迟是否超出业务容忍阈值。

3.5 分类总结矩阵

以下矩阵从数据源、调用频率与优化方向三个维度，为后续性能验证提供依据：