把编辑器里的 API 验证变成 CI 门禁
文章区分了编辑器内人工参与的接口探索与 CLI 无人值守验证:前者适合确认响应结构,后者通过退出码阻断构建。两种场景应共用状态码、响应头和正文断言,避免校验标准分叉。
AI 深度解读
在 Cursor 里让 Agent 调一次接口,看到结果正常,能不能算验证完成?作者的回答是:足够验证眼前的猜想,却不足以守住后续改动。检查留在聊天记录里,下一次提交时不会自己再跑。
这篇讨论的是编辑器和 CLI 如何共用一套接口断言:人在编辑器里探索响应结构,再把检查保存成可重复执行的场景,由 CLI 在合并前执行。对经常让 AI 联调接口的开发者,最有用的是分清「这次成功了」和「以后出错能被拦住」。
编辑器里的成功,为什么还不算回归检查
作者对 API 验证的定义很具体:向真实接口发送请求,再检查响应是否符合断言。检查对象可以是状态码、响应头,也可以是响应体中的某个字段。
所以,看到一个 200 还不够。接口可能返回成功状态,却缺少下一步请求依赖的数据。真正需要固定下来的,是业务流程依赖的那些条件。
编辑器适合摸清这些条件。你可以看着 Agent 发请求、读响应,随时调整猜想,确认字段结构。但如果结果只存在于当前会话里,它就只是某一时刻的证据。没人再次发起检查,它不会发现后续变更。
CLI 改变的是执行方式。无界面运行器(headless runner)读取请求和断言,调用接口、比较结果,通过时返回退出码 0,失败时返回非零退出码。这样,检查就能在每次提交或定时任务中自动运行,也能接进合并前的流水线。
决定检查能否成为门禁的,是它能不能自动重跑,并让失败阻止合并。
只写一套断言,才能让两边得出同一个答案
作者建议把编辑器当作工作台,把 CLI 当作合并门禁。连接两者的,是同一个场景文件。
这里的「场景」,就是按顺序保存的一组请求,以及每一步需要满足的断言。它不只记录调用过哪个接口,还记录响应必须符合什么条件。
落地顺序也很清楚:先在编辑器里调用真实接口,确定状态码、关键响应头和后续请求依赖的字段;再把请求顺序和断言保存下来;最后让 CLI 执行同一场景,并把失败结果接入合并检查。
API 发生变化时,也只修改这一份场景,再分别确认交互执行和流水线执行的结果。否则,两套检查各自维护,很容易出现编辑器说通过、流水线却在验证另一套要求的情况。
原文用 Powerduck 说明这种设计:有序场景可以为每一步配置状态码、响应头和响应字段断言,通过 @powerduck/openapi-cli 的 runScenario 引擎在主进程中执行,支持取消,并能导出自包含 HTML 报告。
不过,原文没有提供具体命令、场景文件格式或接入配置。它说明了设计思路,还不足以让读者照着完成工具部署。
检查变成自动化,也可能稳定地检查错事
作者提醒了三个容易被忽略的问题。
第一,Agent 给出的绿色结论,不等于可重复的验证结果。只保留一句「接口正常」,却没有请求和断言,下一次就无法可靠复现。
第二,自动化也会固化错误理解。如果还没探索过真实 API,就先写好 CLI 检查,错误假设也可能被认真执行。编辑器的价值正是在这里:先理解接口,再决定该守住哪些条件。
第三,同一场景仍可能受环境影响。编辑器里已有的 token、base URL,未必存在于无界面 shell 中。作者建议两边使用一致的变量和凭据来源,并把缺少凭据归为配置错误,避免误判成接口行为失败。
还有一个边界:退出码 0 只说明已写出的断言通过了。没检查的字段、没覆盖的路径,仍然没有得到验证。使用 mock 跑通的场景,也需要对真实后端进行确认。
我的判断
我认同它把「探索」和「持续执行」分开的思路。AI 编程里,临时验证太容易停留在对话中;保存请求、顺序和断言,才能把一次联调积累成后续可用的检查。
但「编辑器里的检查不会重跑」有前提:检查确实只留在会话里。如果 Agent 已经生成并保存了测试,还把它接进 CI,那么持久性问题已经得到处理,入口是不是编辑器并不关键。
共享场景也不是某个产品独有的价值。已有脚本、接口测试集合或测试框架,只要能共用断言并返回可供流水线判断的结果,也能实现类似流程。选择工具时,更该看维护成本和环境一致性。
原文没有展示作者实测记录,也没有给出效率、误报率或漏检率的对照数据。Powerduck 的描述属于方案说明,不能据此认定它优于其他做法。
能拿来做什么
- 下次让 AI 联调接口时,把真正依赖的状态码、响应头和字段保存为可执行断言,让联调结果离开聊天记录。
- 对已有的关键请求链,先交互确认真实响应,再让同一场景通过 CLI 运行;确认失败能返回非零退出码后,再接入合并检查。
- 排查本地通过、流水线失败的问题时,先核对 token、base URL 和变量来源,单独识别配置缺失。
- 阅读自动化成功结果时,同时查看它覆盖了哪些断言;对没有检查的字段和路径,保留未验证的判断。