📚 课程目录第4章 Schema Registry 实战

4、Schema Registry 实战：Avro/Protobuf Schema 定义、兼容性检查、Schema 演化策略

好，咱们进入 Schema Registry 的实战环节。说实话，很多团队把 Schema Registry 当成一个「存 Schema 的仓库」，这其实有点浪费。它真正的价值在于——让生产者和消费者在数据格式上达成契约，并且自动执行这个契约。

我个人习惯把 Schema Registry 比作「数据格式的交警」。没有它，大家各开各的车，早晚要撞。有了它，谁该停、谁该让，清清楚楚。

4.1 为什么需要 Schema Registry？

先看一个真实场景。你写了一个 Kafka Producer，往 Topic 里发 Avro 数据。消费者那边反序列化时，发现字段名变了、类型改了，直接报错。更糟的是——数据已经落盘了，想回退都难。

我在项目中遇到过类似的事。有一次，业务方为了加一个字段，直接改了 Avro Schema 里的字段类型，从 int 改成了 long。结果下游十几个消费者全部挂掉，整整排查了三个小时。从那以后，我强制要求所有 Schema 变更必须经过 Registry 校验。

  核心价值一句话： Schema Registry 保证「写的时候是什么格式，读的时候还是什么格式」。

4.2 Avro Schema 定义实战

Avro 是我用得最多的序列化格式。它的 Schema 用 JSON 写，可读性好，而且支持丰富的类型。

来看一个用户订单的 Schema 定义：

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example.orders",
  "fields": [
    {"name": "order_id", "type": "string"},
    {"name": "user_id", "type": "int"},
    {"name": "amount", "type": "double"},
    {"name": "status", "type": "string", "default": "PENDING"},
    {"name": "items", "type": {
      "type": "array",
      "items": {
        "type": "record",
        "name": "OrderItem",
        "fields": [
          {"name": "product_id", "type": "string"},
          {"name": "quantity", "type": "int"},
          {"name": "price", "type": "double"}
        ]
      }
    }}
  ]
}

这里有几个要点：

namespace：避免命名冲突，我习惯用包路径风格
default：给字段设置默认值，这是兼容性的关键
嵌套类型：Avro 支持 record 嵌套，但别太深，三层以内就好

小技巧： 定义 Schema 时，尽量给每个字段都加上 default。哪怕你觉得「这个字段不可能为空」，也设一个。为什么？因为未来你可能会删掉它，或者消费者还没升级——default 就是你的安。

4.3 Protobuf Schema 定义实战

Protobuf 是另一种主流选择。它的 Schema 用 .proto 文件写，语法更紧凑，而且生成的代码体积更小。

同样的订单模型，用 Protobuf 定义：

syntax = "proto3";

package com.example.orders;

message Order {
  string order_id = 1;
  int32 user_id = 2;
  double amount = 3;
  string status = 4;
  repeated OrderItem items = 5;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  double price = 3;
}

注意 Protobuf 的字段编号（=1, =2, =3...）。这个编号一旦确定，永远不要改。我见过有人为了「整理编号顺序」重新排了一遍，结果线上数据全乱了。

对比维度	Avro	Protobuf
Schema 格式	JSON	.proto 文件
序列化性能	中等	较快
Schema 演化	原生支持，灵活	需要手动管理编号
生态集成	Kafka 生态首选	gRPC、微服务常用
代码生成	需要额外工具	protoc 原生支持

怎么选？我个人习惯：如果团队主要用 Kafka，选 Avro；如果主要用 gRPC 或微服务，选 Protobuf。没必要在同一个项目里混用。

4.4 兼容性检查：三种模式

Schema Registry 最核心的功能就是兼容性检查。它有三种模式，我一个个说。

4.4.1 BACKWARD（向后兼容）

这是最常用的模式。意思是：用新 Schema 写的数据，老 Schema 的消费者也能读。说白了，你不能删字段，只能加字段，而且加的字段必须有 default。

举个例子：

// 旧 Schema
{"name": "age", "type": "int"}

// 新 Schema（兼容）
{"name": "age", "type": "int"},
{"name": "email", "type": "string", "default": ""}

4.4.2 FORWARD（向前兼容）

这个正好反过来：用老 Schema 写的数据，新 Schema 的消费者也能读。这意味着你可以删字段，但不能加必填字段。

我一般在做数据清理时用这个模式。比如某个字段已经废弃了，但历史数据还在，消费者升级后不能报错。

4.4.3 FULL（完全兼容）

BACKWARD + FORWARD 的合体。既不能删必填字段，也不能加必填字段。说白了，只能加可选字段，或者改字段的 default 值。

这个模式最严格，但也最安全。我在金融、支付类项目里强制使用 FULL 模式。

避坑指南： 我曾经在一个项目中，把 BACKWARD 模式误配成了 NONE（不检查）。结果上线后，生产者删了一个字段，消费者直接反序列化失败。从那以后，我要求所有 Schema 变更必须走审批流程，Registry 自动检查兼容性。

4.5 Schema 演化策略

演化策略说白了就是：当 Schema 变了，你怎么保证上下游不崩。

我总结了一套「三步走」策略：

先加后删：加字段时设 default，等所有消费者都升级了，再删废弃字段
不改类型：字段类型一旦确定，不要改。实在要改，就加新字段，废弃旧字段
版本号递增：每次变更都生成新版本，Registry 自动记录

来看一个演化示例：

// v1 - 初始版本
{"name": "user_id", "type": "int"}

// v2 - 加字段，设 default
{"name": "user_id", "type": "int"},
{"name": "user_name", "type": "string", "default": ""}

// v3 - 废弃 user_id，加新字段
{"name": "user_id", "type": "int", "default": 0},
{"name": "user_name", "type": "string", "default": ""},
{"name": "new_user_id", "type": "string", "default": ""}

注意 v3 里，我没有删 user_id，只是加了 default。这样老消费者还能读，新消费者用 new_user_id。等所有消费者都升级了，再删掉 user_id。

4.6 核心流程：一张图看懂

下面这张图展示了 Schema 从定义到演化的完整流程：

4.7 实战建议

最后，分享几个我在项目中沉淀下来的实战建议：

Schema 版本号不要手动管理：让 Registry 自动递增，你只管提交变更
兼容性模式从 BACKWARD 开始：等团队成熟了，再切到 FULL
每次变更都写 changelog：哪怕只是加一个字段，也要记录为什么加、谁加的
消费者要处理未知字段：Avro 和 Protobuf 都支持忽略未知字段，别让消费者因为多了一个字段就崩溃

我的习惯： 每次上线前，我都会在测试环境跑一遍兼容性检查脚本。脚本会对比新旧 Schema，自动生成兼容性报告。如果报告里有「不兼容」的标记，直接阻断上线流程。这个习惯帮我避免了好几次线上事故。

嗯，Schema Registry 的实战内容就这些。记住一句话：Schema 是契约，Registry 是执行者。把契约定好，剩下的交给工具。