JSON转TypeScript类型

JSON 样本会变成哪些 TypeScript 声明

一段包含用户、标签和嵌套地址的 JSON，可以被整理为一个根类型以及若干关联类型。左侧输入必须是可解析的 JSON 文本；右侧会依据样本中的实际值生成 TypeScript。默认根类型名为 Root，默认输出 export interface，也可以切换为 type。对象字段、对象数组和嵌套对象会保留层级关系，普通数组则依据已有元素推断元素类型。

推断来自样本，而不是完整接口契约

生成结果回答的是“这份样本看起来像什么”，并不能证明接口今后只返回这些字段或这些值。样本里的 [1, "x", true, null] 会得到多成员联合类型；对象数组若第二项多出 note，该字段可能显示为 note?: string。相反，空数组没有元素可供判断，作为对象字段时会得到 any[]。只提供一个响应样本时，偶发为空、缺失或改变类型的字段很容易被漏掉，因此最好选取覆盖正常值、空值和可选字段的代表性数据。

日期时间也属于样本推断：符合常见时间格式的字符串可能显示为 Date。JSON 标准本身没有日期类型，解析后的原始值仍是字符串；项目若没有执行字符串到 Date 的转换，就应把生成类型改回 string，或者补充明确的转换步骤。

interface、type 与属性名的取舍

interface 和对象形式的 type 都能描述字段结构。默认接口适合常规对象模型；需要统一采用类型别名，或后续要组合联合类型、交叉类型时，可以开启“使用 type 而非 interface”。“优化属性名”会把类似 created_at、first-name 的键改成更符合 TypeScript 习惯的名称，但这只是生成声明中的命名变化，不会改写运行时 JSON。若代码直接读取原始对象，应关闭该选项或在数据进入业务层前完成字段映射。

从粘贴 JSON 到复制或下载类型

1. 准备有效样本

   从接口响应、测试夹具或配置中复制 JSON。先删除注释、尾随逗号和单引号写法；这些不是标准 JSON。敏感字段可保留结构但替换真实值。

2. 粘贴并检查语法

   把内容放入“JSON 输入”。需要统一缩进时点“格式化”；想恢复内置数据可点“示例”，清空按钮会移除当前输入。语法错误会显示错误信息，并暂时清空输出。

3. 设置根类型名称

   在“类型名称”中把 Root 改成业务可读名称，例如 UserResponse。请使用合法、清晰的 TypeScript 标识符。

4. 核对输出选项

   保持“仅类型定义”开启可得到精简声明；开启“使用 type 而非 interface”可改为类型别名。若确实需要解析与检查函数，应先关闭“仅类型定义”，再开启“运行时类型检查”，并核对新增代码是否符合项目约定。

5. 复制或下载

   检查可选字段、联合类型、日期和空数组后，复制代码，或下载以类型名称命名的 .ts 文件。接入项目后再运行类型检查和现有测试。

一组可复现的转换示例

输入下面的对象，并保持根类型名为 Root、默认接口输出：

{"id":42,"name":"Lin","roles":["admin","editor"],"profile":{"city":"杭州"}}

输出会包含根接口和嵌套的 Profile 接口：

export interface Root {
    id: number;
    name: string;
    roles: string[];
    profile: Profile;
}

export interface Profile {
    city: string;
}

对照测试可以把 roles 改为空数组：结果会变成 any[]，说明样本不足以确定元素类型。再把输入改为 {"rows":[{"id":1},{"id":2,"note":"ok"}]}，合并后的行类型会把 note 标为可选。

常见输入与结果问题

为什么一段看似正确的对象会提示 JSON 无效？

最常见原因是用了 JavaScript 对象字面量语法，而不是标准 JSON。键和字符串必须使用双引号，不能写注释、undefined、函数或尾随逗号；true、false、null 也必须小写。

空数组为什么无法得到具体元素类型？

因为 [] 没有任何元素可供推断。空数组作为对象字段时会生成 any[]；顶层只有空数组时可能没有可用声明。可加入一个脱敏的代表元素后重新生成，再按真实契约修订。

null 会被转换成 any 或可选属性吗？

不会直接这样处理。单独的 null 样本会保留为 null；同一字段在多个对象样本中同时出现字符串和空值时，可能得到 string | null。可选属性表示“键可能不存在”，与“键存在且值为 null”是两件事。

生成 interface 后，接口响应就会自动通过校验吗？

不会。仅生成 TypeScript 声明只影响静态类型检查，不会在运行时验证外部数据。需要运行时检查时，可以关闭“仅类型定义”并开启“运行时类型检查”生成相关函数，仍应结合项目测试确认错误处理和数据转换方式。

复制进项目之前要逐项复核

生成代码是对输入样本的推断稿，不是 API 契约、数据清洗或安全校验的替代品。

• 覆盖范围：一份样本无法展示所有状态。请根据接口文档补齐缺失字段、可选字段、分页结构、错误响应和版本差异。
• 运行时一致性：Date、优化后的属性名以及类型断言都不会自动改变原始 JSON；需要相应的解析或映射逻辑。
• 宽泛类型：any[] 通常意味着样本信息不足。发布前应替换为明确元素类型，或在确实未知时考虑 unknown[] 并执行收窄。
• 数值边界：JSON 只有统一的 number 语法，样本推断不会表达金额精度、超大整数约束或整数与小数的业务规则；这些约束应由接口文档和验证逻辑承担。
• 数据敏感性：转换在当前页面中完成，源 JSON 不作为转换请求提交；页面仍可能记录不含源文本的常规使用事件。即便如此，也应先移除令牌、密码、个人身份信息和生产数据中的秘密值。