JSON Schema 在 API 校验中的实用方式

JSON Schema 最有价值的地方，是描述 API 真正依赖的数据结构。它不需要覆盖所有业务规则，也能帮你发现很多问题。

哪怕一个很小的 schema，也能抓出缺字段、类型错误、枚举值异常，以及团队之间的契约漂移。

从契约边界开始

好的 schema 应该瞄准一个边界：

• 接口接收的请求体。
• 服务返回的响应体。
• 发给合作方的 webhook payload。
• 启动时读取的配置文件。
• 发布到队列里的事件消息。

边界很重要，因为它决定谁需要保持契约稳定。

先校验结构

先写那些变化后会破坏消费者的字段：

• 必填属性。
• 基础类型。
• 数组和对象。
• 枚举值。
• 可空字段。
• 日期或 ID 字符串格式。

之后可以继续细化。第一版的目标，是让常见错误显眼。

把示例放在 schema 旁边

Schema 和示例放在一起更容易被信任。至少保留一个合法示例和一个故意非法的示例。

调试时，可以把 payload 粘到 JSON 格式化工具 中，结合 schema 校验，再把错误路径和 API 代码或文档对照。

不要把所有规则都塞进 JSON Schema

有些规则应该放在别处：

• 权限检查。
• 数据库存在性检查。
• 依赖当前状态的跨字段规则。
• 限流和配额。
• 业务流程判断。

JSON Schema 很适合校验 payload 形状，但不能替代应用逻辑。

契约漂移的信号

如果出现这些现象，就该考虑补 schema：

• 前端到处写 typeof 防御。
• API client 同时兼容新旧字段名。
• webhook 只在某个合作方那里失败。
• 测试 fixture 和生产 payload 对不上。
• 文档示例和真实响应不一致。

这些都是更新契约的好时机。

实用规则

如果人经常打开 payload，只是为了确认某个字段是否存在、类型是否正确，那么这个检查大概率应该进入 schema。