JSON 转 TypeScript — 从 JSON 生成 TypeScript 接口
从 JSON 数据生成 TypeScript 接口。自动识别类型、可选字段、只读属性 —— 在浏览器中完成，无需上传。
JSON to TypeScript Interface
Generate TypeScript interfaces from JSON data. Auto-detects types, optional fields, and nested objects. Works entirely in your browser.
TypeScript 已经在 JavaScript 生态中占据了绝对主导地位,以至于每一个重要的 NPM 包、每一个框架、每一款 IDE 都把 TypeScript 类型定义作为发行的一部分。语言本身的核心价值在于:你写一次类型,就能在整个项目生命周期里获得编辑器自动补全、重构安全性以及编译期错误检测。为每一个 API 响应手写 TypeScript interface —— 还得处理嵌套对象类型、可选属性、联合类型推断 —— 是 TypeScript 开发中最主要的体力活,而生成的 interface 也就成了每一个组件、每一个 hook、每一处涉及该 API 的测试的单一事实来源。
不那么显然的、TypeScript 独有的考量,是 interface 和 type 的区别。interface 可以合并(不同文件里两个 interface User {} 声明会合并成同一个类型),这对需要可扩展的库和声明文件很有用。type 别名不能合并,但能表达联合、交叉、映射和条件类型 —— 在应用代码里它是更强大的构造。生成器默认输出 interface,是因为 TypeScript 团队的官方风格指南对对象形状更推荐 interface;不过对于更喜欢 type 别名、或确实需要联合类型的团队,这个开关已经准备好了。
生成 TypeScript interface 之后,最常见的下游动作是把它交给一个 React 组件、一个 Next.js API 路由,或一个消费该 API 响应的工具函数。如果项目用的是 Zod,打开 Zod 选项,生成的 schema 会在运行时校验响应,并由 schema 反推出 TypeScript 类型 —— 单独的 interface 文件都不必再维护。如果项目用的是 tRPC,生成的 interface 就是 t.procedure.input() 的输入,用来构造带类型的 RPC 端点。interface 是契约;组件、hook、错误处理器是应用层。
使用方法
粘贴你的 JSON
放入一个 JSON 对象或数组。生成器遍历结构,为根节点输出一个 TypeScript `interface`,为每个嵌套对象形状生成对应的子接口。
选择 interface 还是 type
在 `interface`(可扩展、可与同名声明合并)和 `type`(精确、支持联合与交叉类型)之间切换。默认使用 interface。
复制或下载 .ts 文件
把生成的 TypeScript 复制到剪贴板,或下载为 .d.ts 文件。输出可通过 `tsc --noEmit` 编译 —— 无需额外的类型依赖。
常见问题
应该用 interface 还是 type?
`interface` 是 TypeScript 对对象形状的默认推荐写法 —— 支持声明合并与扩展。`type` 是需要精确对象类型、联合类型或交叉类型时的正确选择。对于大多数 API 响应,`interface` 已经足够。
可选属性是怎么确定的?
在部分数组元素中缺失、或在样本中为 null 的属性,会被输出为可选(`key?: Type`)。在所有数组元素中都存在的属性为必选。开启「全部可选」开关会把每个属性都标为可选 —— 这是面向会演化的 API 的最稳妥选择。
能生成 Zod schema 吗?
在输出选项中开启「Zod」,即可在 TypeScript 类型之外再生成一份 Zod 校验 schema。Zod schema 在运行时校验数据,并反推出 TypeScript 类型,因此接口与校验器始终保持同步。Zod 需要安装 `zod` 这个 npm 包。
怎么处理联合类型?
同一个字段在一个数组元素中是字符串、在另一个中是数字时,会被类型化为 `string | number`。一个元素中是对象、另一个中是 null 时,则是 `Type | null`。生成器会推断出覆盖所有观测值的最窄联合。
能生成 const 断言吗?
可以 —— 开启「const」开关,会在数组字面量后面加上 `as const`,用于生成 tuple 类型或只读 record 类型。对那些在运行时不应被修改的 API 固定数据,使用 const 断言很合适。
限制说明
- 不识别可辨识联合生成器不会从一个 `type` 属性键推断出可辨识联合。一个多态的 JSON 响应,比如 `{ type: 'image', src: '...' } | { type: 'text', body: '...' }`,会被类型化成一个扁平的联合 —— 需要可辨识联合的话,生成后自己补上。
- 不支持泛型参数输出是一个具体的 interface。像 `ApiResponse<T>` 这种泛型 API 响应包装器,需要类型参数,而生成器不会推断。需要泛型时自己加上,并把内部类型参数化。
- 不带 JSDoc 注解生成的 interface 不带任何 JSDoc 注释。如果要让类型自文档化,自己手动补上 `@description`、`@example`、`@deprecated` 这些注解。
平台说明
- macOS
- 启用了 TypeScript 支持的 VS Code 可以原生处理生成的 interface。开发中从一条样例 API 响应临时生成时,用这个浏览器工具很合适。
- Windows
- 生成的 interface 在任何 TypeScript 项目中都能编译。从浏览器中粘贴过来的 API 响应,可以临时用它生成。
- Linux
- 命令行场景下,`quicktype --lang typescript` 是标准的等价工具。没有装 Node.js、只是临时生成时,这个浏览器工具更合适。
- Web
- 完全在客户端运行,生成是即时的。