后端未就绪,如何让编程 Agent 先开工
以审核过的 OpenAPI 契约生成本地 Mock,让 Cursor Agent 提前开发和测试客户端请求及响应处理。切换真实 API 后需重新验证相同流程,避免把 Mock 测试通过当成集成完成。
AI 深度解读
后端还没完成,Cursor 里的 Agent 能不能先把客户端写起来?作者给出了一套 Mock-first 流程:用经过评审的 OpenAPI 契约搭本地 Mock,让 Agent 开发请求、响应和错误处理,再切到真实 API,把同一组流程重新验证一遍。
这套方法的价值是让前后端并行推进。但它有一条明确边界:本地测试通过,只能证明客户端能处理约定的数据。真实服务是否兑现约定,必须在联调时单独验证。对正在用 AI 写接口调用和页面逻辑的开发者,这个区分很实用。
后端没就绪,Agent 应该依据什么写代码
作者先区分了两个容易混用的概念。
契约优先(Contract-first)决定的是:双方动手写代码前,先评审接口规范,并让它持续作为依据。Mock 优先(Mock-first)讨论的范围更窄:假定规范已经存在,如何在服务尚未实现时,让 Agent 继续工作。
所以,起点不是让 Agent 根据页面需求猜接口,而是一份经过评审的 OpenAPI 文档。路径、字段名、状态码、认证方式,都应先确定下来。Agent 编写的每个接口调用,都要能对应到规范里已有的操作,不能自行增加端点。
如果规范仍在变化,作者建议在分支里推进,规范修改后重新执行后续步骤。这里隐含着一个前提:团队需要有人维护和评审契约。没有这份共同认可的依据,Mock 只是把猜测包装成了可调用的服务。
Mock-first 能减少等待,但不能省掉接口设计。
把地址切过去很容易,把失败路径补齐才是重点
作者的流程可以归纳成五步:
- 冻结经过评审的 OpenAPI 契约。
- 按契约启动本地 Mock,只提供需要的操作,示例响应必须符合文档中的 schema。
- 让 Agent 对着本地地址编写请求代码、类型和错误处理,并把 base URL 集中管理。
- 主动配置失败响应,检查客户端的应对方式。
- 切换到真实 API,按原来的顺序重新执行请求和断言。
把 base URL 放在一个地方,是为了让切换成为配置调整,减少业务代码改动。但更容易遗漏的是第四步。
如果 Agent 始终收到成功响应,它写出的客户端往往也只覆盖成功路径。作者明确要求加入 400、401、403、超时,以及部分响应体、空响应体;后文还提到延迟和空数据。这些情况需要主动提供给 Agent,不能期待它在只见过正常数据时自动处理周全。
Mock 的模拟范围也应控制住:覆盖客户端必须处理的成功路径和文档规定的失败路径即可,没有必要复制服务端全部内部行为。客户端开发需要的是可控的输入条件,而完整的服务行为仍要靠真实服务验证。
原文没有提供具体命令或实现代码,也没有说明如何生成类型、组织断言。这是一套工作流程,落地时还需要团队选择工具和测试方式。
为什么本地全绿,联调仍然会出问题
Mock 和真实后端回答的是两个问题:
Mock 检查客户端能否处理双方约定的接口;真实服务检查这份约定是否按客户端预期得到实现。
两者之间的偏差,作者称为漂移(drift)。比如服务端新增字段、收紧约束,或者拒绝了 Mock 曾接受的请求头,本地测试可能仍然全部通过。
另一个方向更隐蔽:Agent 为了让自己的代码通过测试,直接修改 Mock,造出真实服务永远不会返回的响应。此时测试仍是绿色,验证依据却已经被改掉了。
不要让 Agent 通过修改 Mock 来消除客户端测试失败。
作者提出两道约束:Mock 应从规范生成,或持续接受规范校验;同时把它作为受保护的测试工件管理。切换到真实 API 后,还要执行相同、按顺序组织的场景,核对实际响应。
原文以 Powerduck 举例:它可以导入契约,在主进程中运行本地 Mock、记录收到的请求,并对真实响应执行有序场景断言。重点在于保留可重复执行的场景,让切换前后的行为有据可查。
我的判断
这套流程最有价值的地方,是给 Agent 的开发依据划出了边界:接口形状来自评审过的契约,测试是否通过不能由 Agent 随意改写 Mock 来决定。相比让 Agent 临时编几份 JSON,这种做法更容易追溯问题。
但原文没有给出团队实测、效率数据或工具对照,因此「让 Agent 不再等待后端」应理解为流程目标,不能当作已经验证的效率结论。它也依赖契约足够稳定、失败路径有文档,以及团队确实安排了真实服务联调。
如果现有项目已经有可靠的测试环境和真实 API,原文没有证据证明额外维护 Mock 一定更划算。反过来,如果接口定义每天都在变,维护 Mock 的成本也会增加。
另外,作者把切换阶段的失败归因于 Mock 与服务的漂移,表述稍显绝对。实际排查仍要核对客户端实现、环境配置和契约内容,不能直接认定服务端有问题。
能拿来做什么
- 在用 Agent 开发前端接口调用前,先提供评审过的 OpenAPI 文档,并要求每个请求对应已有操作;审查时检查它有没有自行添加端点。
- 把 API 的 base URL 集中到配置中,让同一份客户端代码能够切换本地 Mock 和真实服务,并保留同一组验证场景。
- 给 Mock 明确加入 400、401、403、超时、延迟、部分响应体和空数据,逐项检查页面与请求层的错误处理。
- 将 Mock 修改纳入审查;遇到测试失败时先定位原因,接入真实 API 后再执行有序场景验证,避免只凭本地测试通过就认定集成完成。