后端没空写文档？我们让AI从接口返回样例里「长」出类型定义
一个管理者的尴尬时刻
带过小团队的人大概都遇到过这样的场景：前端同事在群里@后端，「这个接口的 data 字段里到底有什么？」后端回一句「你看下返回样例就知道了」。然后前端对着一份截图，手写了二十分钟类型定义，三天后联调时发现漏了一个嵌套字段，返工。
这不是谁的错，是流程的错。接口文档永远滞后于代码，类型定义散落在各端各自维护，等出问题的时候，谁也说不清哪份是「对的」。作为管理者，我看到的风险有三层：
- 协作风险：前后端各自猜字段，联调期反复返工，时间都在这消耗掉了；
- 质量风险：手写类型容易漏可选字段、误判 null,线上跑起来才炸；
- 合规风险：接口里有敏感字段(手机号、内部 ID)时，没人能快速盘点「这个接口到底吐了哪些数据」。
后来我们把这件事交给 AI:把接口返回样例丢给它，让它反推出完整的类型定义。三个月下来，这套流程成了团队联调前的标准动作。
AI 在这件事上到底能做什么
先说清楚 AI 的角色定位：它不是替你写接口的人，而是替你做「样例 → 类型」这层机械翻译的人。具体能做四件事：
第一，从 JSON 样例反推结构化类型。 无论你要 TypeScript interface、JSON Schema 还是 Go struct,它都能从一份返回样例里推导出字段名、层级关系，并生成可编译的代码。
第二，标注不确定的地方。 好的提示词会让 AI 明确说出「这个字段在样例里是 null,我无法确定是 string | null 还是嵌套对象」，而不是默默猜一个。这是风险控制的关键——AI 猜错了不要紧，要紧的是它得告诉你它不确定。
第三，统一团队的类型规范。 命名风格、注释格式、是否生成 mock 数据，都可以在提示词里固化下来。新人来了不用读文档，拿模板直接跑。
第四，做交叉校验。 让 AI 拿着后端实际返回和新类型定义互相对照，找出「样例里有但类型里没有」的字段——这一步专门治「文档滞后」。
我们的落地流程
管理者最关心的不是 demo 多炫，而是流程能不能固化。我们最后收敛成四步：
- 采集样例：后端在预发环境跑一次真实请求，导出 JSON 返回(脱敏后)贴进共享文档。谁都可以贴，不依赖特定的人。
- AI 反推类型：用统一的提示词模板生成 TypeScript 类型定义，附不确定字段清单。
- 人工确认灰区：后端只看 AI 标出的不确定点，30 秒确认一次。注意，人的职责从「写类型」变成了「审类型」，工作量降了一个量级。
- 入库与对比：类型文件进前端仓库，后续接口变更时重跑一次，diff 结果就是接口变更清单——顺便把「接口悄悄改了没人通知」这个老大难也解决了。
可复制的提示词模板
这是我们团队模板的简化版，直接可用：
你是一名资深后端工程师,请根据下面的接口返回 JSON 样例,反推 TypeScript 类型定义。
要求:
1. 为顶层对象命名为 {InterfaceName},嵌套对象单独定义 interface,命名使用 PascalCase;
2. 字段类型从样例推导,无法从单条样例确定的(如空数组、null),不要猜测,
放入「不确定字段清单」,并给出 2 种最可能的类型假设;
3. 疑似日期、枚举、ID 的字段,用注释说明判断依据;
4. 敏感字段(手机号、邮箱、内部ID 等)加 @sensitive 注释;
5. 输出顺序:①类型定义代码 ②不确定字段清单 ③建议向后端确认的问题列表。
接口名:{InterfaceName}
JSON 样例:
{paste_json_here}第 2 条和第 5 条是精华：强制 AI 暴露不确定性，把「猜测」变成「提问」，管理者才有办法做复核。
用 AI 前后对比
之前： 前端拿截图手写类型，平均 15~30 分钟一个接口；复杂嵌套接口经常漏字段，联调时返工；接口悄悄变更没人知道，线上才暴露；敏感字段靠人肉翻查，从未系统盘点过。
之后： 样例贴进去，10 秒出类型 + 不确定清单；后端确认灰区平均不到 1 分钟；接口变更靠重跑 diff 自动发现；敏感字段清单自动生成，安全盘点有了抓手。
粗算下来，单个接口从「半小时 + 联调返工」降到「两分钟 + 一次确认」。更重要的是，这个流程不依赖任何人的经验——提示词模板放在团队库里，谁来执行结果都一致。对管理者来说，这叫可复制的流程；对人来说，这叫可以放心休假。
几点管理层面的提醒
- 样例必须脱敏：真实用户数据不要直接喂给外部模型，先做字段打码，这条要写进流程，不能靠自觉。
- AI 输出必须过一次人眼：尤其是不确定清单，这一分钟的复核是整个流程的安全阀。
- 成本可控：这类任务用主流模型绰绰有余，具体价格以官网价格页为准，单个接口的消耗几乎可以忽略。
最后说句实在的：这类「把 AI 接进日常流程」的能力，前提是你有一个稳定可用的模型 API 通道。我们在用的是 https://api.thistoken.ai/register,注册即用，感兴趣可以试试，把这套流程在你自己团队里跑起来。
---
本文的示例只需一个 API Key 就能复现：在 https://api.thistoken.ai/register 注册即用。