Kafka 消息协议基础：消息格式演进与 RecordBatch 结构
Kafka 自诞生以来，其内部消息协议经历了三次重大迭代：v0（0.7.x ~ 0.8.x）、v1（0.9.x ~ 0.10.x）和 v2（0.11.0+）。理解这些格式的演进，是进行多版本契约测试的基石。本章将深入剖析各版本消息格式的差异、RecordBatch 的诞生背景及其内部结构，以及消息头与元数据的设计。
2.1 消息格式演进：从 v0 到 v2
Kafka 消息格式的每一次升级，都伴随着性能、压缩率或功能性的显著提升。下表总结了三个版本的核心差异：
| 特性 | v0 (0.7.x ~ 0.8.x) | v1 (0.9.x ~ 0.10.x) | v2 (0.11.0+) |
|---|---|---|---|
| 消息结构 | 单条消息独立序列化 | 单条消息独立序列化 | 引入 RecordBatch，多条消息批量序列化 |
| CRC 校验 | 每条消息独立 CRC | 每条消息独立 CRC | Batch 级别 CRC，减少计算开销 |
| 时间戳 | 无时间戳字段 | 新增 timestamp 字段（可选） |
强制时间戳，支持 CreateTime 和 LogAppendTime |
| 压缩方式 | 单条消息压缩 | 单条消息压缩 | Batch 级别压缩，压缩率更高 |
| 消息头 | 无 | 无 | 支持自定义消息头（Headers） |
| 可变长度 | 固定长度字段 | 固定长度字段 | 使用 Varint 和 ZigZag 编码，减少空间占用 |
| ID 字段 | 无 | 无 | 每个 Record 包含递增的 sequence ID |
契约测试要点： 在适配多版本协议时，v2 格式的 RecordBatch 结构是核心。契约测试需要验证 Producer 和 Consumer 在 v0/v1/v2 格式下的序列化/反序列化是否一致，特别是 CRC 校验范围、时间戳语义和消息头字段的兼容性。
2.2 消息批次（RecordBatch）结构
v2 格式最大的变革是引入了 RecordBatch。它将多条消息打包成一个批次进行存储和传输，显著提升了磁盘利用率和网络吞吐量。一个 RecordBatch 由 Batch Header 和若干 Record 组成。
关键概念： 在 v2 协议中，Producer 发送的
ProducerBatch 与 Broker 存储的 RecordBatch 结构基本一致。契约测试应关注 Batch 级别的 CRC 校验是否覆盖了整个 Batch 内容，以及单个 Record 的偏移量计算方式。
2.2.1 Batch Header 结构
Batch Header 包含了整个批次的元数据信息，其字段如下：
| 字段 | 长度 | 说明 |
|---|---|---|
| first_offset | 8 bytes | 批次中第一条消息的偏移量 |
| length | 4 bytes | 整个 Batch 的总字节数（包括 Header） |
| partition_leader_epoch | 4 bytes | 分区 Leader 的 epoch，用于日志截断 |
| magic | 1 byte | 协议版本号，v2 固定为 2 |
| crc | 4 bytes | 从 attributes 到 records 的 CRC32C 校验 |
| attributes | 2 bytes | 压缩类型、时间戳类型等标志位 |
| last_offset_delta | 4 bytes | 最后一条消息相对于 first_offset 的增量 |
| first_timestamp | 8 bytes | 批次中第一条消息的时间戳 |
| max_timestamp | 8 bytes | 批次中最后一条消息的时间戳 |
| producer_id | 8 bytes | 幂等/事务 Producer 的唯一 ID |
| producer_epoch | 2 bytes | Producer 的 epoch，用于去重 |
| base_sequence | 4 bytes | 批次中第一条消息的序列号 |
| records_count | 4 bytes | 批次中包含的 Record 数量 |
2.2.2 Record 结构
Batch 中的每个 Record 采用可变长度编码，结构如下：
| 字段 | 编码方式 | 说明 |
|---|---|---|
| length | Varint | Record 体总长度 |
| attributes | 1 byte | 当前 Record 的属性（保留位） |
| timestamp_delta | Varint | 相对于 Batch first_timestamp 的增量 |
| offset_delta | Varint | 相对于 Batch first_offset 的增量 |
| key | Varint + bytes | 消息键（可为 null） |
| value | Varint + bytes | 消息体（可为 null） |
| headers | Varint + array | 消息头数组（v2 新增） |
兼容性陷阱： 在契约测试中，务必注意 v2 的 Record 使用
timestamp_delta 和 offset_delta 代替了绝对时间戳和偏移量。如果测试工具或客户端库未正确处理这些增量字段，会导致反序列化后的时间戳或偏移量错误。
2.3 消息头与元数据
v2 格式引入了 消息头（Headers），允许用户为每条消息附加自定义的键值对元数据。消息头在 Record 内部以数组形式存储，每个 Header 的结构如下：
| 字段 | 编码方式 | 说明 |
|---|---|---|
| header_key | Varint + string | Header 的键（UTF-8 字符串） |
| header_value | Varint + bytes | Header 的值（可为 null） |
消息头的引入为契约测试带来了新的挑战：
- 序列化一致性： 不同语言的客户端库对 Header 的序列化顺序和空值处理可能存在差异。
- 兼容性： v0/v1 客户端无法解析 v2 的消息头，在混合版本集群中需要做降级处理。
- 契约验证： 测试用例需要覆盖 Header 的增删改查，确保 Producer 写入的 Header 能被 Consumer 完整、正确地读取。
2.4 消息格式演进与 RecordBatch 结构图
下图展示了从 v0 单条消息到 v2 RecordBatch 的结构演进，以及 Batch 内部 Record 的详细布局：
2.5 契约测试中的协议适配策略
基于上述格式差异，在契约测试中需要针对不同版本制定适配策略：
- 版本探测： 通过
magic字段识别消息版本，v0=0, v1=1, v2=2。 - 序列化/反序列化适配： 为每个版本编写独立的序列化器，确保 CRC 计算范围、时间戳处理、压缩逻辑与对应版本一致。
- RecordBatch 解析： 对于 v2 消息，先解析 Batch Header，再根据
records_count循环解析每个 Record，注意 Varint 解码。 - 消息头兼容性： 在混合版本场景下，v2 消息头应被降级忽略或转换为 v0/v1 可识别的元数据（如放入 value 前缀）。
- 幂等与事务支持： v2 的
producer_id、producer_epoch和base_sequence是幂等/事务的基础，契约测试需验证这些字段在重试和乱序场景下的正确性。
实践建议： 在编写契约测试用例时，建议使用 Kafka 官方提供的
MemoryRecords 和 RecordBatch API 来构造和解析消息，避免手动处理二进制协议。同时，利用 kafka-protobuf-serializer 或 kafka-avro-serializer 等工具，可以简化多版本消息的序列化契约验证。