📚 课程目录第4章数据Schema定义

4、数据Schema定义：选对格式，管好版本

数据契约的核心，说白了就是一份双方都认的「数据说明书」。而Schema定义，就是这份说明书的语法和结构。格式选错了，版本管乱了，后面数据质量全是坑。我这些年踩过的坑，十有八九都跟Schema有关。

4.1 Schema格式怎么选？Avro、Protobuf、JSON Schema

先聊格式选择。市面上主流的三家：Avro、Protobuf、JSON Schema。没有的好坏，关键看场景。

特性	Avro	Protobuf	JSON Schema
序列化格式	二进制（紧凑）	二进制（紧凑）	文本（JSON）
Schema存储	与数据分离，读写时需传递	通常预编译进代码	与数据同文件或独立
动态类型支持	强（天然支持）	弱（需反射）	强（运行时解析）
生态成熟度	Hadoop/Kafka生态首选	微服务/gRPC标配	REST API/配置文件常用
兼容性演进	内置策略，非常完善	需手动管理	需额外工具

我个人习惯这样选：

数据管道用Kafka、Hadoop？Avro。它天生为流式数据设计，Schema Registry是标配。
微服务间RPC调用？Protobuf。性能好，代码生成强，gRPC的最佳搭档。
API网关、配置文件、数据交换？JSON Schema。人类可读，调试方便，生态工具多。

我的经验： 有一次项目选了Protobuf做数据湖的Schema定义，结果下游分析师看不懂二进制，每次都要转JSON，效率极低。后来换了Avro + Schema Registry，问题迎刃而解。选格式前，先想清楚谁在用数据。

4.2 字段类型与约束：别让「字符串」害了你

字段定义看似简单，其实最容易出问题。我见过太多「所有字段都是string」的Schema，那跟没定义一样。

核心原则： 类型越精确，质量越好。

数值型： 用int、long、float、double，别用string。我遇到过金额字段用string存，结果排序按字典序，100块比20块「小」。
时间型： 统一用timestamp类型，别用string存「2024-01-01 10:00:00」。时区问题、格式问题，全是坑。
枚举型： 用enum，别用string。状态字段「待审批」「已通过」「已驳回」，用enum能自动校验，用string就得写一堆正则。
约束： 必填（required）、默认值（default）、取值范围（minimum/maximum）、正则（pattern）。这些约束是数据质量的第一道防线。

避坑指南： 我曾经接手一个项目，订单状态字段用string，允许任意值。结果数据里出现了「待审」、「待审核」、「待审批」、「待批准」四种写法。后来加了enum约束，数据质量立竿见影。

4.3 Schema版本管理：别让「改字段」变成灾难

Schema一定会变。业务在变，需求在变，字段自然要变。但怎么变，是个技术活。

版本管理三要素：

版本号： 语义化版本（major.minor.patch）。major：不兼容变更；minor：向后兼容新增；patch：bug修复。
存储： Schema Registry（Confluent Schema Registry、Apicurio Registry）。集中管理，自动校验。
演进策略： 明确哪些变更兼容，哪些不兼容。

注意： 版本号不是随便写的。我见过团队把Schema版本号跟应用版本号绑在一起，结果Schema改了10次，版本号还是1.0.0。版本号只反映Schema本身的变更，跟应用无关。

4.4 兼容性检查：向前？向后？还是全兼容？

兼容性检查是Schema管理的核心。说白了，就是新Schema能不能读老数据，老Schema能不能读新数据。

三种兼容性模式：

模式	定义	典型场景
向后兼容	新Schema能读老数据	生产者先升级，消费者后升级
向前兼容	老Schema能读新数据	消费者先升级，生产者后升级
全兼容	同时满足向前和向后	生产者和消费者独立升级

具体规则（以Avro为例）：

允许： 新增字段（带默认值）、删除字段（带默认值）、修改字段默认值、扩展enum值。
不允许： 删除必填字段、修改字段类型（除非兼容）、缩小enum值范围。

我的建议： 刚开始做数据契约时，先选「向后兼容」。这是最安全的模式。等团队成熟了，再考虑「全兼容」。别一上来就追求完美，兼容性越强，约束越多，开发效率越低。

4.5 实战：用Avro定义数据契约

说了这么多，来点实际的。下面是一个用户订单的Avro Schema示例：

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example.contract",
  "fields": [
    {"name": "order_id", "type": "string", "doc": "订单唯一标识"},
    {"name": "user_id", "type": "string", "doc": "用户ID"},
    {"name": "amount", "type": "double", "doc": "订单金额"},
    {"name": "status", "type": {"type": "enum", "name": "OrderStatus", "symbols": ["PENDING", "PAID", "SHIPPED", "COMPLETED", "CANCELLED"]}, "doc": "订单状态"},
    {"name": "created_at", "type": {"type": "long", "logicalType": "timestamp-millis"}, "doc": "创建时间"},
    {"name": "updated_at", "type": ["null", {"type": "long", "logicalType": "timestamp-millis"}], "default": null, "doc": "更新时间"}
  ]
}

注意几个关键点：

order_id 是string，但实际是UUID，约束在应用层。
status 用了enum，不是string，自动校验。
updated_at 是union类型（null + timestamp），且默认值为null，支持向后兼容。

4.6 知识体系：Schema定义全景图

下面这张图，帮你把本章的知识点串起来：

嗯，这张图把本章的核心逻辑都串起来了。从Schema定义出发，三个分支：格式选择、字段类型与约束、版本管理。版本管理里又包含兼容性检查。你想想看，是不是每个环节都环环相扣？

4.7 小结：Schema定义是数据质量的基石

Schema定义做得好，数据质量就成功了一半。格式选对，字段定义精确，版本管好，兼容性检查到位，后面的数据生产、消费、治理都会顺畅很多。

我记得有一次，一个团队因为Schema版本没管好，生产者和消费者同时升级，结果数据全乱了。后来花了三天才恢复。从那以后，我每次做数据契约，第一件事就是先把Schema版本管理方案定下来。

好了，这一章就到这里。记住：Schema定义不是一次性的工作，而是持续演进的过程。