AI 手写 API 客户端何时该换成 SDK
文章比较 Cursor 按任务编写的 HTTP 调用代码与持续维护的 SDK,涉及接口覆盖、类型、重试和认证等差异。建议少量临时调用使用轻量客户端,长期多接口项目优先评估 SDK,并提醒模型可能编造路径或字段。
AI 深度解读
Cursor 几秒钟写出的 API 请求代码,能不能替代官方 SDK?作者的答案取决于接入范围:临时脚本、少量接口可以用轻量客户端;长期维护、多人协作、调用大量接口的产品,更适合维护中的 SDK。
这篇最有用的提醒,是把「代码生成得快」和「接口接入可靠」分开。真正要比较的,是接口依据从哪来、异常由谁处理,以及 API 变化后谁负责更新。
Cursor 写出的客户端,不会自动跟着 API 更新
这里的「Cursor-generated HTTP client」,指模型为当前任务编写的普通 fetch 或 axios 代码:拼请求、发送请求、解析响应,然后保存在项目仓库里。
它不是通过固定工具生成、可以重复构建的客户端产物。没有独立构建步骤,也没有重新生成命令。你让它接几个接口,它通常就覆盖这几个接口,后续跟着业务代码一起维护。
模型写出了请求函数,不代表建立了接口更新机制。
代码的可靠程度,还取决于模型拿到了什么。作者区分了三种依据:当前打开的 OpenAPI 文件、上下文里的文档,以及模型已有的训练知识。最后一种最需要警惕,因为看起来合理的路径和字段名,也可能根本不存在。
作者提供的折中方案很实用:把实际使用的 OpenAPI 文件放进仓库,让模型依据它编写客户端。至少路径和数据结构有了可检查、可比较差异的来源。不过,合同文件更新后,已有调用仍然需要人工修改。
真正拉开差距的是异常处理和维护成本
作者列出的失败方式并不神秘:接口路径写错、字段凭空出现、token 硬编码、认证方式猜错,或者把嵌套错误直接压成一个普通异常。
更隐蔽的问题是响应变化。服务端调整了返回结构,客户端可能依然能编译,却在运行时处理不了新数据。一次请求成功,只能证明那一次成功路径走通了,覆盖不了 401、403、超时和格式错误的响应体。
因此,无论选哪一种客户端,都要连接真实服务验证。
原文提到 Powerduck 可以导入 OpenAPI,通过本地主进程执行有顺序的场景断言,检查状态码和响应字段。作者同时强调,AI review 只能提示可疑之处,不能证明代码正确。原文没有提供这套工具与其他测试方式的对照结果,它应被看作一种验证路径。
SDK 的价值,则是把类型、重试、认证、取消请求等公共机制集中维护。当多个团队调用大量接口时,统一 token 刷新和错误处理,比每处调用各写一套更容易控制。
但 SDK 也会失去维护、落后于线上 API,或者带来较大的包体积。作者建议检查维护状态,固定经过验证的版本,并关注 changelog。若 SDK 已经过时,依据当前合同编写的轻量客户端反而可能更可靠。
我的判断
我赞同作者用「接口范围和维护周期」做选择依据。只比较有没有额外依赖,会漏掉后续修改、排查异常和统一行为的成本。
不过,原文把维护中的 SDK 描述成覆盖完整合同、附带各种公共能力,这个前提需要逐项核实。不能仅凭 SDK 这个名称,就认定它一定支持重试、取消和 token 刷新;文章没有针对具体 SDK 做能力验证,也没有给出两种方案的故障率或维护工时对照。它提供的是工程经验,不是性能或可靠性的实验结论。
还要区分两件事:让 Cursor 阅读 OpenAPI 后写代码,与使用可重复运行的合同生成工具,维护方式并不相同。原文批评的「没有重新生成步骤」,针对的是前者,不能推广到所有生成式客户端。
对于前端项目,SDK 包体积确实值得检查,但原文没有提供体积数据,不能据此直接认定手写客户端更划算。
能拿来做什么
- 写 Node 临时脚本或接入少量接口时,可以让 Cursor 编写薄客户端,同时提供当前 OpenAPI 文件,并用真实响应核对路径、认证和字段。
- 把 401、403、超时和响应体格式错误纳入验证,不要把编辑器里的一次成功调用当作上线依据。
- 长期产品涉及多个团队时,先检查 SDK 的维护状态、版本匹配情况,以及重试、取消请求和 token 刷新能力,再决定是否引入。
- 将接口依据和依赖版本纳入日常维护。OpenAPI 或 API 更新后检查受影响的调用,使用 SDK 时关注 changelog,并复验相关失败分支。