JSON 转 TypeScript

相关推荐

关于 JSON 转 TypeScript：把 JSON 数据自动变成 TS 类型

适用场景

• 前后端联调时前端开发拿到 Postman 导出的响应 JSON 样本，直接粘贴生成 TS 类型，再也不用翻 Swagger 文档逐字段手抄。
• 测试工程师在 Jest/Vitest 单测里复用后端真实响应 JSON，生成 interface 后给 mock 数据加上类型约束，避免 fetch 返回结构悄悄变化时断言失效。
• 运维人员从 ELK/Kibana 抓取线上错误日志中的 JSON 字符串片段，转成 interface 后接入告警规则配置，把字段名映射成可结构化查询的关键字。
• 数据分析师把 DataX/Fivetran 导出的半结构化 JSON 字段转成 TS 类型定义，交给前端做展示页时直接强类型消费，避免运行时找不到字段而崩溃。
• 接口联调发现某个字段值实为 null 被吞掉接口 200，开可选字段开关后生成 name?: string 让 strictNullChecks 立刻报错定位问题字段。
• 团队 Code Review 时把生成的 DTO 提交到 PR，CI 跑 tsc --strict 自动把 any 残留字段标红，逼迫 mock 数据补全后再合入主干。
• 用 json/format 工具把压成一行的 API 响应排版后再转 TS，避免原始压缩 JSON 里漏看某个尚未出现的可选字段。
• 产品经理调整字段后，后端把新的 MySQL 行转 JSON、丢进本工具，前端直接拿到 v2 版本对应的 interface，旧字段直接通过 interface 的 declaration merging 自然追加。
• 新人 onboarding 拿到一坨手写 any 的老代码，把示例 data.json 转换成正式 interface 后让 ESLint 立刻揪出全部 any 赋值。
• 把含尾随逗号、单引号的 mock 数据文件丢进工具，靠内置的 tryFixJSON 自动修复后顺手产出 TS 类型，省去手动到 IDE 修一遍的步骤。
• 前端做 Storybook 组件文档时，把 props 示例值 JSON 转成 interface，再粘贴到 .stories.tsx 的 type 声明里，文档和组件强类型一一对应。
• 对接企业 SSO 登录返回的嵌套 JSON（user/profile/roles 三层嵌套）转 TS，自动生成 Root、RootProfile、RootRoles 三个子接口直接用于 useUser hook 返回值类型。

使用方法

1. 在左侧输入框粘贴 JSON 内容，或点击「上传」按钮选择 .json/.txt 文件，或点击「示例」加载内置样例。
2. 点击工具栏右侧的 interface 名称按钮（或齿轮图标），自定义根 interface 名称（默认 Root）、开启可选字段/只读字段。
3. 工具会自动转换（输入后 400ms 防抖）；在右侧查看生成的 TypeScript interface 代码，CodeMirror 高亮便于阅读。
4. 选择缩进风格（2 空格或 4 空格），调整工具栏左侧/右侧面板宽度以获得最佳查看体验。
5. 点击「复制」将 TS 代码复制到剪贴板，或点击「下载」保存为 `${interfaceName}.ts` 文件（如 User.ts）。
6. 将代码粘贴到项目 `types/` 目录或 `src/types/` 目录中，按需 import 使用。

功能特点

• 智能类型推断：自动识别 null、boolean、number、string、array、object 等 TypeScript 类型，映射为原生 TS 语法。
• 嵌套对象自动展开：为嵌套对象自动创建独立子 interface（如 RootAddress），保持类型层级清晰、避免冗余。
• 数组类型智能处理：元素类型一致生成 `T[]`，混合类型生成联合数组 `(A | B)[]`，空数组兜底为 `any[]`。
• 可选字段标记：开启后自动检测 null/undefined 字段，添加 `?` 修饰符，生成符合 TypeScript strict 模式的代码。
• 只读字段支持：开启后为所有字段添加 `readonly` 修饰符，适合不可变状态、配置、DTO 等场景。
• interface 名称自定义：根 interface 名称可配置（默认 Root），下载文件名以该名称命名（如 User.ts）。
• 2/4 空格缩进可选：工具栏一键切换 2 空格（ESLint 默认）和 4 空格缩进风格。
• 实时自动转换：输入 JSON 后 400ms 防抖自动转换，无需点击按钮；支持粘贴、文件上传、示例三种输入方式。
• JSON 错误自修复：内置 tryFixJSON 修复函数，自动处理尾随逗号、单引号、缺引号等常见语法错误。
• TypeScript 代码高亮：右侧输出使用 CodeMirror + JavaScript (TypeScript) 高亮，可读性强。
• 复制与下载：一键复制到剪贴板，或下载为标准 .ts 文件直接用于前端项目。
• 纯浏览器本地处理：所有 JSON 解析、类型推断、interface 生成都在浏览器 JavaScript 中完成，原始数据不上传。

常见问题

故障排查

术语表

JSON (JavaScript Object Notation)

轻量级数据交换格式，基于 JavaScript 对象语法但独立于编程语言。支持对象 ({}), 数组 ([]), 字符串, 数字, 布尔, null 六种基本类型。广泛用于 REST API、前后端数据传输、配置文件、日志等场景。

TypeScript

由 Microsoft 开发的 JavaScript 超集，为 JavaScript 添加了静态类型定义、接口、泛型等特性。TypeScript 代码会被编译为纯 JavaScript 后运行于浏览器或 Node.js。是 React、Vue、Angular 等现代前端项目的首选语言。

interface（接口）

TypeScript 中描述对象类型的关键字，语法为 `interface Name { prop: type; }`。支持声明合并（同名 interface 自动合并）、implements（类实现接口）、extends（接口继承）。是 TypeScript 描述对象形状的主要方式。

type 别名

TypeScript 中给类型起别名的关键字，语法为 `type Name = ...`。可用于定义联合类型 (`A | B`)、交叉类型 (`A & B`)、函数类型等。比 interface 更灵活但不支持声明合并。本工具统一使用 interface 而非 type。

类型推断（Type Inference）

本工具根据 JSON value 的 typeof 和具体形式自动决定对应 TS 类型的过程。例如 typeof string 映射为 string，Array.isArray() 命中时按数组处理，typeof object 命中时生成独立子 interface。

可选字段（?）

TypeScript 中表示字段可缺省的修饰符。`name?: string` 表示 name 字段可不存在（值为 undefined）。开启本工具的「可选字段」选项后，值为 null 或 undefined 的字段会自动添加 `?`。

只读字段（readonly）

TypeScript 中表示字段不可变的修饰符。`readonly id: number` 表示 id 字段在对象创建后不能被重新赋值。开启本工具的「只读字段」选项后，所有字段会自动添加 `readonly`。

联合类型（Union Type）

TypeScript 中表示值可以是多种类型之一的语法，写作 `A | B`。本工具在数组元素类型不一致时使用，如 `(string | number)[]` 表示数组元素可能是 string 或 number。

数组类型（Array Type）

TypeScript 中表示数组的语法，有两种形式：泛型形式 `Array<T>` 和简写形式 `T[]`。本工具统一使用简写形式。本工具有三种数组类型生成模式：一致类型 `T[]`、混合类型 `(A | B)[]`、空数组 `any[]`。

嵌套接口（Nested Interface）

在 interface 中引用其他 interface 形成类型层级。本工具为每个嵌套对象生成独立子 interface，主 interface 通过属性名引用。如 Root 引用 RootAddress，RootAddress 可以独立被其他类型引用。

TypeScript strict 模式

TypeScript 编译器的严格模式，包含 noImplicitAny、strictNullChecks、strictFunctionTypes 等多个子选项。开启 strictNullChecks 后，null 和 undefined 是独立类型，不能赋给其他类型变量。本工具生成的可选字段与 strict 模式完全兼容。

DTO (Data Transfer Object)

数据传输对象，用于在不同层（如 API 与 Service 层）之间传递数据。在 TypeScript 项目中通常用 interface 描述，配合 readonly 强调不可变性。本工具是生成 DTO 类型定义的常用工具。

声明合并（Declaration Merging）

TypeScript interface 的特性：同名 interface 会自动合并属性。常用于扩展第三方库的类型定义。本工具生成的 interface 支持与项目中其他同名 interface 合并，便于渐进式类型扩展。

tsconfig.json

TypeScript 项目的配置文件，位于项目根目录。包含 compilerOptions（target、module、strict 等）、include、exclude 等设置。本工具生成的 .ts 文件可以放入任何标准 tsconfig 项目中使用。

tryFixJSON

本工具内置的 JSON 修复函数，会自动处理尾随逗号、单引号代替双引号、缺引号的 key、注释等常见 JSON 语法错误。在 JSON.parse 失败时自动调用，修复成功后会通知用户并继续转换。

JSON 类型到 TypeScript 类型的映射规则

本工具的 getTsType 函数根据 JSON value 的形式推断 TypeScript 类型的完整规则：

interface vs type 别名对比

本工具选择生成 interface 而非 type 别名的原因，以及两者在 TypeScript 项目中的差异：

可选字段与只读字段的生成规则

本工具的两个开关选项对生成代码的影响和最佳使用场景：

Privacy & Security

本 JSON 转 TypeScript 工具所有操作完全在你的浏览器本地完成：JSON 解析、类型推断、interface 生成全部通过浏览器 JavaScript 在客户端执行，不会通过网络向任何服务器发送 JSON 内容、上传的文件或生成的代码。文件上传使用浏览器原生 FileReader API 直接读取到内存，不经过任何中间服务。不使用 Cookie 追踪，不收集任何用户输入或使用数据。关闭或刷新页面后，所有输入和输出内容自动从内存清除。适合处理含 API 密钥、token、敏感业务数据的 JSON。

Authoritative References

• TypeScriptTypeScript interface 官方文档
• TypeScriptTypeScript 入门手册
• MDNJSON 规范 - MDN Web Docs
• TypeScriptTypeScript Playground 在线试用
• TypeScripttsconfig.json 配置参考
• ZodZod - TypeScript 优先的 schema 验证库