API调试指南

目标

建立系统化的API调试流程，从工具选择到错误排查，确保前后端接口对接高效可靠。

前置条件

已有可访问的API端点（本地或远程）
了解HTTP协议基础（请求方法、状态码、Header）
已安装开发工具（Cursor、VS Code 或其他IDE）

操作步骤

步骤1：选择测试工具

目的：根据场景选择合适的API测试工具，提升调试效率。操作：

了解各工具适用场景：

工具	适用场景	优势	缺点
curl	快速验证单个接口	随处可用，可脚本化	无UI，参数多时不直观
Postman	复杂API调试和测试集合	界面友好，支持环境变量、集合	桌面应用较重
VS Code REST Client	在IDE中直接测试	轻量，`.http`文件可版本管理	功能不如Postman完整

推荐选择策略：
- 日常开发 → VS Code REST Client（在 Cursor 中直接使用）。
- 复杂API调试 → Postman。
- 自动化脚本/CI → curl。
安装配置：
- curl：macOS/Linux 已预装，Windows 10+ 已内置。
- Postman：https://www.postman.com/downloads/ 下载安装。
- VS Code REST Client：在扩展商店搜索 "REST Client" 安装。验证：

已安装至少一个API测试工具
工具可正常发送请求并收到响应

步骤2：先测API再开发

目的：在写前端代码之前先验证API可用性，避免前后端联调时才发现接口问题。操作：

获取API文档：
- 如果使用知名库或服务，通过 Context7 MCP 获取最新文档。
- 自建API需确认文档地址（如 Swagger UI、OpenAPI spec）。
按以下顺序验证API：
- 先验证连通性：发送最简单的请求，确认端点可访问。
- 再验证认证：测试API Key / OAuth Token 是否正确。
- 最后验证业务逻辑：测试各种参数组合的返回结果。

创建 .http 测试文件（VS Code REST Client 格式）：

http

### 获取用户列表
GET https://api.example.com/users
Authorization: Bearer {{token}}
Content-Type: application/json

### 创建用户
POST https://api.example.com/users
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "name": "Test User",
  "email": "test@example.com"
}

### 获取单个用户
GET https://api.example.com/users/1
Authorization: Bearer {{token}}

将 .http 文件提交到代码仓库，团队成员共享API测试用例。验证：

每个API端点都有对应的测试请求
认证流程验证通过
测试文件已纳入版本管理

步骤3：使用Context7 MCP获取最新文档

目的：在开发过程中实时获取第三方库和服务的最新API文档，避免依赖过时信息。操作：

在 Claude Code 中通过 Context7 MCP 查询文档：
- 先解析库ID：搜索库名（如 "Stripe"、"Resend"、"NextAuth"）。
- 再查询文档：针对具体问题获取最新代码示例和参数说明。
适用场景：
- 查询第三方服务的API参数和返回格式。
- 确认SDK最新版本的用法变化。
- 获取框架的最新配置方式。
使用技巧：
- 查询时尽量具体（如 "Stripe create checkout session parameters" 而非 "Stripe API"）。
- 对比文档版本号和实际使用的包版本。验证：

获取的API文档与当前使用版本一致
代码示例可直接运行

步骤4：错误排查

目的：快速定位和解决API调用中的各类错误。操作：

按HTTP状态码分类排查：

状态码	含义	排查方向
400 Bad Request	请求参数错误	检查请求体格式、必填参数、数据类型
401 Unauthorized	认证失败	检查Token是否过期、API Key是否正确、Header格式
403 Forbidden	无权限	检查账号权限、IP白名单、资源访问限制
404 Not Found	资源不存在	检查URL路径、资源ID、API版本号
429 Too Many Requests	速率限制	检查请求频率，实现退避重试
500 Internal Server Error	服务端错误	查看服务端日志，联系API提供方
502/503 Bad Gateway	服务不可用	检查服务器状态、CDN配置、部署状态

超时处理：

设置合理的超时时间：
- 普通API请求：5-10秒。
- 文件上传：30-60秒。
- AI/大模型API：30-120秒。

实现超时重试：

javascript

async function fetchWithRetry(url, options = {}, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const controller = new AbortController();
      const timeout = setTimeout(() => controller.abort(), 10000);
      const response = await fetch(url, { ...options, signal: controller.signal });
      clearTimeout(timeout);
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return response;
    } catch (error) {
      if (i === retries - 1) throw error;
      const delay = Math.pow(2, i) * 1000; // 指数退避
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

速率限制处理：

查看API文档了解速率限制规则（如 100 requests/minute）。
从响应Header中读取限制信息：
- X-RateLimit-Limit：总限制数。
- X-RateLimit-Remaining：剩余请求数。
- X-RateLimit-Reset：限制重置时间。
实现客户端限流：
- 使用队列控制请求频率。
- 接近限制时主动等待，而非被拒绝后重试。验证：

各类错误有对应的处理逻辑
超时和重试机制正常工作
速率限制不会导致请求失败

步骤5：日志记录最佳实践

目的：通过规范的日志记录，使API问题可追溯、可排查。操作：

请求日志：记录每次API调用的关键信息。

javascript

console.log('[API Request]', {
  method: 'POST',
  url: '/api/users',
  headers: { 'Content-Type': 'application/json' },
  body: { name: 'test' },
  timestamp: new Date().toISOString()
});

响应日志：记录响应状态和耗时。

javascript

const startTime = Date.now();
const response = await fetch(url);
const duration = Date.now() - startTime;
console.log('[API Response]', {
  status: response.status,
  duration: `${duration}ms`,
  url: url
});

错误日志：记录完整的错误上下文。

javascript

console.error('[API Error]', {
  url: url,
  method: method,
  status: error.status,
  message: error.message,
  stack: error.stack,
  requestBody: body
});

日志分级：
- debug：详细的请求/响应内容（仅开发环境）。
- info：API调用成功，记录耗时。
- warn：非致命问题（重试成功、接近速率限制）。
- error：请求失败，需要关注。
敏感信息处理：
- 日志中脱敏 Token、API Key、密码等字段。
- 生产环境不记录完整请求体和响应体。验证：

所有API调用都有对应日志
日志包含足够的排查信息（URL、状态码、耗时）
敏感信息已脱敏

检查清单

[ ] API测试工具已安装配置
[ ] 所有API端点都有测试用例
[ ] 认证流程已验证
[ ] 常见HTTP错误有对应的处理逻辑
[ ] 超时和重试机制已实现
[ ] 速率限制处理已实现
[ ] 日志记录规范已建立
[ ] 测试用例文件已纳入版本管理

常见问题

问题	原因	解决方案
CORS错误	服务端未配置允许跨域	后端添加 Access-Control-Allow-Origin Header，或使用代理
请求一直pending	服务端未响应或网络不通	检查服务是否运行；设置请求超时；检查防火墙规则
Token频繁过期	Token有效期设置过短	实现Token自动刷新机制；检查过期时间配置
返回数据格式不符预期	API版本更新或文档过时	用 Context7 MCP 获取最新文档；检查实际返回的JSON结构
并发请求被限流	超过API速率限制	实现请求队列；使用指数退避重试；缓存重复请求结果
POST请求返回415	Content-Type Header缺失或错误	确认添加 `Content-Type: application/json` Header

参考文章

Cursor：IDE中直接使用REST Client测试API
Cloudflare：Workers中API代理和缓存配置
Vercel：Edge Functions中API开发和调试
Neon：数据库连接和查询调试

API调试指南 ​

目标 ​

前置条件 ​

操作步骤 ​

步骤1：选择测试工具 ​

步骤2：先测API再开发 ​

步骤3：使用Context7 MCP获取最新文档 ​

步骤4：错误排查 ​

步骤5：日志记录最佳实践 ​

检查清单 ​

常见问题 ​

参考文章 ​

API调试指南

目标

前置条件

操作步骤

步骤1：选择测试工具

步骤2：先测API再开发

步骤3：使用Context7 MCP获取最新文档

步骤4：错误排查

步骤5：日志记录最佳实践

检查清单

常见问题

参考文章