用途
API Integration Specialist 是一个面向第三方 API 集成的技能，用于在应用中接入外部 API 时提供生产级模式、安全实践与错误处理指导。它适用于集成第三方 API（如 Stripe、Twilio、SendGrid 等）、构建 API 客户端库或封装、实现 OAuth 2.0 / API Key / JWT 认证、设置 Webhook 与事件驱动集成、处理限流与重试与熔断、转换 API 响应以供应用使用，以及调试 API 集成问题。
主要能力
认证与安全
- API Key 管理：将密钥存储在环境变量中，不写入代码。示例中通过
process.env.SERVICE_API_KEY与process.env.SERVICE_BASE_URL初始化客户端。 - OAuth 2.0 授权码流程：使用
OAuth2Client配置 clientId、clientSecret、redirectUri 与 scopes，获取授权 URL 并用 code 换取 token。
请求与响应处理
- 标准化请求结构：统一设置 Content-Type、Authorization、User-Agent 等默认请求头，非 2xx 响应抛出
APIError。 - 响应转换：将外部 API 字段映射为内部模型，例如把
user_id、email_address、first_name/last_name、created_timestamp转换为内部字段。
错误处理
- 结构化错误类型：
APIError携带 status 与 body，并提供isRateLimited()（429）、isUnauthorized()（401）、isServerError()（>=500）判断。 - 指数退避重试：
retryWithBackoff默认最多重试 3 次，仅对服务端错误重试，延迟为 1s、2s、4s。
限流
- 客户端限流器：
RateLimiter按时间窗口限制请求数量，示例为每分钟 100 次请求，超出时等待窗口释放后重试。
Webhook 处理
- 签名验证：使用 HMAC-SHA256 计算期望签名，并通过
crypto.timingSafeEqual做恒定时间比较；示例展示 Stripe Webhook 的签名校验与事件处理。
使用方式
该技能以指导与代码示例形式提供集成模式，包括：
- REST API 客户端模式：封装
ServiceAPIClient，提供 request 方法及 getResource、createResource、updateResource、deleteResource 等资源方法，并结合重试逻辑。 - 分页处理：通过异步生成器
fetchAllPages按 cursor 逐页拉取数据。 - 常见集成示例：Stripe 创建 PaymentIntent、SendGrid 发送邮件、Twilio 发送短信。
- 最佳实践：安全（环境变量、HTTPS、验证 Webhook 签名、请求签名、定期轮换密钥）、可靠性（指数退避、优雅处理限流、设置超时、熔断、日志）、性能（缓存、批量请求、流式响应、连接池、监控用量与成本）、监控（响应时间、错误率告警、限流消耗、失败请求日志、健康检查）。
- 故障排查：认证问题、限流、超时错误的排查方向。
适用场景
适用于需要将第三方 REST API、GraphQL 等外部服务接入应用的开发工作，尤其是涉及认证、限流、重试、Webhook 与响应转换的集成任务。
限制
资料未提供该技能的安装命令、运行环境要求、收费或价格信息、平台支持范围，以及具体效果或性能数据，这些内容暂未提供。