3. 多版本协议兼容性原理：Kafka Broker与Client版本协商机制、ApiVersions请求/响应、特性标志（Feature Flags）

Kafka 从 0.9.x 开始引入正式的二进制协议，并在后续版本中不断扩展消息格式、分组协调、事务、幂等、KIP-482 等特性。不同版本的 Broker 与 Client 必须通过一套标准的版本协商机制来确保互通，避免因协议不匹配导致连接失败或数据损坏。本节深入剖析版本协商的核心流程、ApiVersions 请求/响应的结构，以及特性标志（Feature Flags）如何实现细粒度特性开关。

3.1 版本协商的必要性与基本原则

Kafka 协议采用 请求-响应 模型，每个 API 都有独立的版本号。Broker 和 Client 各自支持一组 API 版本集合。版本协商的目标是：

• 向后兼容：新版本 Broker 必须能处理旧版本 Client 的请求。
• 向前兼容：旧版本 Broker 应能拒绝或降级处理新版本 Client 的请求。
• 最优版本选择：双方选择彼此都支持的最高版本，以启用最新特性。

3.2 ApiVersions 请求/响应机制

ApiVersions 是 Kafka 协议中版本号固定为 0 的特殊 API（其自身版本也通过该机制协商）。Client 在建立 TCP 连接后，发送的第一条请求通常是 ApiVersionsRequest。Broker 返回 ApiVersionsResponse，包含所有支持的 API 及其版本范围。

3.2.1 请求与响应结构

3.2.2 协商流程

1. Client 发起连接：向 Broker 发送 ApiVersionsRequest（版本 0）。
2. Broker 响应：返回 ApiVersionsResponse，包含所有 API 的版本范围。
3. Client 选择版本：对每个 API，Client 取 min(ClientMaxVersion, BrokerMaxVersion) 且 max(ClientMinVersion, BrokerMinVersion)，若交集为空则降级或报错。
4. 后续请求：Client 使用协商后的版本号发送其他 API 请求。

3.3 特性标志（Feature Flags）

KIP-584 引入了特性标志机制，允许 Broker 在 ApiVersionsResponse 中声明其支持的特性及版本。Client 据此决定是否启用某些高级功能，而无需依赖 API 版本号推断。

3.3.1 特性标志的结构

3.3.2 特性标志 vs API 版本

3.4 版本协商与特性标志的交互流程

下图展示了 Client 与 Broker 之间完整的版本协商与特性标志交互流程：

3.5 版本降级与错误处理

当 Client 与 Broker 的版本交集为空时，Broker 会返回 UNSUPPORTED_VERSION 错误码。Client 应捕获该错误并采取降级策略：

• 降级到更低版本：Client 尝试使用更低的 API 版本重新发送请求。
• 禁用特性：如果某个特性标志不匹配，Client 应禁用该特性并继续运行。
• 断开连接：如果无法降级，Client 应记录错误并断开连接，避免发送无效请求。

3.6 特性标志的最终化（Finalization）

KIP-584 还引入了特性标志的最终化机制。Broker 可以标记某些特性版本为“最终化”，表示该版本已稳定且不再变更。Client 可以据此决定是否信任该特性。最终化信息通过 FinalizedFeaturesEpoch 字段传递，每次特性版本变更时递增。

3.7 契约测试中的版本协商验证

在契约测试中，版本协商是验证 Client 协议兼容性的核心环节。测试框架应模拟 Broker 返回不同的 ApiVersionsResponse，并断言 Client 的行为符合预期：

// 契约测试示例：验证 Client 在 Broker 不支持事务时的降级行为
@Test
public void testClientDegradesWhenBrokerLacksTransactionFeature() {
    // 模拟 Broker 返回 ApiVersionsResponse，不包含 transaction 特性
    ApiVersionsResponse response = ApiVersionsResponse.builder()
        .apiKeys(Arrays.asList(
            new ApiVersion(ProduceApi.ID, (short)0, (short)8),
            new ApiVersion(FetchApi.ID, (short)0, (short)11)
        ))
        .supportedFeatures(Collections.emptyMap()) // 无特性标志
        .build();
    
    // 注入模拟响应
    mockBroker.enqueueResponse(response);
    
    // 启动 Client
    KafkaClient client = new KafkaClient(bootstrapServers);
    client.connect();
    
    // 验证 Client 未启用事务特性
    assertFalse(client.isTransactionEnabled());
    // 验证 Client 使用 Produce API v8（协商后的最高版本）
    assertEquals(8, client.getProduceApiVersion());
}

3.8 小结

Kafka 的多版本协议兼容性依赖于 ApiVersions 请求/响应机制和特性标志的协同工作。Client 在连接建立阶段通过一次协商确定所有 API 的版本和特性支持情况，后续请求均使用协商后的版本。特性标志提供了比 API 版本更细粒度的控制，支持滚动升级和灰度发布。在契约测试中，必须覆盖版本协商的完整流程，包括正常协商、降级、错误处理等场景，以确保 Client 在不同 Broker 版本下的行为符合预期。