接口文档永远是烂尾工程，我让AI把这份债收了
一个管理者的老问题
带过团队的人大概都经历过这样的对话：
第三方接口联调前，前端问后端：“这个字段是什么类型？可为空吗？"后端翻出对接文档，发现文档是三个月前写的，接口早就改了三版。于是后端去抓包，把真实返回贴到群里，前端对着一段 JSON 猜类型。
JSON 样例人人都有，类型定义人人都在猜。这就是接口协作中最常见的烂尾工程：文档欠的债，永远由联调现场来还。
我们是个十人左右的小团队，做的是多端产品，一份接口返回要在 Web、小程序、客户端三端各写一遍类型。每次接口变更，三端类型同步就是一场拉锯战。而当 TypeScript 项目越来越多，“手写类型”这件事的人力成本开始变得刺眼——不是因为难，而是因为重复、琐碎、易错。
AI 在这件事上能做什么
后来我们把这件事交给 AI 处理，流程很简单，但效果远超预期。AI 能覆盖的环节包括：
- 从 JSON 样例反推完整的类型定义，包括嵌套对象、联合类型、可空字段；
- 识别“样例里看不出来但实际可能变”的字段，比如样例里
remark是null，AI 会建议标为string | null而不是直接断言null； - 生成多语言版本——一份样例，同时产出 TypeScript interface、Kotlin data class、Swift struct；
- 附带类型守卫函数和注释，方便运行时校验和新人理解字段含义。
对管理者来说，最关键的一点是：它把“猜类型”这件依赖个人经验的事，变成了一个可复制的标准流程。谁来做，产出质量都稳定在同一水平线。
我们的标准化流程
现在团队的规定是：任何新接口接入，后端提供真实返回样例，前端不手写类型，统一走 AI 生成流程：
第一步，采样。 后端从测试环境拿真实返回，最好是能覆盖不同状态的多个样例（正常数据、空列表、含 null 的记录）。
第二步，投喂。 把样例连同字段说明一起交给 AI，用统一提示词模板（见下文），明确输出格式和命名规范。
第三步，审查。 前端花两三分钟核对 AI 产出的类型——重点看联合类型和可选字段的推断是否合理。这一步不能省，AI 推断错一个可空字段，运行时就是一个空指针。
第四步，入库。 类型文件进版本库，字段注释保留，作为团队共享的“活文档”。
可复制的提示词模板
这是我们团队内部用的模板，直接替换样例部分即可：
你是一名资深后端工程师。请根据下面的接口返回 JSON 样例，反推 TypeScript 类型定义。
要求：
1. 输出 interface 定义，字段名保持与 JSON 一致，命名采用 camelCase；
2. 样例中出现 null 的字段，标注为「类型 | null」，不要直接断言为 null；
3. 根据字段语义推断可选性：样例中缺失但业务上可能存在的字段，标为可选（?）并在注释中说明假设；
4. 对每个字段添加中文注释，说明推断依据（来自样例值还是业务常识）；
5. 额外输出一个类型守卫函数 isXxx(data: unknown): data is Xxx，用于运行时校验；
6. 最后列出你不确定的字段清单，标注需要人工确认的问题。
接口名称：获取用户订单详情
JSON 样例：
{
"code": 0,
"data": {
"orderId": "A20240601001",
"amount": 199.00,
"status": "PAID",
"remark": null,
"items": [
{ "skuId": 8821, "title": "无线鼠标", "qty": 2 }
]
}
}第 6 条是我们加的关键约束：让 AI 主动交代它不确定的地方。这等于把审查清单也一并生成出来了，前端核对时优先看这些点，效率高很多。如果需要 Kotlin 或 Swift 版本，把第 5、6 条保留，指定输出语言即可。
前后对比
流程上： 以前一个中等复杂度的接口（二十多个字段、三层嵌套），前端手写类型加核对大约四十分钟到一小时，三端各写一遍就是半天人力。现在采样加生成加审查，单端十分钟以内，三端类型一次生成。更重要的是，这个过程不再依赖“团队里最熟悉这个接口的那个人”。
质量上： 手写类型的错误率反而更高。人容易照着单一样例“抄类型”，样例里 remark 是 null 就写成 null，上线后接口返回了字符串，直接报错。AI 在提示词约束下会主动推断联合类型和可选性，还会列出不确定字段。上线后由类型不匹配引起的联调返工，在我们团队基本消失了。
协作上： 最大的变化是责任边界清晰了。后端只负责提供真实样例，前端只负责审查确认，产出物进版本库、可追溯。接口变更时重新跑一遍流程即可，类型文件本身就是最新的接口文档。原来散在聊天记录里的抓包 JSON,现在都有了对口的类型定义沉淀下来。
风险控制上： 有两点必须提醒。第一，AI 产出必须有人审查，尤其是可选性和联合类型的推断——AI 没见过接口的全部状态，样例之外的情况它只能猜，而猜的部分必须人来拍板。第二，提示词模板里不要粘贴包含真实用户数据的样例，采样时先做脱敏，这是团队使用 AI 工具的基本纪律。
几点管理上的建议
- 把提示词模板固化成团队资产，放在共享文档里，不允许各写各的；
- 类型文件进版本库并要求 code review,把 AI 产出纳入正常的工程流程而非游离在外；
- 定期抽查 AI 推断的“不确定字段清单”的确认记录，保证审查环节没有流于形式；
- 模型调用产生的费用属常规工具开支，具体以官网价格页为准，按项目归口统计即可。
这类“AI 替代重复劳动”的场景，投入极小、回报立竿见影，非常适合作为小团队建立 AI 工作习惯的第一步。如果你想在统一入口下管理这类模型调用、按项目管控用量，可以了解一下 https://api.thistoken.ai/register,注册即可开始体验。
---
本文的示例只需一个 API Key 就能复现：在 https://api.thistoken.ai/register 注册即用。