JSON 转 TypeScript 类型定义生成器
粘贴 JSON 对象(或 JSON 数组),即可自动生成对应的 TypeScript interface/type 定义。
使用提示
- 当数组中的所有元素都是对象时,会合并各元素的键生成一个 interface。部分元素缺失的键会自动标记为可选属性(`?`)。
- 根类型名称默认是 "Root",可以修改为你喜欢的名称(例如 `User`、`ApiResponse`)。嵌套对象的 interface 名称会根据其所在的属性名自动生成。
- 直接粘贴 API 响应的示例 JSON,即可快速获得前端开发中所需类型定义的初稿。
- 生成的结果只是根据结构推断出的类型初稿。建议对照实际的 API 规范(是否可为 null、必填字段等)手动调整。
常见问题
手动根据 API 响应示例编写类型定义既耗时又容易出错,比如写错键名或漏掉某个类型。自动生成可以大幅节省前端开发者的时间,并减少这类失误。
工具会合并数组中所有元素的键,只在部分元素中出现的键会自动标记为可选属性(`?`)。如果同一个键在不同元素中类型不同,则会表示为联合类型(例如 `string | number`)。
生成的类型定义只是根据示例 JSON 的结构机械推断出来的。是否可为 null、未来是否会新增字段等信息无法仅凭示例 JSON 判断,建议对照 API 文档手动调整后再使用。
嵌套对象的 interface 名称会根据存放该对象的属性名自动生成(例如键名为 `profile` 的对象会生成名为 `Profile` 的 interface)。如果需要同名但结构不同的 interface,会在末尾添加序号加以区分。
闲话 ― 类型推断工具解决的"类型偏差"问题
TypeScript 是一门可以在编译期借助静态类型发现 bug 的语言,但对于从外部 API 获取的 JSON 数据,如果开发者不手动定义类型,TypeScript 编译器是无从得知其结构的。每当 API 规范与实际响应出现偏差,或者字段被增删,都需要手动更新类型定义,这种"类型定义与 API 实际情况不一致"的问题一直困扰着许多前端项目。
JSON 转 TypeScript 工具通过从实际返回的示例 JSON 反向推算类型,大幅提升了这项工作的效率。同类工具中比较有名的是 quicktype(一个可以生成多种语言类型定义的开源工具),它以支持 JSON Schema、GraphQL schema 等多种输入格式而闻名。
类型推断的难点在于,JSON 本身并不包含"这个字段是否总是存在""未来是否可能变为 null"等信息。因此自动生成的类型定义并非万能,实践中的通行做法是将其视为仅反映"本次示例数据结构"的初稿,再对照实际的 API 规范进行调整。