API集成开发

解决什么问题

对接第三方 API 时，最常见的翻车现场是：一开始能跑通的 requests.get()，上线后开始间歇性超时；Token 过期后整个链路直接挂掉；对方加了限流，你的服务跟着被拖垮。这个技能要解决的就是这类集成稳定性问题——把「能调通」的代码升级成「能扛事」的客户端。

适用场景包括：

• 正在对接第三方 REST 或 GraphQL API
• 现有调用不稳定，需要加超时、重试、熔断
• 对方文档缺失或不准确，需要从实际响应中逆向分析接口行为

核心能力与工作流

技能按五个步骤推进：

步骤 1 — API 评审：先梳理认证方式、端点结构、速率限制、错误码体系与分页方式，不急着写代码。

步骤 2 — 客户端封装：基于 httpx 构建，配置连接池；重试采用指数退避（最多 3 次）；超时拆分为 connect=30s、read=60s；内置断路器，连续失败 5 次熔断 60 秒。

步骤 3 — 认证管理：支持 Token 过期自动刷新、OAuth refresh flow；API Key 一律从环境变量读取，绝不硬编码。

步骤 4 — 错误处理分层：网络层重试 → HTTP 429 按 Retry-After 退避等待 → 4xx 记录日志 → 5xx 触发熔断。

步骤 5 — 可观测性：输出请求日志、耗时分布与成功率监控，产出中间工件 APIClientConfig，可与 testing-api-contract 串联做契约测试。

适用边界

这个技能只做客户端集成，不负责设计你自己对外提供的 API——那种需求应该用 rest-api-design。同样，它不替代网关层的限流策略，如果你的问题在于流量入口，先去看网关配置。