从接口复制一段 JSON,丢进生成器,得到一份 interface——这只能算第一版。示例 JSON 只代表一次响应,真实接口里还有可选字段、空数组、null、联合类型和时间格式。下面这几件事决定生成出来的类型能不能直接用。
1. 示例里没有的字段,不代表不存在
如果接口文档说某个字段「可能不返回」,但示例里恰好有,生成器就会把它当成必填。更稳妥的做法是拿两三条不同状态的响应一起推断,或者生成后手动把可选字段改成 ?。可选字段不是「可有可无」,它会影响调用方是否需要判空。
2. 数组里对象的字段合并
一个数组里有多个对象时,生成器会合并所有出现过的键;只在部分元素里出现的键标记为可选。这个策略适合列表接口,但要注意:如果某个字段在某条数据里是 null,它会被推断成 T | null,而不是可选。两者在类型层面不同,调用方要分别处理。
3. null、空数组和 unknown
空数组无法推断元素类型,通常会得到 unknown[] 或 never[];空对象会得到 {}。这些结果不是错,但需要你根据接口契约补上真实类型。不要为了「让类型通过」把空数组改成 any[],那会把问题推迟到运行时。
4. 数字、日期和大整数
JSON 没有日期类型,时间通常以 ISO 字符串或 Unix 时间戳返回。生成器只能给出 string 或 number,业务层最好再包一层 Date 转换或品牌类型。超过 2^53 - 1 的整数在 JSON 解析阶段就可能丢精度,订单号、雪花 ID 应该让后端以字符串返回。
5. 字面量和联合类型要手动补
status: "paid" 在示例里只是一个字符串,但业务上它可能是 "pending" | "paid" | "refunded"。生成器不会知道枚举范围,生成后把状态、类型、角色这类字段改成字面量联合,能提前发现拼写错误。同理,固定结构可以用 readonly 或 as const 收窄。
一个够用的流程
- 用两三条真实响应(脱敏后)一起生成;
- 把可选字段、null 和联合类型对照接口文档修一遍;
- 给日期、金额、ID 加上业务类型或注释;
- 把生成的类型放进项目,跑一次
tsc --noEmit; - 接口变更时,重新生成并对比 diff,而不是手改到面目全非。
可以直接用 JSON 转 TypeScript 生成第一版,再用 JSON 格式化 检查输入是否合法。