JSON 转 TypeScript：样本推断、可选字段与运行时校验

一个样本，是观察结果而不是完整规范

接口返回一条包含姓名与邮箱的记录，不能证明每条记录都有邮箱，也不能证明字段永远不会是 null。由 JSON 生成 TypeScript，可以减少机械输入，但它描述的是眼前样本。

生成后仍需结合接口约定补充可选字段、联合类型和业务限制。若有多个有代表性的响应，应同时检查正常、空集合与缺失字段的情况。

格式化先帮助人阅读

缩进和换行能让嵌套结构更容易看懂，但不会验证业务意义。字段是合法 JSON，并不代表金额单位、时间格式或标识符都符合你的系统要求。

比较两次响应时，可以先统一排版以减少视觉噪声，再判断字段变化。文本差异显示的是字符变化，仍然需要你判断它是否意味着接口行为改变。

类型声明不会自动验证运行时输入

TypeScript 声明帮助开发时检查用法，但不会把收到的网络数据自动变成可信对象。需要运行时校验的地方，应由应用自己的校验逻辑处理。

因此更合适的用法是：用样本生成初稿，按照真实接口规范修订，再配合应用的错误处理。不要把工具输出直接当作完整的接口规范。

签名检查要保留原始字节

HMAC 计算针对消息字节。即使两个 JSON 解析后的对象相同，增加空格、改变换行或重新排序字段，也可能得到不同的摘要。调试时不要把格式化副本替代原始签名消息。

在 Neatbo 中使用脱敏响应和测试密钥，并确认输入编码与对方协议一致。浏览器内计算可以减少文件传输，但不能替代密钥管理或接口权限控制。

把正常响应与字段不完整的响应一起看

下面两条记录的差异不只是值：第二条缺少 email，tags 为空数组。仅凭样本，无法判断缺失字段是合法情况还是服务端错误；应先查 API 规范，再决定 TypeScript 属性是否可选。

空数组不能提供元素类型的证据。同样，一个非空值也无法证明该字段永远不会为 null。应收集包含错误响应在内的代表性样本，把接口规范层面的决定与生成的类型语法分开。

对于标识符，应区分数字形式与业务含义。看起来很长的十进制编号通常需要按字符串处理；已经被 JavaScript 数字舍入后，再转回字符串也不能找回丢失的位数，必须从输入边界保留正确表示。

[
  {"id":"00123","email":"[email protected]","tags":["new"]},
  {"id":"00456","tags":[]}
]

完成前的检查清单

• 将生成类型放入实际代码前先审查。
• 测试缺失、null 和空集合状态。
• 需要时，在应用输入边界校验不可信响应。
• 签名计算保留原始载荷字节，不使用格式化副本。

本文相关工具