Everything Claude Code API设计指南：REST API、分页和错误响应的AI最佳实践

【免费下载链接】everything-claude-code Complete Claude Code configuration collection - agents, skills, hooks, commands, rules, MCPs. Battle-tested configs from an Anthropic hackathon winner. 项目地址: https://gitcode.com/GitHub_Trending/ev/everything-claude-code

Everything Claude Code是一个完整的Claude Code配置集合，包含代理、技能、钩子、命令、规则和MCP等组件，是Anthropic黑客马拉松的获奖项目。本指南将详细介绍REST API设计的最佳实践，包括资源命名、状态码使用、分页实现和错误响应处理等核心内容，帮助开发者构建高效、可靠的API接口。

API设计的核心原则

API设计是构建现代应用程序的关键环节，良好的API设计能够提高开发效率、增强系统可维护性，并提供出色的用户体验。在Everything Claude Code项目中，API设计遵循以下核心原则：

• 一致性：统一的命名规范、响应格式和错误处理机制
• 易用性：直观的资源路径、清晰的文档和合理的默认值
• 可扩展性：支持分页、过滤和排序，适应数据量增长
• 安全性：严格的认证授权机制和输入验证

REST API资源设计最佳实践

URL结构规范

REST API的URL设计应遵循简洁、一致的原则，采用名词复数形式表示资源集合，使用kebab-case命名多词资源：

# 推荐的URL结构
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# 子资源表示关系
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

避免在URL中使用动词，如/api/v1/getUsers或/api/v1/deleteUser/123，这些操作应通过HTTP方法来表达。

命名规则

良好的命名习惯能够提高API的可读性和可维护性：

# 推荐做法
/api/v1/team-members          # 使用kebab-case命名多词资源
/api/v1/orders?status=active  # 使用查询参数进行过滤
/api/v1/users/123/orders      # 使用嵌套资源表示所有权关系

# 不推荐做法
/api/v1/getUsers              # URL中包含动词
/api/v1/user                  # 使用单数形式（应使用复数）
/api/v1/team_members          # 使用snake_case（应使用kebab-case）

分页实现策略

分页是处理大量数据集合的关键技术，Everything Claude Code提供了两种主要的分页实现方式：

基于偏移量的分页（简单实现）

适用于小型数据集和管理后台，支持跳转到任意页码：

GET /api/v1/users?page=2&per_page=20

# 实现方式
SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 20;

优点：实现简单，支持跳转到指定页码
缺点：大数据集下性能较差，数据插入时可能导致结果不一致

基于游标的分页（高性能实现）

适用于大型数据集和无限滚动场景，性能稳定且结果一致：

GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20

# 实现方式
SELECT * FROM users
WHERE id > :cursor_id
ORDER BY id ASC
LIMIT 21;  -- 获取额外一条记录以判断是否有下一页

分页响应格式示例：

{
  "data": [...],
  "meta": {
    "has_next": true,
    "next_cursor": "eyJpZCI6MTQzfQ"
  }
}

优点：性能稳定，不受数据集大小影响，支持并发插入
缺点：无法跳转到任意页码，游标通常是不透明的加密字符串

分页策略选择指南

使用场景	推荐分页类型
管理后台、小型数据集(<10K)	偏移量分页
无限滚动、大型数据集	游标分页
公共API	游标分页(默认) + 偏移量分页(可选)
搜索结果	偏移量分页(用户期望页码导航)

错误响应设计

一致的错误响应格式能够显著提高API的易用性，帮助开发者快速定位问题。Everything Claude Code采用以下错误响应结构：

标准错误响应格式

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "invalid_format"
      },
      {
        "field": "age",
        "message": "Must be between 0 and 150",
        "code": "out_of_range"
      }
    ]
  }
}

HTTP状态码使用指南

正确使用HTTP状态码能够提高API的语义清晰度：

# 成功响应
200 OK                    — GET, PUT, PATCH (带响应体)
201 Created               — POST (包含Location头)
204 No Content            — DELETE, PUT (无响应体)

# 客户端错误
400 Bad Request           — 验证失败，格式错误
401 Unauthorized          — 认证缺失或无效
403 Forbidden             — 认证通过但权限不足
404 Not Found             — 资源不存在
409 Conflict              — 数据冲突，如重复条目
422 Unprocessable Entity  — 语义错误（JSON格式正确但数据无效）
429 Too Many Requests     — 超出速率限制

# 服务器错误
500 Internal Server Error — 意外错误（绝不要暴露详细信息）
502 Bad Gateway           — 上游服务失败
503 Service Unavailable   — 服务暂时不可用，包含Retry-After头

常见错误用法示例：

# 错误示例：所有响应都使用200状态码
{ "status": 200, "success": false, "error": "Not found" }

# 正确示例：使用语义化HTTP状态码
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "User not found" } }

实用实现示例

分页中间件实现（Node.js/Express）

// 分页中间件
const paginate = (req, res, next) => {
  const page = parseInt(req.query.page) || 1;
  const perPage = Math.min(parseInt(req.query.per_page) || 20, 100); // 限制最大每页数量
  const offset = (page - 1) * perPage;
  
  req.pagination = { page, perPage, offset };
  next();
};

// 使用示例
router.get('/users', paginate, async (req, res) => {
  const { page, perPage, offset } = req.pagination;
  const [users, total] = await Promise.all([
    User.find().limit(perPage).skip(offset),
    User.countDocuments()
  ]);
  
  res.json({
    data: users,
    meta: {
      total,
      page,
      per_page: perPage,
      total_pages: Math.ceil(total / perPage)
    },
    links: {
      self: `/api/v1/users?page=${page}&per_page=${perPage}`,
      next: page * perPage < total ? `/api/v1/users?page=${page + 1}&per_page=${perPage}` : null,
      prev: page > 1 ? `/api/v1/users?page=${page - 1}&per_page=${perPage}` : null
    }
  });
});

错误处理中间件（Node.js/Express）

// 错误处理中间件
const errorHandler = (err, req, res, next) => {
  // 验证错误
  if (err.name === 'ValidationError') {
    return res.status(422).json({
      error: {
        code: 'validation_error',
        message: 'Request validation failed',
        details: Object.values(err.errors).map(e => ({
          field: e.path,
          message: e.message,
          code: e.kind
        }))
      }
    });
  }
  
  // 资源未找到
  if (err.name === 'NotFoundError') {
    return res.status(404).json({
      error: {
        code: 'not_found',
        message: err.message
      }
    });
  }
  
  // 默认服务器错误（不暴露内部细节）
  console.error(err); // 记录错误详情
  res.status(500).json({
    error: {
      code: 'internal_error',
      message: 'An unexpected error occurred'
    }
  });
};

API设计检查清单

在发布新API端点前，建议使用以下检查清单确保质量：

•  资源URL遵循命名约定（复数、kebab-case、无动词）
•  使用正确的HTTP方法（GET用于读取，POST用于创建等）
•  返回适当的状态码（不使用200表示所有响应）
•  使用模式验证输入（如Zod、Pydantic、Bean Validation）
•  错误响应遵循包含代码和消息的标准格式
•  列表端点实现分页（游标或偏移量）
•  已配置认证（或明确标记为公开）
•  已检查授权（用户只能访问自己的资源）
•  已配置速率限制
•  响应不泄露内部细节（堆栈跟踪、SQL错误）
•  与现有端点命名一致（camelCase vs snake_case）
•  已更新文档（OpenAPI/Swagger规范）

总结

良好的API设计是构建成功应用程序的基础。通过遵循本文介绍的REST API设计原则、分页策略和错误处理最佳实践，开发者可以构建出高效、可靠且易于使用的API接口。Everything Claude Code项目提供了丰富的API设计资源和示例，包括详细的设计模式和实现代码，可参考skills/api-design/SKILL.md获取更多信息。

无论是开发新API还是改进现有API，都应始终以一致性、易用性和可扩展性为目标，不断优化API设计，提升用户体验。

【免费下载链接】everything-claude-code Complete Claude Code configuration collection - agents, skills, hooks, commands, rules, MCPs. Battle-tested configs from an Anthropic hackathon winner. 项目地址: https://gitcode.com/GitHub_Trending/ev/everything-claude-code