JSON 转 TypeScript 详解：从数据反推类型
为什么要从 JSON 生成类型
前后端分离架构里，后端 API 返回 JSON，前端要用 TypeScript 消费它。手写接口定义（interface）枯燥易错——字段名拼写错、类型标错、嵌套漏掉都是常态。JSON 转 TS 工具直接拿一份示例 JSON，反推出对应的 TypeScript 接口定义，省去手写，且保证字段名和结构与实际响应一致。
这在”后端没给类型文档、只有接口示例”的场景特别有用：抓一份真实响应，转成类型，立刻就有类型安全的消费代码。
类型推断的基本规则
转换器遍历 JSON 树，按节点类型映射：
| JSON 类型 | TS 类型 |
|---|---|
| 字符串 | string |
| 数字 | number |
| 布尔 | boolean |
| null | null |
| 数组 | T[]（元素类型递归推断） |
| 对象 | interface 或内联类型 |
| 缺省/不确定 | any 或 unknown |
字符串有时还能细化：长得像日期的（2026-06-17）有的工具标 string，有的标 Date——这是约定，标准做法是保守地标 string，让用户按需调。
数组的处理是关键：推断元素类型时，转换器会扫描所有元素取它们的”公共类型”。如果数组元素都是同构对象，合并出一个 interface；如果元素类型不一，可能产出联合类型。
多样本合并：从单例到通用类型
单条 JSON 反推的类型有个根本问题：它只见过这一个样本。比如：
{ "name": "张三", "age": 30 }
推断出 { name: string; age: number }。但真实数据里可能有的记录 age 缺失、有的 name 是 null。单样本推断会把字段都标成必填，实际可能该是可选。
高质量转换器支持多样本合并——喂多条 JSON，合并出更通用的类型：
- 某字段只在部分样本出现 → 标可选（
age?: number） - 某字段类型在不同样本不同 → 联合类型（
name: string | null） - 数组元素跨样本结构不同 → 元素类型取并集
多样本合并的算法核心是对每个字段做类型集合的合并，类似 TypeScript 自身的类型收窄逻辑。这是把”示例数据”变成”靠谱类型定义”的关键一步。
联合类型与字面量
当字段值是固定的几个字符串（如 "active" | "inactive" | "banned"），好的转换器会识别成字符串字面量联合类型而非宽泛的 string——这对状态字段很有用，能利用 TS 的穷举检查。但这需要多样本支撑，单样本看不出来。
数值字面量同理。是否做字面量推断是工具质量的分水岭：低端的全部标 string/number，高端的识别枚举式值。
嵌套与命名
JSON 往往深嵌套，转换器要给嵌套对象起名：
- 策略一：每个嵌套对象生成独立 interface，按字段名派生命名（如
user字段 →User接口）。输出清晰、可复用 - 策略二：嵌套对象用内联类型，不命名。输出紧凑但重复时啰嗦
- 数组元素：通常按字段名单数化命名（
users: User[]→ 元素类型User）
命名质量影响生成代码的可读性。好工具会处理单复数、避免命名冲突、对根对象给个合理名字。
转换的局限
从 JSON 反推类型有先天局限，要清醒认识：
1. 单样本必失真
单条 JSON 永远看不出”哪些字段可选""哪些是联合类型”。生成的类型把所有字段标必填、类型固定，与真实 API 的类型契约可能有出入。多样本是缓解，但仍可能漏掉罕见分支。
2. 无法区分 number 的细分
JSON 只有 number，但 TS 里 price 可能该是更精确的类型。JSON 转换器无从得知，统一标 number。
3. 字符串格式信息丢失
ISO 日期、UUID、邮箱在 JSON 里都是 string，转换器不知道语义，标 string。要 Brand<string, 'UUID'> 这类品牌类型得手工加。
4. 不能发现约束
字段值范围、正则约束、枚举完整性，JSON 示例体现不了。age: number 推断不出”必须 0~150”。
5. null vs undefined
JSON 有 null 无 undefined，但 TS 里”字段缺失”和”字段为 null”是两回事。转换器对 null 的处理（标 null 还是 T | null 还是可选）需要约定，容易和实际语义不符。
真正的源头：JSON Schema / OpenAPI
归根结底，JSON 是数据实例，不是类型定义。最可靠的类型来源是 API 的 OpenAPI/Swagger 规范或 JSON Schema——它们本来就是描述类型的，字段可选性、格式、约束都明确。从 OpenAPI 生成 TS 类型，比从 JSON 示例反推准确得多。
JSON 转 TS 的定位是”没有规范文档时的快捷手段”——快速从示例得到一个能用的类型骨架，再人工修正。它替代不了正式的类型契约，但在”先跑起来”的阶段极其高效。
实用建议
- 用真实响应而非手写示例做输入，避免漏字段
- 尽量喂多条样本，让合并更准
- 生成后人工审一遍：可选字段、联合类型、命名是否合理
- 把生成的类型当起点而非终点，按业务知识补约束（字面量联合、可选、品牌类型）
- 后端有 OpenAPI 的话，优先从规范生成
小结
JSON 转 TS 通过遍历 JSON 树反推类型，单样本会失真（字段都必填、类型固定），多样本合并能识别可选和联合类型，但仍有约束、格式、null 语义等局限。它的价值是”无文档时快速起类型骨架”，准确类型的正道仍是 OpenAPI/JSON Schema。把它当高效起点，配合人工修正和 [[json-format]] 校验输入，能在前后端联调里省大量手写类型的功夫。