4. Schema Registry与数据契约

在批流一体的数据管道里，生产者与消费者往往由不同团队、不同语言、不同发布节奏维护。如果消息体只是“约定俗成”的 JSON，字段改名、类型变化、字段删除都会在消费端引发静默错误或反序列化失败。Schema Registry 的核心价值，是把“消息长什么样”从口头约定升级为可注册、可版本化、可校验的数据契约：生产者发送前按契约序列化，消费者按契约反序列化，注册中心负责在写入新版本时判断兼容性，从而把破坏性变更挡在进入主题之前。

一、数据契约的三层结构

理解 Schema Registry，需要先分清三个层次。第一层是Schema 本身，即用 Avro、Protobuf 或 JSON Schema 描述的消息结构；第二层是Subject，它是 Schema 在注册中心里的命名空间，通常与“主题名 + 键/值”绑定，例如 orders-value；第三层是Schema ID，注册成功后返回的全局整数编号。生产者实际写入 Kafka 的消息并不是裸数据，而是“魔术字节 + 4 字节 Schema ID + 序列化后的二进制负载”。消费者拿到消息后先读 Schema ID，再向注册中心拉取对应 Schema，最后完成反序列化。这个设计让每条消息都自带“我属于哪个契约版本”的线索，而不必把完整 Schema 塞进每条消息。

二、Avro 与 Protobuf 的取舍

Avro 的 Schema 是 JSON 文本，字段带名称与类型，支持默认值、联合类型和逻辑类型（如 decimal、timestamp-millis）。它非常适合“写时紧凑、读时按 Schema 解释”的场景，且默认值机制让新增字段天然向后兼容。Protobuf 使用 .proto 文件，字段用编号标识，新增字段只要不复用旧编号即可兼容，二进制体积更小、跨语言生态成熟，适合接口稳定、需要强类型代码生成的团队。选择时不必追求“哪个更好”，而应看契约变更频率、是否需要默认值语义、以及团队是否已有代码生成流水线。本节实战以 Avro 为主，因为它把“兼容性规则”体现得最直观。

三、兼容性策略：到底谁怕谁

兼容性描述的是“新旧 Schema 之间能否互相读懂”。常见策略有四种：

• BACKWARD：新 Schema 可以读旧数据。消费者先升级、生产者后升级时使用。允许删除字段、新增带默认值的字段。
• FORWARD：旧 Schema 可以读新数据。生产者先升级时使用。允许新增字段、删除带默认值的字段。
• FULL：双向兼容，最严格，适合消费者与生产者无法协调发布顺序的场景。
• NONE：不做校验，仅用于临时调试，生产环境应避免。

判断方向时记住一句话：兼容性检查发生在“注册新版本”这一刻，检查的是新版本能否被已有版本按策略接受。例如把 amount 从 int 改成 string，无论哪种策略都会失败，因为类型语义已经改变；而把 amount 从 int 提升为 long，Avro 允许类型提升，通常可以通过。

四、实战：从 Avro Schema 到可运行的生产消费

下面以订单事件为例，演示一次完整的契约演进。初始版本 v1 只包含订单号、金额和创建时间：

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example.orders",
  "fields": [
    {"name": "order_id", "type": "string"},
    {"name": "amount",   "type": "long"},
    {"name": "created_at", "type": "long", "logicalType": "timestamp-millis"}
  ]
}

把该 Schema 注册到 Subject orders-value，得到 Schema ID 101。生产者配置 value.serializer=io.confluent.kafka.serializers.KafkaAvroSerializer，并设置 schema.registry.url=http://localhost:8081。发送一条消息后，用 kafka-avro-console-consumer 可以观察到反序列化结果：

{"order_id":"A1001","amount":2599,"created_at":1735689600000}

现在业务需要增加“优惠券编码”，且历史消息没有该字段。正确做法是新增字段并给出默认值：

{"name": "coupon_code", "type": "string", "default": ""}

在 BACKWARD 策略下，这个 v2 可以注册成功，因为旧数据缺少 coupon_code 时，Avro 会用默认值 "" 补齐。消费者即使仍使用 v1 的 Schema，也能读取 v2 数据（忽略新字段），这正是“向后兼容”的实际含义。反之，如果直接删除 amount 字段且没有默认值，注册会被拒绝，错误信息通常会指出“reader 缺少 writer 中的字段”。

五、结果判读与常见排障

验证契约是否生效，可以观察三类信号。第一，注册中心返回的版本号是否递增，且兼容性检查是否通过；第二，消费者反序列化是否报 Unknown magic byte 或 Schema not found，前者通常意味着消息不是由 Schema Registry 序列化器写入，后者说明 Schema ID 在注册中心不存在；第三，字段值是否符合预期，尤其是新增字段是否被默认值正确填充。若出现 SerializationException，优先检查序列化器配置、Subject 命名策略（TopicNameStrategy 还是 RecordNameStrategy）以及 Schema 是否已注册。把这些检查点固化到监控告警中，数据契约才真正成为管道稳定性的护栏。