JSON 转 TypeScript 类型与 Zod Schema

怎么用

1. 把 JSON 样本粘贴到左侧。样本越完整越好：数组里放几条不同的记录，能让工具看出哪些字段是可选的。
2. 填写根类型的名称，例如 User、OrderResponse。
3. 选择输出 TypeScript 接口还是 Zod schema。结果实时出现在右侧，可以复制或下载成 .ts 文件。
4. 检查推断结果，特别是值为 null 或空数组的字段，按实际情况补全类型。

推断规则

基本类型与嵌套

JSON 的字符串、数字、true 或 false、null 分别对应 TypeScript 的 string、number、boolean、null。嵌套对象会生成单独的接口，名字取自键名并转成大驼峰：owner 对应 Owner。数组元素的接口名取单数：items 对应 Item，categories 对应 Category，boxes 对应 Box；以 ss、us 结尾的词（例如 status）保持不变。

合并数组里的对象

接口返回的数组里，经常是有的记录带某个字段、有的不带。工具会把数组里的所有对象合并成一个接口：所有元素都有的字段是必填，只在部分元素里出现的字段按 TypeScript 的写法在名字后加问号，标成可选。同一个字段在不同记录里类型不同时生成联合类型，例如 qty 有时是数字、有时是 null，就写成 number | null；数组元素类型混杂时写成 (number | string)[]。

命名冲突与复用

结构完全相同的对象复用同一个接口，不会生成一堆一样的定义。不同位置出现了同名但结构不同的对象，第二个会加数字后缀，例如 User 和 User2，生成后可以按业务含义改名。键名不是合法的 JavaScript 标识符时（例如 first-name、2fa）会加上引号。

Zod schema

选择 Zod 时，每个接口都生成一个 z.object，可选字段加 .optional()，被引用的 schema 先定义、再被使用；最后一行用 z.infer 从 schema 推出同名类型，这样类型和运行时校验只需要维护一份。使用前需要在项目里安装 zod。

示例

载入示例后，根类型填 User，得到：

export interface User {
  id: number;
  name: string;
  email: null;
  roles: string[];
  orders: Order[];
}

export interface Order {
  id: number;
  total: number;
  items: Item[];
  coupon?: string;
}

export interface Item {
  sku: string;
  qty: number;
}

两条订单里只有第二条有 coupon，所以它是可选的；第二条订单的 items 是空数组，和第一条合并后仍然是 Item[]。email 在样本里只出现了 null，工具只能推断成 null，实际上它多半应该是 string | null，这正是需要人工检查的地方。

局限

• 只能从样本推断。样本里没出现的字段、没出现过的取值类型，推断结果里都没有。
• 值为 null 的字段只能推断成 null，只有空数组的字段只能推断成 unknown[]，需要手动补全。
• 不会识别日期、枚举、字符串格式："2026-09-30" 只会是 string，"admin" 不会变成字面量类型。
• 超过 2^53 的整数在 JavaScript 里会丢精度，类型仍是 number；如果接口用字符串传大整数，样本里也会是 string。

参考资料

• TypeScript Handbook：Object Types（可选属性）
• Zod：Basic usage（z.infer）
• Zod：API（optional）