API 模块规范

本文件覆盖 /src/api/ 目录下所有内容的根 CLAUDE.md 配置。

API 专项规范

请求校验

• 使用 Zod 进行 Schema 校验
• 始终校验输入
• 校验失败返回 400 状态码
• 返回字段级别的错误详情

认证

• 所有接口需携带 JWT Token
• Token 放在 Authorization 请求头
• Token 有效期 24 小时
• 实现 Refresh Token 机制

响应格式

所有响应必须遵循如下结构：

{
  "success": true,
  "data": { /* 实际数据 */ },
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

错误响应：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "用户可见的错误信息",
    "details": { /* 字段级错误 */ }
  },
  "timestamp": "2025-11-06T10:30:00Z"
}

分页

• 使用游标分页（而非偏移量分页）
• 包含 hasMore 布尔字段
• 单页最大条数限制为 100
• 默认每页 20 条

限流

• 认证用户：每小时 1000 次请求
• 公开接口：每小时 100 次请求
• 超限返回 429 状态码
• 响应头中包含 retry-after

缓存

• 使用 Redis 进行会话缓存
• 默认缓存时长：5 分钟
• 写操作时使缓存失效
• 缓存键以资源类型为前缀