介绍
## When to Use
用户需要 API 集成方面的专业知识 —— 从基础请求到生产就绪的模式。Agent 负责处理认证、错误处理、重试、分页和 Webhook。
## 快速参考
| 主题 | 文件 | |-------|------| | 认证模式 | `auth.md` | | 重试与容错 | `resilience.md` | | 分页处理 | `pagination.md` | | Webhook 集成 | `webhooks.md` |
## 请求陷阱
- 在 POST/PUT/PATCH 请求中包含 `Content-Type: application/json` —— 遗漏该头会导致许多 API 返回静默的 415 错误 - 添加 `Accept: application/json`，除非 API 指定了不同的格式 —— 某些 API 在没有它时默认返回 XML - 查询参数中的 API 密钥会被记录在服务器访问日志中 —— 如果支持，请优先使用基于 Header 的认证 - Token 可能在请求与响应之间过期 —— 遇到 401 时应执行单次重试并刷新 Token
## 静默失败
- 某些 API 返回 HTTP 200 状态码，但响应体中包含错误 —— 需验证响应模式（schema），而不仅仅是状态码 - 注意空数组、null 值与缺失键的区别 —— 对于每个 API 来说，它们的含义各不相同 - 当偏移量超过总数时，分页端点可能会返回 200 状态码和空页面 —— 请先检查总数
## 重试与容错
- 使用抖动指数退避：`delay = min(base * 2^attempt * (1 + random(0, 0.3)), max_delay)`，其中 base=1s，max=30s - 通常仅针对 429、500、502、503、504 状态码重试 —— 除非 API 文档另有说明，否则避免重试 400、401、403、404 - 读取 429 响应中的 `Retry-After` 头 —— 它优先于你计算出的退避时间 - 对同一端点连续失败 5 次以上后，在重试前完全暂停 60 秒（熔断机制）
## 分页陷阱
- 如果页面之间的数据发生变化，基于游标的分页可能会返回重复项 —— 通过 ID 进行去重 - 某些 API 会在请求之间更改 `total_count` —— 在第一页时对其做快照 - 如果页面返回的项目少于 `per_page` 但包含 `next` 游标，请继续分页 —— 这不一定是最后一页
## 速率限制
- 通过 `X-RateLimit-Remaining` 头跟踪配额 —— 在降为 0 之前主动限流，不要等到收到 429 错误 - 某些 API 具有针对每个端点的隐藏速率限制，而不仅仅是全局限制 —— 需按路径监控 429 错误 - 在速率限制的时间窗口内均匀分布请求，而不是在开始时突发请求
## Webhook
- 使用事件 ID 去重实现幂等处理程序 —— 提供商会在超时时重试，你将会收到重复请求 - 立即返回 200，异步处理 —— Webhook 提供商的超时时间通常为 5-30 秒 - 当提供商支持时，验证 Webhook 签名 —— 在没有加密证明的情况下不要信任请求来源 - 在解析之前记录原始 Webhook 请求体 —— 当提供商在未通知的情况下更改其模式时，这将非常有价值
## 调试生产问题
- 日志：针对每次 API 调用，记录方法、URL、状态码、响应时间和 `X-Request-Id` 头 - 在开发环境正常但在生产环境失败的 API：检查 IP 白名单、TLS 版本、SNI 和出站代理设置 - 当响应数据看起来不正确时，与 OpenAPI/Swagger 规范进行比较 —— 规范通常比人工编写的文档更新