如何利用多样本 API 返回值推导准确的 TypeScript 接口定义

1. 什么是多样本 TypeScript 接口推导？

TypeScript 接口定义是前端全栈类型安全的基础。然而，如果仅根据单条静态 JSON API 响应推导 TS 类型，往往会在生产环境中引发隐蔽的类型崩溃。

单条 JSON 样本无法揭示条件出现的字段（例如仅管理员可见的属性），也无法捕获在不同业务状态下返回 null 或其他类型的数据字段。

2. 单样本工具的缺陷

1. 漏标可选属性 (`?`)：单条样本中存在的字段会被强行声明为必填项，导致前端访问未返回的属性时抛出 TypeError: Cannot read property of undefined。
2. 缺失联合类型 (Union Types)：样本 1 中返回 string、样本 2 中返回 null 的字段会被硬编码为单一类型。
3. 空数组退化：遇到 "items": [] 时，生成器只能无奈降级为 any[] 或 never[]。

3. 多样本合并推导算法

当提供 2 份或以上代表不同业务状态的 JSON 样本时，推导引擎会执行以下合并逻辑：

1. 字段频次统计：若某个属性存在于样本 1 但缺失于样本 2，自动为其标注可选符号（key?: Type）。
2. 类型冲突归纳：若样本 1 字段为 string，样本 2 为 null，自动归纳为联合类型：string | null。
3. 递归嵌套合并：对嵌套子对象进行深度递归合并，确保保留所有样本中的完整属性。

// 根据多份 API 样本自动推导的 TypeScript 规范接口：
export interface UserProfile {
    id: number;
    username: string;
    email?: string | null; // 多样本对比推导出的可选且可空字段！
    roles: string[];
    bio?: string;
}

4. 常见问题解答 (FAQ)

Q1: 为什么单样本 JSON 转 TS 工具在生产环境中容易出 Bug？

因为单条 API 响应只代表特定用户或特定状态下的一个快照。某些可选字段或边缘状态下返回的 null 值不会出现在该快照中，前端代码按强类型访问时即会发生运行时空指针报错。

Q2: 工具是如何判断某个属性是否应该带问号 (?) 的？

只要某个属性 Key 在您提供的多份 JSON 样本中未全勤出现（且勾选了“智能推导可选属性”选项），工具就会在生成的 Interface 属性名后自动追加 ?。

Q3: 可以自定义根接口名称和空数组退化类型吗？

可以！您可以在页面上方自定义 Root Interface 名称（如 ApiResponse），并将空数组的默认退化类型指定为 unknown[] 或 any[]。