浏览 AI 知识库
API 接口对接流程：先核对认证、请求、响应和错误格式
API 对接不要从复制成功响应开始。认证方式、请求头、字段类型、错误结构和最小可运行请求，才是双方能否联通的基础。
沿完整工作流推进
前一阶段的可检查结果，是下一阶段的输入；中间证据不足时停在当前阶段。
先遇到 401、再遇到 422，问题其实出在两层
开发者照文档发送 POST 请求得到 401，拿到 Token 后又因字段名错误收到 422。只盯着成功 JSON 示例，遗漏了认证头、Content-Type 和错误结构。
- 认证和环境明确
- 最小真实请求已验证
- 错误与重试契约写入对接记录
先确认这次任务的起点、边界和交付
| 需要确认 | 本例内容 |
|---|---|
| 现有材料 | 目标接口 `POST /v1/orders`；有 OpenAPI 文档、测试 Token 和最小订单样例；禁止调用生产。 |
| 不能越过的边界 | 先核对环境、认证、请求和响应契约；Token 脱敏；用最小请求验证，再接入完整页面。 |
| 要交付的结果 | API 契约核对表与最小请求 |
从“认证与环境”走到“测试分页、超时和重试”
| 当前阶段 | 实际处理 |
|---|---|
| 认证与环境 | 区分测试和生产端点、密钥类型、scope、请求头和轮换方式，不把密钥写进源码。 |
| 最小成功请求 | 只带必填字段运行一次，保存脱敏请求、响应、状态码、请求 ID 和时间。 |
| 建立请求响应模型 | 逐字段记录类型、必填、枚举、默认、空值和版本兼容，未知字段保持向前兼容。 |
| 按状态码处理错误 | 区分用户输入、认证、权限、资源、限流和服务端错误，保留上游原始信息供诊断。 |
| 测试分页、超时和重试 | 验证终止条件、幂等性、退避和取消，不对所有失败无限重试。 |
先让一个测试订单请求成功，再封装业务客户端
教学场景：仓库需要接入供应商测试环境的订单查询接口。示例值已脱敏，真实接入必须使用官方文档给出的主机、认证方式和字段。
PowerShell
保留状态码、请求 ID 和原始响应
$headers = @{ Authorization = "Bearer $env:VENDOR_API_TOKEN"; Accept = "application/json" }
$response = Invoke-WebRequest `
-Uri "https://sandbox.example.test/v1/orders/ord_1042" `
-Headers $headers -Method Get -SkipHttpErrorCheck
$response.StatusCode
$response.Headers['x-request-id']
$response.Content实测响应
客户端类型必须覆盖空值和枚举
HTTP 200
x-request-id: req_demo_7f31
{
"id": "ord_1042",
"status": "processing",
"paid_at": null,
"items": [{ "sku": "A-17", "quantity": 2 }]
}成功样例只证明这一条请求可用；还要分别保存 401、404、429、超时和空列表样例，确认是否可重试及是否产生副作用。
文档、实际响应和本地类型要逐字段对齐
| 字段或行为 | 官方说明 | 实测 | 本地处理 |
|---|---|---|---|
| status | pending / processing / completed | processing | 未知枚举保留原值并报警 |
| paid_at | 完成付款后为时间 | null | 类型允许 null，不转成空字符串 |
| items | 数组 | 2 件同一 SKU | 校验 quantity 为正整数 |
| 429 | 可能含 Retry-After | 待错误样例验证 | 未确认前不自动无限重试 |
完成后的API 契约核对表与最小请求
契约表记录 Base URL、Bearer 认证、幂等键、必填字段和 400/401/409/422/429 错误。最小 curl 在沙盒返回 201 与 requestId；同一幂等键重试未创建第二笔订单。
为什么“最小请求成功，前端接入仍失败”还不能交付
最小请求成功，前端接入仍失败
- 原因
- 浏览器请求在 CORS、代理或序列化层改变
- 怎么改
- 对比实际网络请求与成功 curl，逐字段检查头、正文和环境