100-API

API集成规则 (100)

规则概述

本规则定义了API设计、调用和错误处理的最佳实践，旨在提高API的可用性、一致性和鲁棒性。

API设计原则

1.1 RESTful API设计

• 使用HTTP动词表示操作（GET, POST, PUT, DELETE等）
• 使用名词复数形式作为资源标识符（例如：/users, /orders）
• 使用嵌套路由表示资源关系（例如：/users/{id}/orders）
• 使用查询参数进行过滤、排序和分页

# 不推荐
GET /getUser/123
POST /createOrder
DELETE /deleteProduct/456

# 推荐
GET /users/123
POST /orders
DELETE /products/456

1.2 API版本控制

• 在URI中包含API版本（例如：/api/v1/users）
• 或通过请求头指定版本（例如：Accept: application/vnd.company.v1+json）
• 避免破坏性变更，优先使用向后兼容的设计

1.3 响应格式

• 使用一致的响应格式（通常为JSON）
• 包含状态码、数据和元数据
• 使用适当的HTTP状态码表示请求结果

// 推荐的响应格式
{
  "status": 200,
  "data": {
    "id": 123,
    "name": "示例用户"
  },
  "meta": {
    "timestamp": "2024-05-07T12:34:56Z"
  }
}

API调用实践

2.1 请求构建

• 使用专门的HTTP客户端库（例如：Axios, Fetch API, Requests）
• 设置合适的超时时间
• 实现重试机制处理临时性故障

// JavaScript示例：带有超时和重试的API请求
async function fetchWithRetry(url, options = {}, retries = 3, timeout = 5000) {
  options.timeout = timeout;
  
  try {
    return await axios(url, options);
  } catch (error) {
    if (retries <= 0) throw error;
    
    if (error.code === 'ECONNABORTED' || error.response?.status >= 500) {
      await new Promise(r => setTimeout(r, 1000));
      return fetchWithRetry(url, options, retries - 1, timeout);
    }
    
    throw error;
  }
}

2.2 身份验证

• 使用OAuth 2.0或JWT进行身份验证
• 存储敏感凭据时使用安全存储机制
• 实现令牌刷新机制
• 避免在客户端存储长期有效的令牌

2.3 并发控制

• 实现请求限流和批处理
• 管理并发请求数量
• 考虑后端API限制，避免触发限流

错误处理

3.1 错误类型

区分不同类型的错误：

• 网络错误（连接失败、超时）
• 服务器错误（500系列状态码）
• 客户端错误（400系列状态码）
• 业务逻辑错误（特定错误码或消息）

3.2 错误处理策略

• 实现全局错误处理机制
• 对不同类型的错误应用不同的处理策略
• 提供有意义的错误消息给用户
• 记录详细错误信息用于调试

// JavaScript错误处理示例
try {
  const response = await api.getUser(userId);
  // 处理正常响应
} catch (error) {
  if (error.isNetworkError) {
    // 处理网络错误
    showNetworkErrorMessage();
    logError('Network', error);
  } else if (error.status === 401) {
    // 处理认证错误
    redirectToLogin();
    logError('Auth', error);
  } else {
    // 处理其他错误
    showGenericErrorMessage();
    logError('General', error);
  }
}