📚 课程目录第2章核心概念与术语

核心概念与术语：Schema 定义、字段类型、约束条件、版本控制、兼容性

好，我们直接进入正题。这一章要聊的，是 Schema 治理里最基础、也最绕不开的几个概念。说白了，就是一套 API 数据结构的“宪法”。你如果不把这些东西理清楚，后面做治理、做版本管理，全是空中楼阁。

我个人习惯，在开始任何新项目之前，先跟团队把这几条术语对齐。不然开会的时候，你说“字段类型”，他说“约束条件”，鸡同鸭讲，效率极低。咱们一个一个来拆。

1. Schema 定义：数据结构的“蓝图”

什么是 Schema 定义？你可以把它想象成一张建筑蓝图。它不关心具体的砖头水泥（也就是数据值），它只规定这栋楼有几层、每层多高、窗户开在哪。在 API 的世界里，Schema 定义就是描述数据长什么样、包含哪些字段、每个字段是什么类型的一套规则。

举个例子，一个用户信息的 Schema 定义，可能会说：

{
  "type": "object",
  "properties": {
    "userId": { "type": "string" },
    "userName": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["userId", "userName"]
}

你看，它只定义了结构，没有具体数据。这就是 Schema 定义的核心——约定大于配置。有了它，前端和后端就不用再靠“口头协议”来对接了。

核心要点： Schema 定义是数据契约的书面形式。它让机器可读，让人可理解。

2. 字段类型：数据的“身份证”

字段类型，就是告诉系统“这个数据到底是什么玩意儿”。是字符串？是数字？还是布尔值？这听起来很简单，但我在项目中遇到过无数次因为类型定义不清导致的线上事故。

比如，一个“年龄”字段，你定义成 string 还是 integer？如果定义成 string，前端传了个 "25"，后端也能处理。但如果你要做年龄排序，字符串排序和数字排序的结果完全不一样。这就是坑。

常见的字段类型包括：

string：文本，比如用户名、邮箱。
integer：整数，比如年龄、数量。
number：浮点数，比如价格、评分。
boolean：布尔值，比如是否激活。
array：数组，比如标签列表。
object：嵌套对象，比如地址信息。

嗯，这里要注意：不要滥用 string 来存所有东西。我曾经接手过一个老项目，里面所有字段都是 string，连时间戳都是字符串。结果做数据统计的时候，解析格式能让人崩溃。类型定义得越精确，后续的维护成本就越低。

3. 约束条件：数据的“交通规则”

光有类型还不够。你想想看，一个“邮箱”字段，类型是 string，但用户传了个 "abc" 进来，这显然不合理。约束条件就是用来干这个的——它给数据加了“边界”和“规则”。

常见的约束条件有：

约束类型	说明	示例
`required`	字段是否必填	用户注册时，手机号必填
`minimum / maximum`	数值范围	年龄最小 0，最大 150
`minLength / maxLength`	字符串长度限制	密码至少 8 位
`pattern`	正则表达式匹配	邮箱格式校验
`enum`	枚举值列表	状态只能是 "active" 或 "inactive"

避坑指南： 我曾经在定义订单状态时，只用了 string 类型，没有加 enum 约束。结果下游系统传了个 "pendding"（拼写错误），导致整个订单流程卡死。从那以后，凡是状态字段，我必加 enum 约束。

4. 版本控制：Schema 的“时光机”

API 不是一成不变的。业务在变，需求在变，Schema 也得跟着变。但你不能说变就变，把老客户端全搞崩了。这时候就需要版本控制。

版本控制的核心思想是：每个 Schema 都有一个唯一的版本号，并且历史版本可追溯。常见的做法是用语义化版本号，比如 v1.0.0、v2.1.0。

我个人习惯，在 Schema 定义里直接加上版本字段：

{
  "schemaVersion": "2.0.0",
  "type": "object",
  "properties": {
    "userId": { "type": "string" },
    "userName": { "type": "string" }
  }
}

为什么要这么做？因为当你同时维护多个版本的 Schema 时，没有版本号，你根本不知道当前这份定义对应的是哪个时期的逻辑。版本控制就是 Schema 的“时光机”，让你能随时回到过去。

小技巧： 版本号不要只放在文件名里，要嵌入到 Schema 本体中。这样即使文件被拷贝、重命名，版本信息也不会丢失。

5. 兼容性：新旧版本的“和平共处”

有了版本控制，接下来就是兼容性问题。你发布了 v2.0.0，但老客户端还在用 v1.0.0，怎么办？兼容性就是用来解决这个问题的。

兼容性分为两种：

向后兼容（Backward Compatible）：新版本的 Schema 能处理老版本的数据。比如，你新增了一个可选字段，老客户端没传，新服务也能正常处理。
向前兼容（Forward Compatible）：老版本的 Schema 能处理新版本的数据。比如，新版本新增了一个字段，老客户端看到不认识，直接忽略，不会报错。

在实际项目中，向后兼容是底线。你不能因为升级了 Schema，就把老用户全抛弃了。我见过最惨的一次事故，就是团队升级 API 时，把一个必填字段改成了新的格式，结果老客户端没适配，线上大面积报错。

那怎么保证兼容性？有几个原则：

只增不减：尽量不要删除字段，可以标记为废弃（deprecated）。
放宽约束：比如把必填改成可选，把枚举值范围扩大。
避免类型变更：不要把 string 改成 integer，这属于破坏性变更。

核心要点： 兼容性不是技术问题，是契约问题。你改 Schema 之前，先问问自己：“老客户端会不会挂？”

知识体系总览

为了让你更直观地理解这五个概念之间的关系，我画了一张图。你可以把它当作本章的“知识地图”。

从这张图你可以看到，五个概念不是孤立的。Schema 定义是基础，字段类型和约束条件构成了它的骨架。而版本控制和兼容性，则是让这个骨架能够随着业务演进而持续运转的“润滑剂”。

嗯，这一章的内容就到这里。概念虽然多，但都是后面章节的基石。你先把这几个术语刻在脑子里，后面讲治理策略、讲工具选型的时候，我们才能在一个频道上对话。