JSON 转 TypeScript 接口实战:从接口返回值生成类型,省去手写

接一个新的后端接口,第一件烦人的事往往不是写逻辑,而是给响应补类型。文档列了三十多个字段,你照着一个个敲 interface,敲到一半还得猜哪个是嵌套对象、哪个数组里元素长什么样。等接口真返回数据,发现文档又漏了两个字段。手写类型这件事,本质上是在复述一份已经存在的结构,价值低,还容易抄错。

把这一步交给工具做更合理:拿一段真实响应,直接推出 TS 接口。下面把推断里几个容易踩的点讲清楚,再走一遍完整的输入输出。

为什么手写接口类型是重复劳动

类型声明描述的是数据的形状,而数据本身就摆在你面前。你 curl 一次接口,JSON 已经把每个 key、每层嵌套、每个数组都说清楚了。再手动翻译成 interface,等于把同一份信息抄第二遍。抄写过程里人会犯三类错:漏字段、把可选当必需、把嵌套对象拍平。这三类错编译器一开始查不出来,等运行时报 undefined 才发现。

用 JSON 转 TypeScript 接口工具 把响应粘进去,推断器读每个 key,把结构原样翻成声明,这三类抄写错误从源头消失。

嵌套对象与数组怎么处理

嵌套对象会被抽成独立接口,并按父级命名。比如根名设成 GitHubUser,里面的 plan 对象会自动变成 GitHubUserPlan,而不是塞一坨匿名内联类型。这样你 Cmd 点击就能跳转,结构也分层清楚。

数组分两种。元素是标量或混合形状时直接 union:[1, "a", null] 推成 (number | string | null)[],而且 null 永远排到 union 末尾,读起来顺。元素是形状不同的对象时,推断器不会吐出好几个接口,而是把它们折叠成一个,差异字段以可选形式呈现。

可选字段是怎么识别的

这是最有价值的一条规则。当某层是对象数组时,数组里每个对象都折叠进同一个 shape。一个 key 在 N 个元素里只出现 n 次(n < N),就被标成 ?。换句话说,推断器不只告诉你字段叫什么,还告诉你哪些字段每次都在、哪些只是有时候有。

这正好对上接 webhook 的真实困境。第三方文档写着"这个字段有时候在",到底什么时候在没人说得清。你把前几次 payload 当成一个 JSON 数组粘进去,推断结果直接把"非每次都有"的字段标成可选,比读文档可靠得多。

需要注意:单个对象作为根没有这种模糊性,所有 key 都算必需。如果你这段 JSON 本身就是唯一真相而不是采样列表,打开严格模式,所有 key 都标必需,不再按数组采样去推可选。

一段真实的输入输出

我自己接一个内部订单接口时,响应大概长这样:

[
  { "id": 1, "buyer": { "name": "Lei", "vip": true }, "coupon": "X10" },
  { "id": 2, "buyer": { "name": "Han" } }
]

根名设成 Order,推出来是这样:

export interface Order {
  id: number;
  buyer: OrderBuyer;
  coupon?: string;
}

export interface OrderBuyer {
  name: string;
  vip?: boolean;
}

看几个细节:coupon 只在第一个元素出现,被标了 ?;buyer 抽成了 OrderBuyer 子接口;vip 同样因为第二个 buyer 里没有而成为可选。这套结果直接复制进 src/types/order.ts 就能用,我没改一个字。整个过程比手敲快了不止十倍,关键是可选字段那两处,手写时我大概率会漏掉。

几个容易踩的坑

JSON 数字一律推成 number,没有 int 和 float 之分。一个永远是 42 的字段不会变成字面量类型,需要更窄的类型得配运行时校验器,比如 zod。另外输出只是类型,不是 JSON Schema,运行时 API 仍可能返回任何东西,边界处该校验还得校验。

还有解析层面:工具走严格 JSON.parse,末尾逗号、注释、不带引号的 key 都会报错。手头是 YAML 或带注释的配置时,先用 YAML 转 JSON 工具 过一道,再把干净 JSON 粘进来。如果只是想确认 JSON 本身格式没问题,JSON 格式化工具 可以先帮你排版校验一遍。

小结

从接口返回值生成类型,核心收益有三个:嵌套对象自动分层命名、数组元素合并成带 union 的单一接口、可选字段按采样自动识别。这三件事手写时最费神也最容易错,交给推断器之后,你省下的时间可以花在真正需要判断的地方。整个推断全在浏览器本地完成,JSON 不出标签页,贴生产响应也安全。

---

Made by Toolora · Updated 2026-06-13