JSON 转 TypeScript 接口：告别手写类型定义，自动生成

为什么要从 JSON 生成类型？

编译期发现字段拼写错误、null 访问和类型不匹配，减少 runtime 白屏。

OpenAPI 若缺失或不准确，一份真实响应 JSON 往往是最可靠的契约来源。

类型与样例同步更新，Code Review 时能 diff 出 API 变更影响。

手工推断：最小示例

观察 JSON 结构：对象 → interface，数组 → T[]，null 与缺失需决定是否可选。

{
  "id": 1001,
  "name": "Alice",
  "email": null,
  "tags": ["vip", "beta"]
}

interface User {
  id: number;
  name: string;
  email: string | null;
  tags: string[];
}

生成器如何处理嵌套与数组？

嵌套对象通常生成独立 interface 或 inline 类型；数组取首个元素推断元素类型。

空数组 [] 无法推断元素类型，需人工改为 unknown[] 或补充样例。

多态数组（元素形状不同）会生成联合类型 A | B。

{
  "items": [
    { "type": "book", "isbn": "978-3" },
    { "type": "food", "calories": 120 }
  ]
}

可选属性 vs null

JSON 中「字段缺失」与「字段为 null」语义不同：可选常用 email?: string，可空常用 email: string | null。

生成工具默认策略各异；对接 API 时应与后端约定 null 含义，再调整生成选项。

常用工具与命令

quicktype：支持 JSON → TS，可命名根类型、readonly、可选处理。

json-schema-to-typescript：若已有 JSON Schema，从 schema 生成更稳。

在线 json2ts 站点：粘贴即用，适合一次性接口；大项目建议 CLI 进仓库脚本。

# quicktype 示例（需安装 quicktype）
# npx quicktype sample.json -o types.ts --lang typescript

生成后的最佳实践

不要把生成文件手改到无法重新生成——自定义逻辑放在 wrapper 类型或 mapper 函数。

用多个样例（含边界 case）跑生成，合并或取 union，避免单一 happy path 误导。

配合 zod / io-ts 做 runtime 校验时，可从同一 JSON Schema 双向生成。

每次 API 版本升级：更新样例 → 重新生成 → 让 TypeScript 编译暴露 breaking changes。