3. 消息契约的定义：消息格式、字段约束与兼容性规则

消息契约是契约测试的基石。在 Kafka 场景中，契约不仅描述消息的二进制结构，还定义了字段的语义约束、可选性、默认值以及版本演化时的兼容性规则。本章将围绕三种主流序列化格式——Avro、JSON Schema 和 Protobuf——展开，对比它们在字段约束与兼容性规则上的设计差异。

3.1 三种消息格式的核心特征

特性 Avro JSON Schema Protobuf
序列化方式 二进制（紧凑，无自描述） 文本（JSON 字符串） 二进制（紧凑，带字段编号）
Schema 注册 Schema Registry 原生支持 需额外工具或自定义注册 需额外工具或自定义注册
字段标识 按字段名匹配 按字段名匹配 按字段编号（field number）匹配
默认值支持 支持（在 schema 中声明） 支持（通过 default 关键字） 支持（在 proto 文件中声明）
向后兼容 强（内置兼容性检查） 中等（依赖工具链） 强（字段编号不可变）
向前兼容 强（支持字段删除/添加默认值） 中等（需谨慎处理 required 字段） 强（新增字段需 optional 或默认值）
选型建议： 如果团队已使用 Confluent Schema Registry，Avro 是最自然的选择；若团队前端/后端均使用 TypeScript，JSON Schema 可减少技术栈切换成本；Protobuf 适合对序列化性能要求极高、且字段编号管理严格的微服务架构。

3.2 字段约束：从类型到语义

字段约束是契约测试中“校验”的直接对象。一个完整的消息契约应覆盖以下四个层次的约束：

  1. 类型约束：字段的数据类型（string、int、record、enum 等）。
  2. 值域约束：字段的取值范围（最小值、最大值、枚举值列表）。
  3. 可选性约束：字段是 required 还是 optional，以及是否提供默认值。
  4. 语义约束：字段的业务含义（如“订单状态”只能取特定枚举值，“金额”必须为正数）。

以下是一个 Avro 契约示例，展示了上述约束的声明方式：

{
  "type": "record",
  "name": "OrderCreated",
  "namespace": "com.example.ecommerce",
  "fields": [
    { "name": "orderId",   "type": "string",   "doc": "全局唯一订单ID" },
    { "name": "userId",    "type": "string",   "doc": "用户ID" },
    { "name": "amount",    "type": "double",   "doc": "订单金额，单位元" },
    { "name": "status",    "type": { "type": "enum", "name": "OrderStatus",
                                     "symbols": ["PENDING", "PAID", "SHIPPED", "CANCELLED"] },
                           "doc": "订单状态" },
    { "name": "items",     "type": { "type": "array", "items": "string" },
                           "default": [], "doc": "商品ID列表" },
    { "name": "discount",  "type": ["null", "double"], "default": null,
                           "doc": "折扣金额，可为空" }
  ]
}
契约测试关注点： 测试用例应覆盖“字段缺失”“字段类型错误”“枚举值越界”“默认值生效”等场景。例如，发送一个缺少 orderId 的消息，验证消费者是否按契约拒绝该消息。

3.3 兼容性规则：版本演化的安全网

消息契约不是一成不变的。随着业务迭代，生产者可能新增字段、删除字段或修改字段类型。兼容性规则定义了“新版本 Schema 能否安全替换旧版本 Schema”的判断标准。以下是三种常见的兼容性类型：

兼容性类型 定义 典型场景 Avro 支持 JSON Schema 支持 Protobuf 支持
BACKWARD 新 Schema 可以读取旧 Schema 写入的数据 消费者升级，生产者未升级 ✅ 原生 ⚠️ 需手动校验 ✅ 原生
FORWARD 旧 Schema 可以读取新 Schema 写入的数据 生产者升级，消费者未升级 ✅ 原生 ⚠️ 需手动校验 ✅ 原生
FULL 同时满足 BACKWARD 和 FORWARD 生产者和消费者独立升级 ✅ 原生 ⚠️ 需手动校验 ✅ 原生
常见陷阱： 在 Avro 中，删除一个没有默认值的字段会破坏 BACKWARD 兼容性；在 Protobuf 中，重复使用已删除的字段编号会导致数据解析错乱。契约测试应包含“兼容性规则检查”用例，确保 Schema 变更不会破坏已有消费者。

3.4 兼容性规则对比：Avro vs Protobuf vs JSON Schema

下面这张 SVG 图展示了三种格式在字段演化时的兼容性决策路径，帮助你在设计契约时快速判断哪些变更安全、哪些需要版本号升级。

消息格式兼容性决策路径 字段变更 新增字段 删除字段 修改字段类型 有默认值 / optional → 兼容（BACKWARD/FORWARD） 无默认值 / required → 破坏 BACKWARD 兼容 Avro/Protobuf： 保留字段编号，标记为 reserved 直接删除字段 → 破坏 FORWARD 兼容 扩大类型（int→long） → 可能兼容（需测试） 缩小类型（long→int） → 破坏 BACKWARD 兼容 契约测试中的兼容性验证策略 1. 每次 Schema 变更后，使用 Schema Registry 的兼容性 API 进行自动检查。 2. 编写契约测试用例，用旧版本 Schema 序列化消息，用新版本 Schema 反序列化（BACKWARD）。 3. 用新版本 Schema 序列化消息，用旧版本 Schema 反序列化（FORWARD）。 4. 只有两种方向都通过，才能声明 FULL 兼容。

3.5 契约定义的最佳实践

  • 始终声明默认值：新增字段时，为旧消费者提供默认值，避免破坏 FORWARD 兼容性。
  • 使用枚举而非字符串：枚举在 Avro 和 Protobuf 中具有强类型约束，契约测试可直接校验枚举值是否在允许集合内。
  • 字段编号管理（Protobuf）：为每个字段分配唯一编号，删除时标记为 reserved，避免未来误用。
  • Schema 版本化：在消息头或 Kafka 消息 key 中携带 Schema 版本号，便于消费者动态选择反序列化器。
  • 契约即文档：在契约中添加 doc 或 description 字段，描述每个字段的业务含义，降低沟通成本。
← 上一章 📖 返回目录 下一章 →