手写 JSON Schema 大半天，改成一句话描述 10 分钟搞定：WorkBuddy json-schema-generator 实操

手写 JSON Schema 大半天，改成一句话描述 10 分钟搞定：WorkBuddy json-schema-generator 实操

说句实在话，我做接口联调最烦的不是写代码，是对字段。

后端返的字段叫 user_name，前端接口文档里写的是 username；说好的是字符串，一跑全是数字；联调到一半，产品又加了个 avatar 字段，文档没同步…… 半天时间就这么耗在"字段对不上→回去翻文档→再对"的循环里。

后来我把接口的校验规则用 JSON Schema 固化下来，字段错误在测试环境就直接爆出来。关键是——Schema 不再手写了。

先给没用过 WorkBuddy 的朋友补个背景：WorkBuddy 里的"技能"（Skill）就是一套提前封装好的工作流程，装进客户端后，你在对话框里说需求它自动调用，不用记命令、不用切窗口。下面要用的 json-schema-generator 就是其中一个技能。

一、json-schema-generator 是个啥

一句话：把"人话描述的数据结构"变成"机器能校验的 JSON Schema"。

以前写 Schema 是纯手工活：字段名、类型、必填项、枚举值、嵌套结构，一个字母写错接口校验就废。现在你只需要用大白话说清楚"这个接口要返回什么"，工具自动生成：

• JSON Schema（Draft 2020-12 标准）——校验规则本体
• 示例数据——符合 Schema 的 mock 数据，前端联调直接能用
• 校验说明——每个字段规则的中文解释，给团队看、给文档用

我第一次装的时候还以为要配环境敲命令，结果在技能市场搜到、点一下安装就完了，跟装手机 App 一样。

二、三步上手，跟聊天一样

1. 打开 WorkBuddy，装技能 左侧「技能」进技能市场，搜 "json-schema-generator"（或 "JSON Schema"），点安装，秒级生效。已在 SkillHub 上架，搜索即可安装。
2. 描述你的数据结构 对话框直接说人话。比如：生成一个"用户注册接口"的请求 Schema：手机号、密码、昵称（选填），手机号要校验 11 位数字格式
3. 拿 Schema + 示例数据走人 它会输出标准 Schema、一份符合规范的示例 JSON、一段校验说明。

输入需求

发送需求后，右侧会展开生成的 schema.json，字段、类型、必填、正则一目了然：

生成 Schema

三步就完事，不需要你懂 Schema 语法——当然，懂一点能更好地提需求，第五节给你模板。

三、真实案例：用户注册接口的请求校验

拿上面那个需求，工具生成的 Schema 长这样（核心部分）：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["phone", "password"],
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^1[3-9]\\d{9}$",
      "description": "手机号，11 位"
    },
    "password": {
      "type": "string",
      "minLength": 6,
      "maxLength": 32
    },
    "nickname": {
      "type": "string",
      "maxLength": 20
    }
  }
}

注意几个细节（都是它自动处理的）：

• required 只列了必填的 phone/password，nickname 是选填，自然不在里面
• 手机号的正则 ^1[3-9]\d{9}$ 直接给全了，不用自己查规则
• 密码长度限制、昵称长度限制都是描述里提到的，自动落到 min/maxLength

这比我手写快在哪？ 手写我要记 pattern 语法、要记得把选填字段排除出 required、嵌套对象还要小心括号配对——它一次生成全对。

四、进阶：示例数据 + 校验说明，联调直接起飞

Schema 只是第一步，真正省时间的是配套的两样东西。

示例数据：前端联调最怕没有 mock 数据。它生成的示例 JSON 是严格符合 Schema 的，前端直接拿来起服务，字段永远对得上：

{
  "phone": "13800138000",
  "password": "pass123456",
  "nickname": "小明"
}

校验说明：中文解释每条规则，我直接贴进接口文档，后端和前端看同一份说明，扯皮少一半。

五、给工具说人话：需求描述模板（直接复制改）

这是我最想分享的部分。工具生成得准不准，九成看你描述得清不清楚。下面这个模板是我踩过几轮坑后固定下来的，直接复制改：

生成一个"{接口名}"的 {请求|响应} Schema：
- {字段名}：{类型}，{必填|选填}，{特殊规则，如格式/长度/枚举}
- {字段名}：{类型}，{必填|选填}，{特殊规则}
（嵌套对象请写明"包含 xx、yy 字段"）

举个实际例子：

生成一个"创建订单接口"的请求 Schema：order_id：字符串，必填，20 位以内 amount：数字，必填，保留两位小数 status：字符串，必填，只能是 pending、paid、shipped、cancelled 之一 address：对象，必填，包含 province、city、detail 三个字符串字段

按这个模板说，生成结果基本不用改。要加校验规则（比如金额 > 0），直接补一句"amount 大于 0"就行。

六、串起来用：生成 → 校验 → 文档，一条链路吃三份红利

单个生成只是省事，串起来才是真提效。我现在跑接口时的固定链路：

需求描述生成 Schema → 贴进项目校验层 → 校验说明同步进接口文档

• 生成：新接口先按模板说需求，10 分钟拿到 Schema
• 校验：把 Schema 文件放项目里，用校验库（Python 的 jsonschema、JS 的 ajv 都行）在接口层跑一遍，字段错误测试环境就爆出来，不用等上线才发现
• 文档：校验说明直接贴接口文档，前后端看同一份规则

拿一份真实 JSON 跑校验，工具会逐字段告诉你是否通过：

校验 JSON

这条链路跑通后，我新接口从"写规则+等联调返工"变成"说需求+看报错修字段"，返工少了大半。

七、踩过的坑，提前避

1. 描述越具体，Schema 越准。 我第一次只说"生成一个订单接口的 Schema"，结果必填字段、类型全猜错。后来改成按第五节模板描述，一次生成就能用。

2. 枚举值要用"或"说清楚。 状态字段要限制取值范围，说"订单状态只能是 pending、paid、shipped、cancelled 之一"，它才会生成 enum。不说，就是自由字符串。

3. 生成完拿真实数据跑一遍。 我吃过一次亏：Schema 看着对，拿真实接口返回值一校验，漏了个可空字段。现在生成后必做一步：丢一份真实数据给校验库跑，报错就补规则。

4. 技能输出可以改，别删了重建。 生成结果有个别字段不满意（比如正则想更严格），直接在结果上改，或者跟它说"手机号校验改严格点"，比重新描述一遍快。

写在最后

JSON Schema 这东西，会写的人觉得简单，不会的人天天被字段坑。json-schema-generator 的价值就是把这层门槛抹平——你把精力放在"说清楚数据结构"上，剩下交给工具。

我现在的习惯是：新接口先描述需求生成 Schema → 贴进项目校验层 → 文档自动同步校验说明。一个动作吃三份红利：开发少返工、前后端少扯皮、接口质量有兜底。

如果你也被字段对不上折磨过，评论区聊聊你踩过最离谱的坑。

#WorkBuddy