📚 课程目录第4章契约的发布与发现

4. 契约的发布与发现：注册中心的作用、Schema Registry 实战、契约的版本演进策略

契约写好了，然后呢？

放在本地文件夹里，发个邮件告诉下游「嘿，看这里」？

别闹了。生产环境里，契约必须有一个中心化的、可发现的、带版本管理的存放地。这就是注册中心要做的事。我见过太多团队因为契约散落在 Wiki、Git、甚至聊天记录里，最后对不上账，线上事故一查，原来是下游还在用三个月前的旧 Schema。

4.1 注册中心：契约的「电话本」

注册中心的核心作用，说白了就三件事：

存储：把契约（Schema）集中存起来，别散落一地。
发现：生产者发布后，消费者能主动查到最新版本。
校验：发布时自动检查兼容性，不合规的直接拦住。

你可以把它想象成一个「电话本」。生产者把自己的号码（Schema）登记上去，消费者翻一翻就能找到。但比电话本更智能的是——它还会告诉你，这个号码是不是已经换了区号（版本升级），以及你手里的老号码还能不能用（兼容性检查）。

关键认知：没有注册中心，数据契约就是一张废纸。你无法知道谁在用哪个版本，也无法在变更时通知所有人。

目前业界最主流的方案是 Confluent Schema Registry，它和 Kafka 深度绑定。当然也有其他选择，比如 Apicurio Registry（红帽出品，支持多种协议）或者干脆用 Git + CI/CD 自己搭一套。我个人习惯是：如果团队已经上了 Kafka 生态，直接用 Confluent Schema Registry 最省心；如果技术栈比较杂（既有 Kafka 又有 HTTP API），Apicurio 更灵活。

4.2 Schema Registry 实战：从发布到消费

我们拿 Avro 格式举个例子。假设你是一个订单服务的生产者，要发布一个 OrderCreated 事件。

第一步：定义 Schema

{
  "type": "record",
  "name": "OrderCreated",
  "namespace": "com.example.order",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "userId", "type": "string"},
    {"name": "amount", "type": "double"},
    {"name": "timestamp", "type": "long"}
  ]
}

第二步：注册到 Schema Registry

用 REST API 或者客户端 SDK 发布。我一般用 REST API 做演示，因为直观：

POST /subjects/order-created-value/versions
Content-Type: application/vnd.schemaregistry.v1+json

{
  "schema": "{\"type\":\"record\",\"name\":\"OrderCreated\",\"namespace\":\"com.example.order\",\"fields\":[{\"name\":\"orderId\",\"type\":\"string\"},{\"name\":\"userId\",\"type\":\"string\"},{\"name\":\"amount\",\"type\":\"double\"},{\"name\":\"timestamp\",\"type\":\"long\"}]}"
}

返回结果里会给你一个 id，这个 id 就是 Schema 的唯一标识。Kafka 消息里会带上这个 id，消费者拿到消息后，用 id 去 Registry 里拉取 Schema 来反序列化。

第三步：消费者自动发现

消费者不需要提前知道 Schema 长什么样。它只需要配置好 Schema Registry 的地址，消费消息时自动根据 id 拉取 Schema。这就是「发现」的过程。

// 消费者端配置示例
props.put("schema.registry.url", "http://schema-registry:8081");
props.put("key.deserializer", "io.confluent.kafka.serializers.KafkaAvroDeserializer");
props.put("value.deserializer", "io.confluent.kafka.serializers.KafkaAvroDeserializer");

小技巧：生产环境里，Schema Registry 一定要做高可用部署。我曾经遇到过 Registry 挂了，导致所有消费者无法反序列化消息，整个数据管道瘫痪。至少 3 节点起步，别省这个钱。

4.3 契约的版本演进策略

契约不是写死就不动了。业务在变，字段在加，类型在改。怎么管好版本？

Schema Registry 内置了几种兼容性策略，我列个表给你看：

策略	含义	适用场景
BACKWARD	新 Schema 可以读旧数据	消费者先升级，生产者后升级
FORWARD	旧 Schema 可以读新数据	生产者先升级，消费者后升级
FULL	双向兼容	生产者和消费者同时升级，但不确定谁先谁后
NONE	不检查兼容性	开发环境、快速迭代

你想想看，实际项目中哪个策略最常用？

我个人经验是：BACKWARD 用得最多。为什么？因为大多数场景下，我们希望消费者先升级（兼容旧数据），然后生产者再发新数据。这样即使消费者还没完全部署完，也不会因为读到旧格式的消息而崩溃。

举个例子：

旧 Schema 有 name 字段。
新 Schema 增加了 age 字段，且设置了默认值 0。
BACKWARD 策略下，新 Schema 可以读旧数据（age 取默认值 0）。
消费者先升级到新 Schema，没问题。生产者再发新数据，也没问题。

注意：千万不要在生产环境用 NONE 策略。我曾经接手过一个项目，前任把兼容性检查关了，结果 Schema 改了字段类型，下游反序列化直接抛异常，数据丢了整整一天才被发现。血的教训。

4.4 版本演进的核心原则

不管用哪种策略，有几个原则你得记住：

只加字段，不改类型：新增字段是最安全的变更。改类型（比如 string 改成 int）几乎总是破坏性的。
给新字段设默认值：这样旧数据反序列化时能兜底。
不要删除字段：删除字段会导致旧数据无法被新 Schema 读取。实在要废弃，标记为 deprecated，等所有消费者都迁移了再考虑删除。
版本号递增：每次变更都生成一个新版本，不要覆盖旧版本。Schema Registry 默认就是追加模式，别自作聪明去改历史版本。

下面这张图展示了契约从定义、注册、版本演进到被消费者发现的完整流程：

嗯，到这里你应该明白了：注册中心不是可选项，而是数据契约体系的基础设施。没有它，版本管理就是一句空话。Schema Registry 帮你自动做兼容性检查，省去了人工 review 的疏漏。版本演进策略选对了，生产者和消费者就能各自独立升级，互不阻塞。

我最后再啰嗦一句：别把 Schema Registry 当成一个「存 Schema 的数据库」。它更重要的价值是那个「校验」动作——在问题发生之前就拦住它。这个习惯养成了，你的数据管道会稳很多。