从「AI 写接口」到「AI 交付接口 + 文档 + 测试」
用 AI 写业务接口，现在已经很常见了。真正拉开差距的，往往不是「能不能生成代码」，而是交付物能不能一次性收齐：功能可用、文档可信、测试可跑、回归可重复。
这篇文章想讲的，是我们在实际项目里走完的这条路——以及为什么要走。
一、第一阶段：AI 开发功能，写接口
最早的用法很直接：
「帮我做一个某某能力，暴露一个 HTTP 接口。」
AI 会去读现有代码风格，补 Service、拼请求体、调 SDK / 查库，几轮对话后接口就能跑通。对开发者来说，这已经很爽：
- 少写样板代码
- 路由、入参、返回结构能对齐项目习惯
- 需求到可联调的时间明显缩短
但问题也很快暴露出来。
接口写完了，文档还在脑海里，或者事后随手贴一段假 JSON。
联调靠 Postman 点几下，没有沉淀成可复跑的测试。
过两周改字段，调用方问「现在到底返回什么」，只能再抓一次线上响应。
换句话说：AI 帮我们把「写接口」提速了，但交付标准还停留在「功能大概能用」。
二、缺的不是代码，是交付闭环
一次完整的接口交付，其实至少有四件事：
| 交付物 | 解决什么问题 |
|---|---|
| 功能 / 接口本身 | 业务能不能用 |
| 接口文档 | 别人怎么调、返回长什么样 |
| 测试类 | 预期行为有没有写下来 |
| 自动化跑通 | 改完能不能一键验证 |
只让 AI 写接口，等于只做了第一格。后面三格如果靠人肉补，AI 带来的效率红利会被「文档漂移 + 回归靠猜」吃掉。
更麻烦的是：手写文档很容易和真实返回不一致；「测过了」如果不能重复执行，下次改动仍然心虚。
所以目标应该升级成一句话：
让 AI 一次交付：功能 + 接口文档 + 测试类 + 可自动化执行的验证。
三、第二阶段：把文档和测试绑进同一条链路
做法的关键，不是再发明一个「文档生成器」或「测试框架」，而是约定：测接口的那一次真实请求，同时产出文档。
流程变成：
- AI 写功能接口（按项目现有 Service / 路由约定）
- AI 写测试类（不是只
System.out，而是断言 HTTP 成功、业务code、关键字段形状） - 跑测试类（对着本地或测试环境发真实请求）
- 同一次成功响应写进接口文档（参数表 + 真实示例 JSON，而不是手编样例）
这样有几个好处：
- 文档来自真响应：不会出现「文档写的是 A，线上返回是 B」
- 测试可重复：改字段、改分支，再跑一遍就知道有没有坏
- AI 有明确验收标准：不只是「代码写完了」，而是「Example 跑绿 + 文档落盘」
- 人和 AI 对齐同一套清单：少漏文档、少漏边界断言
可以把演进画成：
以前：需求 → AI 写接口 → 人肉联调 →（可选）事后补文档 现在：需求 → AI 写接口 + 测试类 → 自动化跑通（真请求） → 同步生成 / 更新接口文档 → 文档可信、回归可重复四、一次对话里，AI 应该交什么
当需求是「加一个某某 Open API」时，理想输出不再是「一个 Service 文件」，而是一整包：
接口实现
路由、入参校验、业务编排、错误路径说得清。接口文档
URL、参数说明、鉴权说明、真实成功响应示例；文档里的样例应来自实际调用，而不是 AI「想象」出来的 JSON。测试类
覆盖主路径；至少再带一个边界（空入参、不存在数据、幂等二次调用等）。断言要验结构，不只验「没抛异常」。自动化执行
测试类能一键跑；跑通即代表「当前环境上接口行为符合预期」，并顺带刷新文档。
开发者的角色，从「盯着 AI 一行行改代码」，变成「定需求与验收，让 AI 按闭环交付，自己做关键 review」。
五、实践里几条很管用的原则
1. 文档不要手抄假响应
假样例写得再漂亮，也会漂。用真实请求的成功响应生成文档，信任成本最低。
2. 测试不要停留在「能打印」
打印只证明「这次碰巧通了」。断言字段、状态、分支，才是把行为固化下来。
3. 把约定写成可复用的流程（Skill / 清单）
同一项目里，接口放哪、测试类叫什么、文档写到哪、怎么跑，都应固定。人和 AI 都按同一清单走，质量才稳定。
4. 一次对话要说清验收
与其只说「帮我写个接口」，不如说：「实现接口，补测试类，跑通后生成文档；主路径 + 一个失败/边界分支都要断言。」
六、小结
AI 写接口，解决的是「写得快」。
AI 同时交付文档、测试类，并能自动化跑通，解决的是「交得全、信得过、改得起」。
如果只用一句话概括这次升级：
从「AI 帮我把功能写出来」，升级到「AI 帮我把功能交出来」——带文档、带测试、可回归。
这不是多写两个文件的问题，而是把接口交付从「能联调」抬到「可维护」。后面再接新能力，默认就按这个标准要结果，效率和质量会一起上去。