Vibe Coding 第三方集成：官方 SDK 还是直接 HTTP，如何做可替换选择

让 AI “安装官方 SDK 并完成集成”通常最快得到 Demo，但 SDK 可能还没覆盖新接口、只支持 Node 运行时、内置不可见重试，或把供应商错误压成一个通用异常。反过来，坚持直接 fetch 也不天然简单：认证刷新、分页、流式解析、上传编码和兼容演进都变成自己的维护责任。

选择对象不是“依赖多一个包”这么小，而是由谁承担协议适配。Google Cloud 的客户端库说明区分手写 Cloud Client Libraries 与自动生成的 API Client Libraries，这提示我们：即使都叫官方 SDK，抽象层次、体验与能力也可能不同。先阅读供应商当前文档，再为实际操作做探针，不能根据包名猜行为。

先列出你真正使用的协议面

不要比较 SDK 的总功能数量。列出本项目会调用的 operation、认证模式、同步或流式响应、文件大小、分页、长任务轮询、幂等、超时、代理和运行时。标明哪些是第一版必需、哪些只是可能需要；AI 若自行加入批量、自动重试或缓存，应视为未批准的语义变化。

接着建立三个候选：供应商维护的 SDK、由 OpenAPI/其他 IDL 生成的客户端、直接 HTTP 的薄适配器。逐项记录：

• 能否覆盖目标 operation 与当前 API 版本；
• Node、Edge、浏览器或其他运行时是否真正支持；
• 认证凭证如何注入、刷新和隔离；
• 超时、重试、分页和流控默认行为能否配置；
• 原始状态码、header、request ID 和错误 body 是否可取得；
• 包体、传递依赖、发布节奏和安全更新由谁负责；
• mock、录制和故障注入是否方便。

这些结论必须来自锁定版本的代码、官方文档或可执行探针。不要写“SDK 通常更稳定”或“fetch 一定更轻”。SDK Quickstart 首次成功契约适合衡量入门路径，但生产选择还要覆盖失败和升级。

三种方案各自适合什么

官方 SDK 适合认证或协议复杂、长任务和分页已被可靠封装、供应商积极维护且运行时匹配的场景。它的价值是减少协议细节重复，不是免除审查。查看默认 timeout 是否存在、自动重试哪些方法、是否读取环境全局凭证，以及 major/minor 升级是否改变模型类型。

生成客户端适合有质量较高、版本稳定的 OpenAPI 契约，并希望类型与 operation 同步的场景。生成物必须可重建且不手改，外层仍需处理认证、观测和领域错误。复杂 oneOf、流式协议或供应商扩展要用小型 conformance suite 验证，不能因为生成成功就假设运行正确。编程 Agent 修改 API 的契约兼容门可用于拦截上游规范的破坏性变化。

直接 HTTP 适合只用少量稳定 operation、协议清晰、需要精确控制 header/流式传输，或 SDK 不支持目标运行时的情况。薄并不等于散落 fetch：集中 base URL、认证、序列化、deadline、错误解码和 telemetry，但把 operation 方法保持显式。RFC 9110 定义的 HTTP 语义是底线，供应商文档再补充业务约束。

有些集成可混用：大部分操作走 SDK，缺失的新接口由 direct HTTP 临时补充。但两条路径必须共享认证和观测，并计划 SDK 覆盖后的收敛；否则重试、User-Agent 和错误类型会长期分裂。Agent 改 API 的契约兼容门展示了“接口能调用”不等于消费者契约仍然成立，同样适用于供应商 SDK 的抽象承诺。

用端口隔离供应商选择

领域代码依赖自有接口，例如 PaymentGateway.createIntent(command)，而不是到处导入供应商类型。适配器把 SDK 或 HTTP 的 response 转为内部结果：稳定错误类别、远端 request ID、可重试提示和必要领域字段。原始响应只在受控诊断中保留，不泄露 token 或个人数据。

端口不能被设计成所有供应商字段的最大并集；那只是换名后的供应商耦合。先表达产品真正需要的能力，供应商特有扩展通过明确 capability 查询或专用路径暴露。工具结果演进可参考工具结果 Schema 兼容矩阵，让调用方知道哪些字段稳定。

无论选哪种，应用层统一设置 deadline，并避免 SDK 内重试叠加外层重试。若 SDK 无法关闭或观测重试，必须把它写入容量预算。错误映射保留 401、403、409、429、5xx 与网络未知结果的差别；一个 catch { throw IntegrationError } 会让上层无法决定刷新凭证、停止重试还是对账。

用同一套黑盒场景做决定

为候选实现最小纵向切片，用相同测试验证正常请求、认证失败、校验失败、429、5xx、超时、断流、分页结束、未知字段和 request ID 传递。记录可观察行为和实现复杂度，不虚构吞吐差异。需要性能数据时，用实际 payload 和部署运行时单独基准，并保存版本和环境。

升级测试锁定依赖与 API 版本，先在 CI 对 sandbox 或本地协议桩运行 conformance suite，再合并依赖更新。REST API 版本控制中的兼容策略也适用于上游：弃用 header、版本公告和 schema diff 应进入依赖更新报告。

最终决策记录采用的候选、锁定版本、被拒绝原因、已知缺口、退出条件和 owner。例如“当 SDK 支持 Edge 且可关闭内置重试时重新评估”，比“SDK 太重”更可执行。让 AI 根据矩阵实现适配器，而不是让它自行挑最熟悉的库，第三方集成才能在供应商变化时替换，而不重写整个业务层。