接一个新 API 前，先核对认证、请求、响应和错误格式

接 API 前先冻结契约和最小请求

认证方式、端点、字段、分页、限流、错误和版本都可能变化。先用官方文档和实际响应确认，再封装客户端；不要从一段旧 curl 推导整个接口。

认证与环境

区分测试和生产端点、密钥类型、scope、请求头和轮换方式，不把密钥写进源码。

把涉及的文件、目录、版本、命令和实际输出写进记录；代码变化同时保留 diff 与测试结果。

最小成功请求

只带必填字段运行一次，保存脱敏请求、响应、状态码、请求 ID 和时间。

确认“最小成功请求”已经有可回查结果，再进入“建立请求响应模型”；依据仍然来自猜测时，把缺口单列并停在当前步骤。

建立请求响应模型

逐字段记录类型、必填、枚举、默认、空值和版本兼容，未知字段保持向前兼容。

确认“建立请求响应模型”已经有可回查结果，再进入“按状态码处理错误”；依据仍然来自猜测时，把缺口单列并停在当前步骤。

按状态码处理错误

区分用户输入、认证、权限、资源、限流和服务端错误，保留上游原始信息供诊断。

确认“按状态码处理错误”已经有可回查结果，再进入“测试分页、超时和重试”；依据仍然来自猜测时，把缺口单列并停在当前步骤。

测试分页、超时和重试

验证终止条件、幂等性、退避和取消，不对所有失败无限重试。

需要修改时先限定文件和行为范围，无法说明回滚方式或影响面的动作先不执行。 完成后把证据归入“API 契约核对表与最小请求”。

契约表必须与一次真实调用对应

文档字段、实际响应和本地类型有差异时先记录并确认。最小请求、错误样例和测试通过后，再在业务流程中集成。