2. OpenAPI 接口基础：RESTful 设计原则与 Kafka 端点

在 Kafka 堆积诊断场景中，OpenAPI（即 Kafka REST Proxy 暴露的 HTTP 接口）是连接监控系统、运维脚本与 Kafka 集群的核心桥梁。理解其 RESTful 设计原则、端点语义及请求/响应结构，是进行接口调用性能调优的前提。

2.1 RESTful API 设计原则在 Kafka OpenAPI 中的体现

Kafka REST Proxy 遵循典型的 RESTful 架构风格，其核心原则映射如下：

2.2 Kafka OpenAPI 常见端点

以下是与堆积诊断最相关的三个核心端点组，每个端点对应不同的资源操作粒度。

2.2.1 /consumers 端点组

用于管理 Consumer Group 实例和消费操作。在堆积诊断中，主要用于获取消费组状态和触发消费位置查询。

# 创建消费者实例（POST）
POST /consumers/{groupName}
Content-Type: application/vnd.kafka.v2+json

{
  "name": "diagnostic_consumer_1",
  "format": "json",
  "auto.offset.reset": "earliest"
}

# 获取消费者组列表（GET）
GET /consumers

2.2.2 /topics 端点组

提供 Topic 元数据、分区信息和消息数据访问。是计算堆积量的数据源入口。

# 获取 Topic 列表（GET）
GET /topics

# 获取指定 Topic 的分区详情（GET）
GET /topics/{topicName}/partitions

# 获取指定分区的最新偏移量（GET）
GET /topics/{topicName}/partitions/{partitionId}/offsets

2.2.3 /offsets 端点组

直接暴露偏移量查询能力，是堆积诊断的核心端点。通过对比生产端最新偏移和消费端已提交偏移，即可计算堆积量。

# 获取消费组在指定 Topic 上的已提交偏移（GET）
GET /consumers/{groupName}/instances/{instanceId}/offsets

# 获取消费组在所有 Topic 上的偏移摘要（GET）
GET /consumers/{groupName}/offsets

2.3 请求/响应结构详解

Kafka OpenAPI 使用 JSON 作为主要数据交换格式，并遵循 Content-Type 协商机制。理解请求头和响应体的结构，有助于在调优时精准提取所需字段，减少不必要的解析开销。

2.3.1 通用请求结构

所有请求均需包含以下关键部分：

• 请求行：HTTP 方法 + 资源路径 + HTTP 版本
• 请求头：必须包含 Content-Type（如 application/vnd.kafka.v2+json），可选 Accept 头
• 请求体（仅 POST/PUT）：JSON 格式，包含操作参数

// 请求示例：向 Topic 发送消息
POST /topics/order_events HTTP/1.1
Content-Type: application/vnd.kafka.v2+json

{
  "records": [
    {"key": "order_123", "value": {"status": "created", "timestamp": 1710000000}}
  ]
}

2.3.2 通用响应结构

响应体通常包含以下字段：

// 响应示例：查询消费组偏移
HTTP/1.1 200 OK
Content-Type: application/vnd.kafka.v2+json

{
  "error_code": 0,
  "offsets": [
    {"partition": 0, "offset": 1500, "metadata": "", "error_code": 0},
    {"partition": 1, "offset": 2300, "metadata": "", "error_code": 0}
  ]
}

2.4 端点调用性能基线

在堆积诊断场景中，不同端点的响应延迟差异显著。以下为基于典型集群（3 Broker、100 个 Topic、每个 Topic 8 分区）的参考基线：