2. Schema设计原则：命名规范、字段类型选择、版本号管理、兼容性设计

Schema 设计这件事，说白了就是给数据立规矩。规矩立得好，后面十年都省心；立得不好，天天加班修数据。我带过好几个数据平台的项目，踩过的坑能写满一个笔记本。今天我把最核心的四个设计原则掰开揉碎讲给你听。

2.1 命名规范：看着舒服，查着不累

我见过最离谱的字段名叫 fld_1、col_b、temp_data_2024_old_new_final。你想想看，三个月后你自己都看不懂这字段存的是什么。

命名规范的核心就三条：

• 自解释性——看到名字就知道含义，不需要翻文档
• 一致性——同一个团队、同一个项目，风格统一
• 可读性——别搞缩写谜语，usr_nm 不如 user_name

我个人习惯用 snake_case（小写+下划线），这在 Avro、Protobuf、JSON Schema 里都通用。举个例子：

// 好的命名
user_id
order_created_at
payment_amount_cents
shipping_address_city

// 坏的命名
uid
ordCrtDt
payAmt
addrCity

我在项目中遇到过一件事：有个同事把字段名从 user_phone 改成了 phone_number，结果下游 12 个消费方全部报错。嗯，这里要注意——命名一旦上线，改起来就是牵一发动全身。

2.2 字段类型选择：选对类型，省一半存储

类型选错，后果很严重。我曾经见过有人用 string 存时间戳，结果做范围查询时性能惨不忍睹。也见过用 decimal(38, 0) 存年龄的，一个字段占 16 字节，其实 int 就够了。

选类型时记住这几条：

• 能用数值就别用字符串——数值比较和计算比字符串快一个数量级
• 能用整数就别用浮点——浮点有精度问题，金额用 decimal 或 int（存分）
• 时间戳统一用 UTC——别问为什么，问就是时区战争打怕了
• 枚举值用 enum 类型——别用 string 存 'active'、'inactive'，容易拼错

给你看个对比表：

场景	推荐类型	不推荐类型	原因
用户年龄	int	string	数值比较快，还能做聚合
订单金额	int（单位：分）	float	浮点精度丢失，0.1+0.2≠0.3
状态码	enum	string	enum 有约束，不会出现非法值
创建时间	timestamp	string	timestamp 支持时区转换和范围查询
用户备注	string	text	string 有长度限制，避免大字段

2.3 版本号管理：给 Schema 一个身份证

Schema 是会变的。业务调整、字段新增、类型修正——这些都是常态。没有版本号，你根本不知道线上跑的是哪个版本的 Schema。

版本号怎么管？我推荐 语义化版本（SemVer）：

• MAJOR：不兼容的变更（删字段、改类型）
• MINOR：向后兼容的新增（加字段、加默认值）
• PATCH：内部修正（注释更新、格式调整）

举个例子：

// 版本 1.0.0
{
  "name": "user_event",
  "version": "1.0.0",
  "fields": [
    {"name": "user_id", "type": "string"},
    {"name": "event_type", "type": "string"}
  ]
}

// 版本 1.1.0（新增字段，兼容）
{
  "name": "user_event",
  "version": "1.1.0",
  "fields": [
    {"name": "user_id", "type": "string"},
    {"name": "event_type", "type": "string"},
    {"name": "event_time", "type": "timestamp", "default": null}
  ]
}

// 版本 2.0.0（改了类型，不兼容）
{
  "name": "user_event",
  "version": "2.0.0",
  "fields": [
    {"name": "user_id", "type": "int"},  // 从 string 改成 int
    {"name": "event_type", "type": "string"},
    {"name": "event_time", "type": "timestamp"}
  ]
}

我记得有一次，生产环境同时跑了三个版本的 Schema，因为没有版本号，运维根本不知道哪个是新的。后来我们强制要求：每次变更必须更新版本号，并且记录 changelog。

2.4 兼容性设计：让新旧版本和平共处

这是最考验功力的部分。兼容性设计做不好，每次升级都是一次灾难。我见过一个团队升级 Schema，结果下游 30 个服务全部挂掉，回滚花了整整两天。

兼容性分两种：

• 向后兼容：新 Schema 能读旧数据
• 向前兼容：旧 Schema 能读新数据

实际项目中，我们主要关注 向后兼容。怎么做？记住这几条铁律：

1. 只加字段，不删字段——删字段是最大的不兼容
2. 新增字段必须设默认值——null、0、空字符串都行，但不能没有
3. 不改已有字段的类型——string 改 int？想都别想
4. 不改已有字段的语义——原来存手机号，别改成存邮箱

给你看个兼容性决策矩阵：

变更类型	向后兼容	向前兼容	建议
新增字段（有默认值）	✅ 是	✅ 是	安全，放心做
新增字段（无默认值）	❌ 否	✅ 是	不推荐，旧数据读不了
删除字段	❌ 否	❌ 否	禁止，用废弃标记代替
修改字段类型	❌ 否	❌ 否	禁止，新建字段替代
修改字段名	❌ 否	❌ 否	禁止，别名或新建字段
放宽字段约束	✅ 是	❌ 否	谨慎，评估下游影响

我曾经犯过一个错：给一个已有字段加了 required 约束，结果旧数据全是 null，消费端直接崩溃。从那以后，我给自己定了个规矩——永远不要收紧约束，只能放宽。

知识体系总览

下面这张图把本章的核心逻辑串起来了。你可以把它当作 Schema 设计的检查清单：

这四个原则不是孤立的。命名规范影响可读性，字段类型影响性能和存储，版本号管理影响可追溯性，兼容性设计影响系统稳定性。把它们结合起来，你的 Schema 才能经得起时间考验。