用 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 帮我把功能交出来」——带文档、带测试、可回归。这不是多写两个文件的问题而是把接口交付从「能联调」抬到「可维护」。后面再接新能力默认就按这个标准要结果效率和质量会一起上去。