📚 课程目录第2章 Schema定义与规范

2. Schema定义与规范：选对语言，定好规矩

聊到Schema治理，第一个绕不开的问题就是：用什么语言来定义Schema？

我个人习惯把Schema定义语言比作“数据世界的契约”。契约写得好，上下游协作就顺畅；写得模糊，线上故障就找上门。今天咱们就掰开揉碎，聊聊三种主流方案——Avro、Protobuf、JSON Schema，再讲讲命名和版本号那些“看似简单、坑却不少”的细节。

核心观点：没有“最好”的Schema语言，只有“最合适”的场景。选型前，先想清楚你的数据是存还是传，是给谁用，兼容性要求有多高。

2.1 三大Schema定义语言对比

先上一张对比表，帮你快速建立全局认知。这张表是我在多个项目里反复验证过的，你直接拿去用就行。

特性	Avro	Protobuf	JSON Schema
序列化格式	二进制（紧凑）	二进制（紧凑）	文本（JSON）
Schema与数据关系	Schema独立存储，数据不自描述	Schema独立存储，数据不自描述	Schema可内嵌，数据自描述
兼容性演进	原生支持（读写分离）	需手动规则（字段编号）	需额外工具链
性能	高（适合大数据批量）	极高（适合RPC场景）	低（解析开销大）
可读性	中等（需反序列化）	低（需编译）	高（纯文本）
生态成熟度	Kafka、Hadoop生态	gRPC、微服务生态	REST API、配置文件

2.2 Avro：大数据场景的“老大哥”

Avro是Apache Hadoop生态的亲儿子。我在做实时数仓项目时，Kafka Topic的Schema几乎清一色用Avro。为什么？因为它天生为Schema演进设计的。

Avro的核心机制是读写分离——读数据的Schema和写数据的Schema可以不同，只要兼容就行。这玩意儿在数据湖场景下简直是救命稻草。

看个例子：

// 写数据时用的Schema（v1）
{
  "type": "record",
  "name": "User",
  "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"}
  ]
}

// 读数据时用的Schema（v2，新增了email字段，带默认值）
{
  "type": "record",
  "name": "User",
  "fields": [
    {"name": "id", "type": "int"},
    {"name": "name", "type": "string"},
    {"name": "email", "type": ["null", "string"], "default": null}
  ]
}

我的经验：Avro的默认值机制一定要用好。新增字段时，要么给默认值，要么设为nullable。否则老数据反序列化直接报错。我曾经因为忘加default，导致凌晨三点被电话叫醒……

2.3 Protobuf：微服务通信的“性能怪兽”

Protobuf是Google家的，gRPC的标配。如果你做微服务间的高频RPC调用，Protobuf几乎是唯一选择。它的序列化速度比JSON快10倍以上，体积小到离谱。

但Protobuf的兼容性规则比Avro更严格。它依赖字段编号（field number）来标识字段，而不是字段名。所以：

字段编号一旦分配，永远不能改
删除字段时，编号要保留（用reserved关键字）
新增字段必须用新编号

看个正确示范：

syntax = "proto3";

message User {
  int32 id = 1;          // 固定编号
  string name = 2;       // 固定编号
  reserved 3;            // 之前删掉的字段，编号保留
  reserved "phone";      // 之前删掉的字段名，保留
  optional string email = 4;  // 新增字段，用新编号
}

避坑指南：我曾经见过一个团队，因为删了字段后没加reserved，结果新加的字段复用了旧编号，导致线上数据解析错乱。那场面……嗯，你懂的。记住：Protobuf的字段编号是不可逆资产。

2.4 JSON Schema：REST API的“瑞士军刀”

JSON Schema不负责序列化，它只负责校验。说白了，就是给JSON数据定一套“规矩”——哪些字段必填、值范围多少、结构长什么样。

我一般在以下场景用JSON Schema：

REST API的请求/响应校验
配置文件的结构约束
数据交换格式的文档化

举个例子：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "name"],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  }
}

我的建议：JSON Schema的format关键字很好用，但不同实现的支持程度不一样。比如email格式，有的库严格校验，有的只做正则匹配。生产环境一定要先测试。

2.5 命名规范：好名字是Schema治理的第一步

命名这件事，看着简单，但我在项目里见过太多“车祸现场”。比如：

user_info vs UserInfo vs userInfo —— 同一个概念三种写法
order_id vs orderId vs OrderID —— 风格不统一
data、info、temp —— 含义模糊

我建议团队统一以下规范：

元素	推荐风格	示例	说明
Schema名称	PascalCase	`UserProfile`	首字母大写，单词首字母大写
字段名称	snake_case	`user_id`	全小写，下划线分隔
枚举值	UPPER_SNAKE_CASE	`STATUS_ACTIVE`	全大写，下划线分隔
命名空间	反向域名	`com.company.project`	避免冲突

核心原则：命名规范一旦确定，就要用工具强制落地。比如在CI/CD中加入Schema lint检查，不符合规范的直接拒绝合并。别指望靠“自觉”，人都会偷懒。

2.6 版本号规范：语义化版本是底线

Schema版本号怎么定？我强烈推荐语义化版本（SemVer），格式：MAJOR.MINOR.PATCH。

具体规则：

MAJOR（主版本）：不兼容的变更。比如删除了必填字段、改了字段类型。
MINOR（次版本）：向后兼容的新增。比如新增了可选字段、增加了枚举值。
PATCH（补丁版本）：不影响兼容性的修改。比如修正了字段描述、调整了默认值。

举个例子：

// v1.0.0 初始版本
User { id: int, name: string }

// v1.1.0 新增可选字段（兼容）
User { id: int, name: string, email?: string }

// v2.0.0 删除必填字段（不兼容）
User { id: int, email?: string }  // name被删了

注意：版本号不是随便加的。我见过一个团队，每次改Schema都升MAJOR版本，结果版本号飙到v47.0.0，完全失去了语义。记住：只有不兼容变更才升MAJOR，别滥用。

2.7 知识体系总览

下面这张图，帮你把本章的核心逻辑串起来。建议保存下来，以后做Schema选型时对照着看。

2.8 本章小结

好了，咱们把这一章的核心点捋一捋：

Avro：大数据场景首选，读写分离机制让Schema演进变得丝滑。记得用好默认值。
Protobuf：微服务RPC场景的王者，字段编号是命根子，删字段必须reserved。
JSON Schema：REST API和配置文件的校验利器，但别用它做高性能序列化。
命名规范：统一风格，用工具强制落地，别靠自觉。
版本号规范：语义化版本是底线，MAJOR只给不兼容变更。