# API Integration (API 集成) > 🔌 **核心理念** : 稳健的 API 集成 = 类型安全 + 优雅错误处理 + 智能重试 ## 🔴 第一原则：防御性编程 **永远假设 API 会失败，做好所有准备！** ❌ 错误思路: "这个 API 很稳定，不需要错误处理" ✅ 正确思路: "任何 API 都可能失败，必须有完整的错误处理和降级方案" ❌ 错误思路: "直接调用就行，简单快速" ✅ 正确思路: "封装一层，统一处理认证、错误、重试、日志" ## When to Use This Skill 使用此技能当你需要： * 集成第三方 REST/GraphQL API * 设计 API 客户端架构 * 实现错误处理和重试逻辑 * 处理 API 认证和授权 * 优化 API 调用性能 ## Not For / Boundaries 此技能不适用于： * 设计自己的 API（参考 API 设计规范） * 数据库直接操作（参考 database-migration skill） * WebSocket 实时通信（参考专门的实时通信方案） * * * ## Quick Reference ### 🎯 API 集成决策流程需求分析 → 选择客户端库 → 设计封装层 → 实现错误处理 → 添加重试逻辑 → 测试验证 ↓ 优先使用官方 SDK ### 📋 集成前必问清单问题 | 目的 ---|--- 1\. 有没有官方 SDK？ | 优先使用官方维护的客户端 2\. API 文档是否完整？ | 确认端点、参数、响应格式 3\. 认证方式是什么？ | API Key / OAuth / JWT 4\. 有没有速率限制？ | 设计限流策略 5\. 错误码有哪些？ | 设计错误处理映射 6\. 是否需要重试？ | 确定重试策略 ### 🔧 推荐技术栈场景 | 推荐方案 ---|--- HTTP 客户端 | ky, axios, fetch 类型生成 | openapi-typescript, graphql-codegen 请求缓存 | @tanstack/react-query, swr 重试逻辑 | p-retry, axios-retry 速率限制 | bottleneck, p-limit Mock 测试 | msw, nock ### ✅ API 客户端设计原则 // ✅ 好的设计：封装统一的 API 客户端 class ApiClient { private baseUrl: string; private headers: Record; constructor(config: ApiConfig) { this.baseUrl = config.baseUrl; this.headers = { 'Content-Type': 'application/json', 'Authorization': `Bearer ${config.apiKey}`, }; } async request(endpoint: string, options?: RequestOptions): Promise { // 统一处理：认证、错误、重试、日志 } } // ❌ 坏的设计：到处散落的 fetch 调用 const data = await fetch('https://api.example.com/users', { headers: { 'Authorization': `Bearer ${apiKey}` } }); * * * ## API 集成工作流 ### Phase 1: 需求分析与准备 1. 阅读 API 文档，理解端点和数据结构 2. 确认认证方式和获取凭证 3. 了解速率限制和配额 4. 确定需要调用的端点列表 5. 设计数据模型和类型定义 ### Phase 2: 客户端架构设计 1. 选择 HTTP 客户端库 2. 设计基础客户端类/函数 3. 实现认证逻辑 4. 设计请求/响应拦截器 5. 规划错误处理策略 ### Phase 3: 实现与测试 1. 实现各端点调用方法 2. 添加类型定义 3. 实现错误处理 4. 添加重试逻辑 5. 编写单元测试和集成测试 ### Phase 4: 优化与监控 1. 添加请求缓存 2. 实现请求合并/批处理 3. 添加日志和监控 4. 性能优化 * * * ## Examples ### Example 1: REST API 集成 **Input:** "需要集成 GitHub API 获取用户仓库列表" **Steps:** 1. 检查官方 SDK: `@octokit/rest` ✅ 2. 评估: Stars 5k+, 官方维护, TypeScript 支持 3. 决策: 使用官方 SDK **Expected Output:** pnpm add @octokit/rest import { Octokit } from '@octokit/rest'; const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN, }); async function getUserRepos(username: string) { try { const { data } = await octokit.repos.listForUser({ username, sort: 'updated', per_page: 100, }); return data; } catch (error) { if (error.status === 404) { throw new UserNotFoundError(username); } throw error; } } ### Example 2: 自定义 API 客户端 **Input:** "需要集成一个没有官方 SDK 的第三方 API" **预期输出：** // 服务/api/customApiClient.ts 从 'ky' 导入 ky；从 'p-retry' 导入 pRetry；接口 ApiConfig { 基址：字符串； apiKey：字符串；超时？：数量； } 导出函数 createApiClient(config: ApiConfig) { const 客户端 = ky.create({ prefixUrl: config.baseUrl, 超时：config.timeout ?? 30000, 标题：{ '授权': `承载${config.apiKey}`, '内容类型'：'应用程序/json'， }, 钩子：{ 之前错误：[ （错误）=> { // 统一错误处理 const { 响应 } = 错误；如果（响应？.status === 429）{ error.name = 'RateLimitError'; } 返回错误； }, ], }, }); 返回{ 异步 get(端点: string): Promise { 返回p重试（ () => client.get(端点).json(), { 重试：3，onFailedAttempt：logRetry } ）； }, 异步 post（端点：字符串，数据：未知）： Promise { 返回p重试（ () => client.post(endpoint, { json: data }).json(), { 重试：3，onFailedAttempt：logRetry } ）； }, }; } ### 示例 3：GraphQL API 集成 **输入：** “需要集成 GraphQL API” **预期输出：** pnpm 添加 graphql-请求 graphql // 服务/api/graphqlClient.ts 从 'graphql-request' 导入 { GraphQLClient, gql }; const client = new GraphQLClient(process.env.GRAPHQL_ENDPOINT!, { 标题：{ 授权：`承载${process.env.API_TOKEN}`， }, }); // 类型安全的查询常量 GET_USER = gql` 查询 GetUser($id: ID!) { 用户（id：$id）{ 编号姓名电子邮件 } } `; 界面用户{ id：字符串；名称：字符串；电子邮件：字符串； } 导出异步函数 getUser(id: string): Promise { const { user } = wait client.request<{ user: User }>(GET_USER, { id }); 返回用户； } ** ** ## 错误最佳处理实践 ### 错误分类与处理策略错误类型 | HTTP 状态码 | 处理策略 ---|---|--- 客户端错误 | 400-499 | 400-499 不重试，返回用户偏好错误认证错误 | 401, 403 | 刷新令牌或提示重新登录资源不存在 | 404 | 404 返回 null 或推送特定错误速度限制 | 429 | 429 等待后重试服务器错误 | 500-599 | 指数退避重试网络错误 | - | 重试+降级方案 ### 自定义错误类 // 错误/apiErrors.ts 导出类 ApiError 扩展错误 { 构造函数（消息：字符串，公共状态代码：数字，公共代码：字符串，公共可重试：boolean = false ）{ 超级（消息）； this.name = 'ApiError'; } } 导出类 RateLimitError 扩展 ApiError { 构造函数（公共重试之后：数字）{ super('超出速率限制', 429, 'RATE_LIMIT', true); } } 导出类 AuthenticationError 扩展 ApiError { 构造函数（）{ super('认证失败', 401, 'AUTH_FAILED', false); } } ** ** ## 重试策略 ### 指数退避重试从 'p-retry' 导入 pRetry； const 结果 = 等待 pRetry( 异步（）=> { const 响应 = 等待 fetch(url); 如果（！response.ok）{ 抛出新错误(`HTTP ${response.status}`); } 返回response.json(); }, { 重试次数：3， minTimeout: 1000, // 首次重试等待 1s maxTimeout: 10000, // 最大等待10s Factor: 2, // 指数因子 onFailedAttempt：（错误）=> { console.log(`尝试 ${error.attemptNumber} 失败。${error.retriesLeft} 剩余重试次数。`); }, } ）； ### 条件重试 // 只对特定错误重试 const shouldRetry = (error: Error) => { if (error instanceof ApiError) { return error.retryable; } // 网络错误总是重试 return error.name === 'TypeError' || error.name === 'NetworkError'; }; * * * ## References * `references/rest-template.md`: REST API 集成完整模板 * `references/error-handling.md`: API 错误处理模式详解 * * * ## Maintenance * **Sources** : 行业最佳实践, 开源社区经验 * **Last Updated** : 2025-01-01 * **Known Limits** : * 具体 API 的特殊处理需要根据文档调整 * 某些 API 可能需要特殊的认证流程

API集成

包含技能