更换 API 供应商或接入失败时，怎样避免把整个项目改坏？
先比较真实接口约定，再在现有边界内替换，用状态码、响应和调用链定位故障。
本页目录
直接回答
更换供应商不是简单替换地址和模型名。请求格式、图片参数、流式协议、异步状态和错误结构都可能不同。替换前应先确认旧能力、新能力、字段映射与回退需求，再输出实施计划。整理建议：先找到项目现有 API 封装并复用，把变化集中在必要边界，只有真实存在多种实现需求时才增加适配层。发生错误时先用证据定位是输入、认证、额度、服务端还是上游问题，避免让 AI 连续猜测并重写整个功能。
适用场景
- 准备从平台 SDK 换到其他模型接口
- 接口在 Postman 成功，在项目里却失败
- AI 修复了几轮，错误反而越来越多
一步一步做
找到所有调用方与既有约定
搜索原 API 服务函数、环境变量名和响应字段，确认页面、后台任务、测试与数据保存是否依赖它。记录上层实际需要什么，例如最终图片地址、可追踪任务 ID 或文本增量，而不只记录供应商原始 JSON。
独立验证新接口并比较差异
用同一组输入验证新接口。列出输入字段、结果字段、失败类型、调用次数、超时和存储方式的变化。特别检查同步改异步、单图改多图、临时链接改文件内容等差异，它们可能影响用户流程与数据库。
在最小边界完成替换
沿用现有服务层或模块，保持无须变化的调用接口。确实需要改调用方时，一并更新类型、页面状态、记录保存与相关验证。回退旧供应商只有在权限、成本、语义一致且不会重复产生任务时才有意义，不要默认无条件重试。
按证据排查故障
收集发生时间、请求 ID、状态码、脱敏响应与最近改动。401/403 优先核对认证和权限，429 核对额度与频率，超时核对任务时长及网络，5xx 查看服务端与供应商证据；这些是排查方向，并非仅凭状态码即可定论。
验证成功与失败的完整路径
确认真实结果被展示和保存，再检查空输入、无权限、超时、上游失败和重试。日志记录必要定位信息，不输出完整 Key、用户私密输入或签名地址。验证失败仍应显示失败，不能为了页面流畅返回假的成功数据。
逐项判定流式、异步与最终结果
若请求写 stream:false，响应却含 partial_succeeded 等中间状态，不能只凭这些字段猜测最终结果。以实际请求与供应商当前文档为准：普通 JSON 解析一次；SSE 或其他流式协议累积事件并识别结束；任务接口保存任务 ID，按允许频率查询终态。只有最终结果且文件可读时才标记完成；连接断开或查询超时先查任务是否已创建，再决定重试，防止重复付费。
案例拆解
假设示例：生图从立即返回改为排队任务
旧接口一次请求返回图片 URL，新接口只返回任务 ID，需要查询状态。若只改地址，页面会把“还没完成”误判为没有结果。最小正确改动应包括任务提交、等待状态、终态处理和结果保存；若页面关闭后还要找回任务，则还需明确持久化。这个差异应在集成前的接口比较中发现，而不是靠用户报错才补。
补充假设示例：界面显示 100%，但收到的只是一个含预览图的中间事件。服务端继续等待文档规定的最终状态，成功后再保存结果；若连接断开则用任务 ID 查已有任务。不要自动重发生成请求，否则一次用户操作可能变成两次收费。
行动检查
可复制模板
API 替换与排错请求
工作模板
当前能力：［描述］；旧服务：［名称］；新服务：［名称］。
先读所有调用方和现有封装，不立即大改。比较请求、返回、异步／流式行为、错误及成本差异。
已验证的脱敏请求与响应：［材料］。当前错误、时间与最近改动：［记录］。
请先给出根因假设及验证方法，再执行最小修改；同步必要调用方与验证。交付真实结果、失败路径和回退范围，不打印凭据。
响应协议与终态对照卡
旧／新接口：
请求是否指定stream、实际响应Content-Type：
模式：［单次JSON／事件流／异步任务］
事件或状态表：状态｜数据字段｜是否最终｜下一动作
任务ID／最终结果字段／可见文件验证：
断线或超时后：［先查询已有任务还是重发，依据是什么］
取消与重复提交：
费用发生点、幂等支持和不确定状态：
上线前保留的脱敏实际响应样本：
易错点
- 每次报错就换库、换模型、换架构：会失去判断哪个变化有效的依据。
- 把适配层当成必需设计：只有少量调用时可复用现有模块，避免为未来假想扩展。
- 无条件重试付费任务：先判断第一次请求是否已经创建任务。