[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BF7PR5G4D51777B6JYA0KY":3,"skill-same:01M7BF7PR5G4D51777B6JYA0KY":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7BF7PR5G4D51777B6JYA0KY","api-design",null,"REST API设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制。","YYC-Cube\u002FYYC3-Knowledge-Base","YYC-Cube","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F235006543?v=4","01M79J2PH4SWD2X0825X6PN748","yyc3","01M79J2PHVK3F6ZBYT8K2SCZCW",1,"MIT","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-AI-应用工具\u002FYYC3-AI-应用工具-Everything-claude-code\u002Fdocs\u002Fzh-CN\u002Fskills\u002Fapi-design\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: api-design\ndescription: REST API设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制。\norigin: ECC\n---\n\n# API 设计模式\n\n用于设计一致、对开发者友好的 REST API 的约定和最佳实践。\n\n## 何时启用\n\n* 设计新的 API 端点时\n* 审查现有的 API 契约时\n* 添加分页、过滤或排序功能时\n* 为 API 实现错误处理时\n* 规划 API 版本策略时\n* 构建面向公众或合作伙伴的 API 时\n\n## 资源设计\n\n### URL 结构\n\n```\n# 资源使用名词、复数、小写、短横线连接\nGET    \u002Fapi\u002Fv1\u002Fusers\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPOST   \u002Fapi\u002Fv1\u002Fusers\nPUT    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPATCH  \u002Fapi\u002Fv1\u002Fusers\u002F:id\nDELETE \u002Fapi\u002Fv1\u002Fusers\u002F:id\n\n# 用于关系的子资源\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\nPOST   \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\n\n# 非 CRUD 映射的操作（谨慎使用动词）\nPOST   \u002Fapi\u002Fv1\u002Forders\u002F:id\u002Fcancel\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Flogin\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Frefresh\n```\n\n### 命名规则\n\n```\n# 良好\n\u002Fapi\u002Fv1\u002Fteam-members          # 多单词资源使用 kebab-case\n\u002Fapi\u002Fv1\u002Forders?status=active  # 查询参数用于过滤\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002Forders      # 嵌套资源表示所有权关系\n\n# 不良\n\u002Fapi\u002Fv1\u002FgetUsers              # URL 中包含动词\n\u002Fapi\u002Fv1\u002Fuser                  # 使用单数形式（应使用复数）\n\u002Fapi\u002Fv1\u002Fteam_members          # URL 中使用 snake_case\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002FgetOrders   # 嵌套资源路径中包含动词\n```\n\n## HTTP 方法和状态码\n\n### 方法语义\n\n| 方法 | 幂等性 | 安全性 | 用途 |\n|--------|-----------|------|---------|\n| GET | 是 | 是 | 检索资源 |\n| POST | 否 | 否 | 创建资源，触发操作 |\n| PUT | 是 | 否 | 完全替换资源 |\n| PATCH | 否\\* | 否 | 部分更新资源 |\n| DELETE | 是 | 否 | 删除资源 |\n\n\\*通过适当的实现，PATCH 可以实现幂等\n\n### 状态码参考\n\n```\n# 成功\n200 OK                    — GET、PUT、PATCH（包含响应体）\n201 Created               — POST（包含 Location 头部）\n204 No Content            — DELETE、PUT（无响应体）\n\n# 客户端错误\n400 Bad Request           — 验证失败、JSON 格式错误\n401 Unauthorized          — 缺少或无效的身份验证\n403 Forbidden             — 已认证但未授权\n404 Not Found             — 资源不存在\n409 Conflict              — 重复条目、状态冲突\n422 Unprocessable Entity  — 语义无效（JSON 格式正确但数据错误）\n429 Too Many Requests     — 超出速率限制\n\n# 服务器错误\n500 Internal Server Error — 意外故障（切勿暴露细节）\n502 Bad Gateway           — 上游服务失败\n503 Service Unavailable   — 临时过载，需包含 Retry-After 头部\n```\n\n### 常见错误\n\n```\n# 错误：对所有请求都返回 200\n{ \"status\": 200, \"success\": false, \"error\": \"Not found\" }\n\n# 正确：按语义使用 HTTP 状态码\nHTTP\u002F1.1 404 Not Found\n{ \"error\": { \"code\": \"not_found\", \"message\": \"User not found\" } }\n\n# 错误：验证错误返回 500\n# 正确：返回 400 或 422 并包含字段级详情\n\n# 错误：创建资源返回 200\n# 正确：返回 201 并包含 Location 标头\nHTTP\u002F1.1 201 Created\nLocation: \u002Fapi\u002Fv1\u002Fusers\u002Fabc-123\n```\n\n## 响应格式\n\n### 成功响应\n\n```json\n{\n  \"data\": {\n    \"id\": \"abc-123\",\n    \"email\": \"alice@example.com\",\n    \"name\": \"Alice\",\n    \"created_at\": \"2025-01-15T10:30:00Z\"\n  }\n}\n```\n\n### 集合响应（带分页）\n\n```json\n{\n  \"data\": [\n    { \"id\": \"abc-123\", \"name\": \"Alice\" },\n    { \"id\": \"def-456\", \"name\": \"Bob\" }\n  ],\n  \"meta\": {\n    \"total\": 142,\n    \"page\": 1,\n    \"per_page\": 20,\n    \"total_pages\": 8\n  },\n  \"links\": {\n    \"self\": \"\u002Fapi\u002Fv1\u002Fusers?page=1&per_page=20\",\n    \"next\": \"\u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\",\n    \"last\": \"\u002Fapi\u002Fv1\u002Fusers?page=8&per_page=20\"\n  }\n}\n```\n\n### 错误响应\n\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Request validation failed\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"message\": \"Must be a valid email address\",\n        \"code\": \"invalid_format\"\n      },\n      {\n        \"field\": \"age\",\n        \"message\": \"Must be between 0 and 150\",\n        \"code\": \"out_of_range\"\n      }\n    ]\n  }\n}\n```\n\n### 响应包装器变体\n\n```typescript\n\u002F\u002F Option A: Envelope with data wrapper (recommended for public APIs)\ninterface ApiResponse\u003CT> {\n  data: T;\n  meta?: PaginationMeta;\n  links?: PaginationLinks;\n}\n\ninterface ApiError {\n  error: {\n    code: string;\n    message: string;\n    details?: FieldError[];\n  };\n}\n\n\u002F\u002F Option B: Flat response (simpler, common for internal APIs)\n\u002F\u002F Success: just return the resource directly\n\u002F\u002F Error: return error object\n\u002F\u002F Distinguish by HTTP status code\n```\n\n## 分页\n\n### 基于偏移量（简单）\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\n\n# 实现\nSELECT * FROM users\nORDER BY created_at DESC\nLIMIT 20 OFFSET 20;\n```\n\n**优点：** 易于实现，支持“跳转到第 N 页”\n**缺点：** 在大偏移量时速度慢（例如 OFFSET 100000），并发插入时结果不一致\n\n### 基于游标（可扩展）\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?cursor=eyJpZCI6MTIzfQ&limit=20\n\n# 实现\nSELECT * FROM users\nWHERE id > :cursor_id\nORDER BY id ASC\nLIMIT 21;  -- 多取一条以判断是否有下一页\n```\n\n```json\n{\n  \"data\": [...],\n  \"meta\": {\n    \"has_next\": true,\n    \"next_cursor\": \"eyJpZCI6MTQzfQ\"\n  }\n}\n```\n\n**优点：** 无论位置如何，性能一致；在并发插入时结果稳定\n**缺点：** 无法跳转到任意页面；游标是不透明的\n\n### 何时使用哪种\n\n| 用例 | 分页类型 |\n|----------|----------------|\n| 管理仪表板，小数据集 (\u003C10K) | 偏移量 |\n| 无限滚动，信息流，大数据集 | 游标 |\n| 公共 API | 游标（默认）配合偏移量（可选） |\n| 搜索结果 | 偏移量（用户期望有页码） |\n\n## 过滤、排序和搜索\n\n### 过滤\n\n```\n# 简单相等\nGET \u002Fapi\u002Fv1\u002Forders?status=active&customer_id=abc-123\n\n# 比较运算符（使用括号表示法）\nGET \u002Fapi\u002Fv1\u002Fproducts?price[gte]=10&price[lte]=100\nGET \u002Fapi\u002Fv1\u002Forders?created_at[after]=2025-01-01\n\n# 多个值（逗号分隔）\nGET \u002Fapi\u002Fv1\u002Fproducts?category=electronics,clothing\n\n# 嵌套字段（点表示法）\nGET \u002Fapi\u002Fv1\u002Forders?customer.country=US\n```\n\n### 排序\n\n```\n# 单字段排序（前缀 - 表示降序）\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-created_at\n\n# 多字段排序（逗号分隔）\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-featured,price,-created_at\n```\n\n### 全文搜索\n\n```\n# 搜索查询参数\nGET \u002Fapi\u002Fv1\u002Fproducts?q=wireless+headphones\n\n# 字段特定搜索\nGET \u002Fapi\u002Fv1\u002Fusers?email=alice\n```\n\n### 稀疏字段集\n\n```\n# 仅返回指定字段（减少负载）\nGET \u002Fapi\u002Fv1\u002Fusers?fields=id,name,email\nGET \u002Fapi\u002Fv1\u002Forders?fields=id,total,status&include=customer.name\n```\n\n## 认证和授权\n\n### 基于令牌的认证\n\n```\n# Bearer token in Authorization header\nGET \u002Fapi\u002Fv1\u002Fusers\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n\n# API key (for server-to-server)\nGET \u002Fapi\u002Fv1\u002Fdata\nX-API-Key: sk_live_abc123\n```\n\n### 授权模式\n\n```typescript\n\u002F\u002F Resource-level: check ownership\napp.get(\"\u002Fapi\u002Fv1\u002Forders\u002F:id\", async (req, res) => {\n  const order = await Order.findById(req.params.id);\n  if (!order) return res.status(404).json({ error: { code: \"not_found\" } });\n  if (order.userId !== req.user.id) return res.status(403).json({ error: { code: \"forbidden\" } });\n  return res.json({ data: order });\n});\n\n\u002F\u002F Role-based: check permissions\napp.delete(\"\u002Fapi\u002Fv1\u002Fusers\u002F:id\", requireRole(\"admin\"), async (req, res) => {\n  await User.delete(req.params.id);\n  return res.status(204).send();\n});\n```\n\n## 速率限制\n\n### 响应头\n\n```\nHTTP\u002F1.1 200 OK\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 95\nX-RateLimit-Reset: 1640000000\n\n# 超出限制时\nHTTP\u002F1.1 429 Too Many Requests\nRetry-After: 60\n{\n  \"error\": {\n    \"code\": \"rate_limit_exceeded\",\n    \"message\": \"Rate limit exceeded. Try again in 60 seconds.\"\n  }\n}\n```\n\n### 速率限制层级\n\n| 层级 | 限制 | 时间窗口 | 用例 |\n|------|-------|--------|----------|\n| 匿名用户 | 30\u002F分钟 | 每个 IP | 公共端点 |\n| 认证用户 | 100\u002F分钟 | 每个用户 | 标准 API 访问 |\n| 高级用户 | 1000\u002F分钟 | 每个 API 密钥 | 付费 API 套餐 |\n| 内部服务 | 10000\u002F分钟 | 每个服务 | 服务间调用 |\n\n## 版本控制\n\n### URL 路径版本控制（推荐）\n\n```\n\u002Fapi\u002Fv1\u002Fusers\n\u002Fapi\u002Fv2\u002Fusers\n```\n\n**优点：** 明确，易于路由，可缓存\n**缺点：** 版本间 URL 会变化\n\n### 请求头版本控制\n\n```\nGET \u002Fapi\u002Fusers\nAccept: application\u002Fvnd.myapp.v2+json\n```\n\n**优点：** URL 简洁\n**缺点：** 测试更困难，容易忘记\n\n### 版本控制策略\n\n```\n1. 从 \u002Fapi\u002Fv1\u002F 开始 —— 除非必要，否则不要急于版本化\n2. 最多同时维护 2 个活跃版本（当前版本 + 前一个版本）\n3. 弃用时间线：\n   - 宣布弃用（公共 API 需提前 6 个月通知）\n   - 添加 Sunset 响应头：Sunset: Sat, 01 Jan 2026 00:00:00 GMT\n   - 在弃用日期后返回 410 Gone 状态\n4. 非破坏性变更无需创建新版本：\n   - 向响应中添加新字段\n   - 添加新的可选查询参数\n   - 添加新的端点\n5. 破坏性变更需要创建新版本：\n   - 移除或重命名字段\n   - 更改字段类型\n   - 更改 URL 结构\n   - 更改身份验证方法\n```\n\n## 实现模式\n\n### TypeScript (Next.js API 路由)\n\n```typescript\nimport { z } from \"zod\";\nimport { NextRequest, NextResponse } from \"next\u002Fserver\";\n\nconst createUserSchema = z.object({\n  email: z.string().email(),\n  name: z.string().min(1).max(100),\n});\n\nexport async function POST(req: NextRequest) {\n  const body = await req.json();\n  const parsed = createUserSchema.safeParse(body);\n\n  if (!parsed.success) {\n    return NextResponse.json({\n      error: {\n        code: \"validation_error\",\n        message: \"Request validation failed\",\n        details: parsed.error.issues.map(i => ({\n          field: i.path.join(\".\"),\n          message: i.message,\n          code: i.code,\n        })),\n      },\n    }, { status: 422 });\n  }\n\n  const user = await createUser(parsed.data);\n\n  return NextResponse.json(\n    { data: user },\n    {\n      status: 201,\n      headers: { Location: `\u002Fapi\u002Fv1\u002Fusers\u002F${user.id}` },\n    },\n  );\n}\n```\n\n### Python (Django REST Framework)\n\n```python\nfrom rest_framework import serializers, viewsets, status\nfrom rest_framework.response import Response\n\nclass CreateUserSerializer(serializers.Serializer):\n    email = serializers.EmailField()\n    name = serializers.CharField(max_length=100)\n\nclass UserSerializer(serializers.ModelSerializer):\n    class Meta:\n        model = User\n        fields = [\"id\", \"email\", \"name\", \"created_at\"]\n\nclass UserViewSet(viewsets.ModelViewSet):\n    serializer_class = UserSerializer\n    permission_classes = [IsAuthenticated]\n\n    def get_serializer_class(self):\n        if self.action == \"create\":\n            return CreateUserSerializer\n        return UserSerializer\n\n    def create(self, request):\n        serializer = CreateUserSerializer(data=request.data)\n        serializer.is_valid(raise_exception=True)\n        user = UserService.create(**serializer.validated_data)\n        return Response(\n            {\"data\": UserSerializer(user).data},\n            status=status.HTTP_201_CREATED,\n            headers={\"Location\": f\"\u002Fapi\u002Fv1\u002Fusers\u002F{user.id}\"},\n        )\n```\n\n### Go (net\u002Fhttp)\n\n```go\nfunc (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {\n    var req CreateUserRequest\n    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {\n        writeError(w, http.StatusBadRequest, \"invalid_json\", \"Invalid request body\")\n        return\n    }\n\n    if err := req.Validate(); err != nil {\n        writeError(w, http.StatusUnprocessableEntity, \"validation_error\", err.Error())\n        return\n    }\n\n    user, err := h.service.Create(r.Context(), req)\n    if err != nil {\n        switch {\n        case errors.Is(err, domain.ErrEmailTaken):\n            writeError(w, http.StatusConflict, \"email_taken\", \"Email already registered\")\n        default:\n            writeError(w, http.StatusInternalServerError, \"internal_error\", \"Internal error\")\n        }\n        return\n    }\n\n    w.Header().Set(\"Location\", fmt.Sprintf(\"\u002Fapi\u002Fv1\u002Fusers\u002F%s\", user.ID))\n    writeJSON(w, http.StatusCreated, map[string]any{\"data\": user})\n}\n```\n\n## API 设计清单\n\n发布新端点前请检查：\n\n* \\[ ] 资源 URL 遵循命名约定（复数、短横线连接、不含动词）\n* \\[ ] 使用了正确的 HTTP 方法（GET 用于读取，POST 用于创建等）\n* \\[ ] 返回了适当的状态码（不要所有情况都返回 200）\n* \\[ ] 使用模式（Zod, Pydantic, Bean Validation）验证了输入\n* \\[ ] 错误响应遵循带代码和消息的标准格式\n* \\[ ] 列表端点实现了分页（游标或偏移量）\n* \\[ ] 需要认证（或明确标记为公开）\n* \\[ ] 检查了授权（用户只能访问自己的资源）\n* \\[ ] 配置了速率限制\n* \\[ ] 响应未泄露内部细节（堆栈跟踪、SQL 错误）\n* \\[ ] 与现有端点命名一致（camelCase 对比 snake\\_case）\n* \\[ ] 已记录（更新了 OpenAPI\u002FSwagger 规范）\n","# API 设计模式\n\n用于设计一致、对开发者友好的 REST API 的约定和最佳实践。\n\n## 何时启用\n\n* 设计新的 API 端点时\n* 审查现有的 API 契约时\n* 添加分页、过滤或排序功能时\n* 为 API 实现错误处理时\n* 规划 API 版本策略时\n* 构建面向公众或合作伙伴的 API 时\n\n## 资源设计\n\n### URL 结构\n\n```\n# 资源使用名词、复数、小写、短横线连接\nGET    \u002Fapi\u002Fv1\u002Fusers\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPOST   \u002Fapi\u002Fv1\u002Fusers\nPUT    \u002Fapi\u002Fv1\u002Fusers\u002F:id\nPATCH  \u002Fapi\u002Fv1\u002Fusers\u002F:id\nDELETE \u002Fapi\u002Fv1\u002Fusers\u002F:id\n\n# 用于关系的子资源\nGET    \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\nPOST   \u002Fapi\u002Fv1\u002Fusers\u002F:id\u002Forders\n\n# 非 CRUD 映射的操作（谨慎使用动词）\nPOST   \u002Fapi\u002Fv1\u002Forders\u002F:id\u002Fcancel\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Flogin\nPOST   \u002Fapi\u002Fv1\u002Fauth\u002Frefresh\n```\n\n### 命名规则\n\n```\n# 良好\n\u002Fapi\u002Fv1\u002Fteam-members          # 多单词资源使用 kebab-case\n\u002Fapi\u002Fv1\u002Forders?status=active  # 查询参数用于过滤\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002Forders      # 嵌套资源表示所有权关系\n\n# 不良\n\u002Fapi\u002Fv1\u002FgetUsers              # URL 中包含动词\n\u002Fapi\u002Fv1\u002Fuser                  # 使用单数形式（应使用复数）\n\u002Fapi\u002Fv1\u002Fteam_members          # URL 中使用 snake_case\n\u002Fapi\u002Fv1\u002Fusers\u002F123\u002FgetOrders   # 嵌套资源路径中包含动词\n```\n\n## HTTP 方法和状态码\n\n### 方法语义\n\n| 方法 | 幂等性 | 安全性 | 用途 |\n|--------|-----------|------|---------|\n| GET | 是 | 是 | 检索资源 |\n| POST | 否 | 否 | 创建资源，触发操作 |\n| PUT | 是 | 否 | 完全替换资源 |\n| PATCH | 否\\* | 否 | 部分更新资源 |\n| DELETE | 是 | 否 | 删除资源 |\n\n\\*通过适当的实现，PATCH 可以实现幂等\n\n### 状态码参考\n\n```\n# 成功\n200 OK                    — GET、PUT、PATCH（包含响应体）\n201 Created               — POST（包含 Location 头部）\n204 No Content            — DELETE、PUT（无响应体）\n\n# 客户端错误\n400 Bad Request           — 验证失败、JSON 格式错误\n401 Unauthorized          — 缺少或无效的身份验证\n403 Forbidden             — 已认证但未授权\n404 Not Found             — 资源不存在\n409 Conflict              — 重复条目、状态冲突\n422 Unprocessable Entity  — 语义无效（JSON 格式正确但数据错误）\n429 Too Many Requests     — 超出速率限制\n\n# 服务器错误\n500 Internal Server Error — 意外故障（切勿暴露细节）\n502 Bad Gateway           — 上游服务失败\n503 Service Unavailable   — 临时过载，需包含 Retry-After 头部\n```\n\n### 常见错误\n\n```\n# 错误：对所有请求都返回 200\n{ \"status\": 200, \"success\": false, \"error\": \"Not found\" }\n\n# 正确：按语义使用 HTTP 状态码\nHTTP\u002F1.1 404 Not Found\n{ \"error\": { \"code\": \"not_found\", \"message\": \"User not found\" } }\n\n# 错误：验证错误返回 500\n# 正确：返回 400 或 422 并包含字段级详情\n\n# 错误：创建资源返回 200\n# 正确：返回 201 并包含 Location 标头\nHTTP\u002F1.1 201 Created\nLocation: \u002Fapi\u002Fv1\u002Fusers\u002Fabc-123\n```\n\n## 响应格式\n\n### 成功响应\n\n```json\n{\n  \"data\": {\n    \"id\": \"abc-123\",\n    \"email\": \"alice@example.com\",\n    \"name\": \"Alice\",\n    \"created_at\": \"2025-01-15T10:30:00Z\"\n  }\n}\n```\n\n### 集合响应（带分页）\n\n```json\n{\n  \"data\": [\n    { \"id\": \"abc-123\", \"name\": \"Alice\" },\n    { \"id\": \"def-456\", \"name\": \"Bob\" }\n  ],\n  \"meta\": {\n    \"total\": 142,\n    \"page\": 1,\n    \"per_page\": 20,\n    \"total_pages\": 8\n  },\n  \"links\": {\n    \"self\": \"\u002Fapi\u002Fv1\u002Fusers?page=1&per_page=20\",\n    \"next\": \"\u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\",\n    \"last\": \"\u002Fapi\u002Fv1\u002Fusers?page=8&per_page=20\"\n  }\n}\n```\n\n### 错误响应\n\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Request validation failed\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"message\": \"Must be a valid email address\",\n        \"code\": \"invalid_format\"\n      },\n      {\n        \"field\": \"age\",\n        \"message\": \"Must be between 0 and 150\",\n        \"code\": \"out_of_range\"\n      }\n    ]\n  }\n}\n```\n\n### 响应包装器变体\n\n```typescript\n\u002F\u002F Option A: Envelope with data wrapper (recommended for public APIs)\ninterface ApiResponse\u003CT> {\n  data: T;\n  meta?: PaginationMeta;\n  links?: PaginationLinks;\n}\n\ninterface ApiError {\n  error: {\n    code: string;\n    message: string;\n    details?: FieldError[];\n  };\n}\n\n\u002F\u002F Option B: Flat response (simpler, common for internal APIs)\n\u002F\u002F Success: just return the resource directly\n\u002F\u002F Error: return error object\n\u002F\u002F Distinguish by HTTP status code\n```\n\n## 分页\n\n### 基于偏移量（简单）\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?page=2&per_page=20\n\n# 实现\nSELECT * FROM users\nORDER BY created_at DESC\nLIMIT 20 OFFSET 20;\n```\n\n**优点：** 易于实现，支持“跳转到第 N 页”\n**缺点：** 在大偏移量时速度慢（例如 OFFSET 100000），并发插入时结果不一致\n\n### 基于游标（可扩展）\n\n```\nGET \u002Fapi\u002Fv1\u002Fusers?cursor=eyJpZCI6MTIzfQ&limit=20\n\n# 实现\nSELECT * FROM users\nWHERE id > :cursor_id\nORDER BY id ASC\nLIMIT 21;  -- 多取一条以判断是否有下一页\n```\n\n```json\n{\n  \"data\": [...],\n  \"meta\": {\n    \"has_next\": true,\n    \"next_cursor\": \"eyJpZCI6MTQzfQ\"\n  }\n}\n```\n\n**优点：** 无论位置如何，性能一致；在并发插入时结果稳定\n**缺点：** 无法跳转到任意页面；游标是不透明的\n\n### 何时使用哪种\n\n| 用例 | 分页类型 |\n|----------|----------------|\n| 管理仪表板，小数据集 (\u003C10K) | 偏移量 |\n| 无限滚动，信息流，大数据集 | 游标 |\n| 公共 API | 游标（默认）配合偏移量（可选） |\n| 搜索结果 | 偏移量（用户期望有页码） |\n\n## 过滤、排序和搜索\n\n### 过滤\n\n```\n# 简单相等\nGET \u002Fapi\u002Fv1\u002Forders?status=active&customer_id=abc-123\n\n# 比较运算符（使用括号表示法）\nGET \u002Fapi\u002Fv1\u002Fproducts?price[gte]=10&price[lte]=100\nGET \u002Fapi\u002Fv1\u002Forders?created_at[after]=2025-01-01\n\n# 多个值（逗号分隔）\nGET \u002Fapi\u002Fv1\u002Fproducts?category=electronics,clothing\n\n# 嵌套字段（点表示法）\nGET \u002Fapi\u002Fv1\u002Forders?customer.country=US\n```\n\n### 排序\n\n```\n# 单字段排序（前缀 - 表示降序）\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-created_at\n\n# 多字段排序（逗号分隔）\nGET \u002Fapi\u002Fv1\u002Fproducts?sort=-featured,price,-created_at\n```\n\n### 全文搜索\n\n```\n# 搜索查询参数\nGET \u002Fapi\u002Fv1\u002Fproducts?q=wireless+headphones\n\n# 字段特定搜索\nGET \u002Fapi\u002Fv1\u002Fusers?email=alice\n```\n\n### 稀疏字段集\n\n```\n# 仅返回指定字段（减少负载）\nGET \u002Fapi\u002Fv1\u002Fusers?fields=id,name,email\nGET \u002Fapi\u002Fv1\u002Forders?fields=id,total,status&include=customer.name\n```\n\n## 认证和授权\n\n### 基于令牌的认证\n\n```\n# Bearer token in Authorization header\nGET \u002Fapi\u002Fv1\u002Fusers\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n\n# API key (for server-to-server)\nGET \u002Fapi\u002Fv1\u002Fdata\nX-API-Key: sk_live_abc123\n```\n\n### 授权模式\n\n```typescript\n\u002F\u002F Resource-level: check ownership\napp.get(\"\u002Fapi\u002Fv1\u002Forders\u002F:id\", async (req, res) => {\n  const order = await Order.findById(req.params.id);\n  if (!order) return res.status(404).json({ error: { code: \"not_found\" } });\n  if (order.userId !== req.user.id) return res.status(403).json({ error: { code: \"forbidden\" } });\n  return res.json({ data: order });\n});\n\n\u002F\u002F Role-based: check permissions\napp.delete(\"\u002Fapi\u002Fv1\u002Fusers\u002F:id\", requireRole(\"admin\"), async (req, res) => {\n  await User.delete(req.params.id);\n  return res.status(204).send();\n});\n```\n\n## 速率限制\n\n### 响应头\n\n```\nHTTP\u002F1.1 200 OK\nX-RateLimit-Limit: 100\nX-RateLimit-Remaining: 95\nX-RateLimit-Reset: 1640000000\n\n# 超出限制时\nHTTP\u002F1.1 429 Too Many Requests\nRetry-After: 60\n{\n  \"error\": {\n    \"code\": \"rate_limit_exceeded\",\n    \"message\": \"Rate limit exceeded. Try again in 60 seconds.\"\n  }\n}\n```\n\n### 速率限制层级\n\n| 层级 | 限制 | 时间窗口 | 用例 |\n|------|-------|--------|----------|\n| 匿名用户 | 30\u002F分钟 | 每个 IP | 公共端点 |\n| 认证用户 | 100\u002F分钟 | 每个用户 | 标准 API 访问 |\n| 高级用户 | 1000\u002F分钟 | 每个 API 密钥 | 付费 API 套餐 |\n| 内部服务 | 10000\u002F分钟 | 每个服务 | 服务间调用 |\n\n## 版本控制\n\n### URL 路径版本控制（推荐）\n\n```\n\u002Fapi\u002Fv1\u002Fusers\n\u002Fapi\u002Fv2\u002Fusers\n```\n\n**优点：** 明确，易于路由，可缓存\n**缺点：** 版本间 URL 会变化\n\n### 请求头版本控制\n\n```\nGET \u002Fapi\u002Fusers\nAccept: application\u002Fvnd.myapp.v2+json\n```\n\n**优点：** URL 简洁\n**缺点：** 测试更困难，容易忘记\n\n### 版本控制策略\n\n```\n1. 从 \u002Fapi\u002Fv1\u002F 开始 —— 除非必要，否则不要急于版本化\n2. 最多同时维护 2 个活跃版本（当前版本 + 前一个版本）\n3. 弃用时间线：\n   - 宣布弃用（公共 API 需提前 6 个月通知）\n   - 添加 Sunset 响应头：Sunset: Sat, 01 Jan 2026 00:00:00 GMT\n   - 在弃用日期后返回 410 Gone 状态\n4. 非破坏性变更无需创建新版本：\n   - 向响应中添加新字段\n   - 添加新的可选查询参数\n   - 添加新的端点\n5. 破坏性变更需要创建新版本：\n   - 移除或重命名字段\n   - 更改字段类型\n   - 更改 URL 结构\n   - 更改身份验证方法\n```\n\n## 实现模式\n\n### TypeScript (Next.js API 路由)\n\n```typescript\nimport { z } from \"zod\";\nimport { NextRequest, NextResponse } from \"next\u002Fserver\";\n\nconst createUserSchema = z.object({\n  email: z.string().email(),\n  name: z.string().min(1).max(100),\n});\n\nexport async function POST(req: NextRequest) {\n  const body = await req.json();\n  const parsed = createUserSchema.safeParse(body);\n\n  if (!parsed.success) {\n    return NextResponse.json({\n      error: {\n        code: \"validation_error\",\n        message: \"Request validation failed\",\n        details: parsed.error.issues.map(i => ({\n          field: i.path.join(\".\"),\n          message: i.message,\n          code: i.code,\n        })),\n      },\n    }, { status: 422 });\n  }\n\n  const user = await createUser(parsed.data);\n\n  return NextResponse.json(\n    { data: user },\n    {\n      status: 201,\n      headers: { Location: `\u002Fapi\u002Fv1\u002Fusers\u002F${user.id}` },\n    },\n  );\n}\n```\n\n### Python (Django REST Framework)\n\n```python\nfrom rest_framework import serializers, viewsets, status\nfrom rest_framework.response import Response\n\nclass CreateUserSerializer(serializers.Serializer):\n    email = serializers.EmailField()\n    name = serializers.CharField(max_length=100)\n\nclass UserSerializer(serializers.ModelSerializer):\n    class Meta:\n        model = User\n        fields = [\"id\", \"email\", \"name\", \"created_at\"]\n\nclass UserViewSet(viewsets.ModelViewSet):\n    serializer_class = UserSerializer\n    permission_classes = [IsAuthenticated]\n\n    def get_serializer_class(self):\n        if self.action == \"create\":\n            return CreateUserSerializer\n        return UserSerializer\n\n    def create(self, request):\n        serializer = CreateUserSerializer(data=request.data)\n        serializer.is_valid(raise_exception=True)\n        user = UserService.create(**serializer.validated_data)\n        return Response(\n            {\"data\": UserSerializer(user).data},\n            status=status.HTTP_201_CREATED,\n            headers={\"Location\": f\"\u002Fapi\u002Fv1\u002Fusers\u002F{user.id}\"},\n        )\n```\n\n### Go (net\u002Fhttp)\n\n```go\nfunc (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {\n    var req CreateUserRequest\n    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {\n        writeError(w, http.StatusBadRequest, \"invalid_json\", \"Invalid request body\")\n        return\n    }\n\n    if err := req.Validate(); err != nil {\n        writeError(w, http.StatusUnprocessableEntity, \"validation_error\", err.Error())\n        return\n    }\n\n    user, err := h.service.Create(r.Context(), req)\n    if err != nil {\n        switch {\n        case errors.Is(err, domain.ErrEmailTaken):\n            writeError(w, http.StatusConflict, \"email_taken\", \"Email already registered\")\n        default:\n            writeError(w, http.StatusInternalServerError, \"internal_error\", \"Internal error\")\n        }\n        return\n    }\n\n    w.Header().Set(\"Location\", fmt.Sprintf(\"\u002Fapi\u002Fv1\u002Fusers\u002F%s\", user.ID))\n    writeJSON(w, http.StatusCreated, map[string]any{\"data\": user})\n}\n```\n\n## API 设计清单\n\n发布新端点前请检查：\n\n* \\[ ] 资源 URL 遵循命名约定（复数、短横线连接、不含动词）\n* \\[ ] 使用了正确的 HTTP 方法（GET 用于读取，POST 用于创建等）\n* \\[ ] 返回了适当的状态码（不要所有情况都返回 200）\n* \\[ ] 使用模式（Zod, Pydantic, Bean Validation）验证了输入\n* \\[ ] 错误响应遵循带代码和消息的标准格式\n* \\[ ] 列表端点实现了分页（游标或偏移量）\n* \\[ ] 需要认证（或明确标记为公开）\n* \\[ ] 检查了授权（用户只能访问自己的资源）\n* \\[ ] 配置了速率限制\n* \\[ ] 响应未泄露内部细节（堆栈跟踪、SQL 错误）\n* \\[ ] 与现有端点命名一致（camelCase 对比 snake\\_case）\n* \\[ ] 已记录（更新了 OpenAPI\u002FSwagger 规范）\n",{"name":5,"origin":24,"description":7},"ECC","main","87afe6ce96220accf50a345dea46784c8c9f210e","YYC3-AI-应用工具\u002FYYC3-AI-应用工具-Everything-claude-code\u002Fdocs\u002Fzh-CN\u002Fskills\u002Fapi-design",0,"https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base","https:\u002F\u002Fkb.yyc3.top\u002F","https:\u002F\u002Fgithub.com\u002FYYC-Cube","万象归元于云枢 | 深栈智启新纪元","2026-11-10 10:37:32",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill api-design",{"tool":40,"command":41},"bunx","bunx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill api-design",{"tool":43,"command":44},"pnpm","pnpm dlx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill api-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-AI-应用工具\u002FYYC3-AI-应用工具-Everything-claude-code\u002Fdocs\u002Fzh-CN\u002Fskills\u002Fapi-design\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7CTDWHERCXPQCP0K03A86AS","vercel-sandbox","Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include \"Vercel Sandbox browser\", \"microVM Chrome\", \"agent-browser in sandbox\", \"browser automation on Vercel\", or any task requiring Chrome in a Vercel Sandbox.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fvercel-sandbox\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7CTD8D2BNJY54S65M47HEJA","slack","Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include \"check my Slack\", \"what channels have unreads\", \"send a message to\", \"search Slack for\", \"extract from Slack\", \"find who said\", or any task requiring programmatic Slack interaction.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fslack\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7CTCSSB8ZP3Q58C3YZDZK1W","electron","Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include \"automate Slack app\", \"control VS Code\", \"interact with Discord app\", \"test this Electron app\", \"connect to desktop app\", or any task requiring automation of a native Electron application.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Felectron\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7CTCBJY76688V4DCZGWFHGQ","dogfood","Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to \"dogfood\", \"QA\", \"exploratory test\", \"find issues\", \"bug hunt\", \"test this app\u002Fsite\u002Fplatform\", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fdogfood\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7CTC4H0FFGVEAQR9PA4GA1A","agent-browser","Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to \"open a website\", \"fill out a form\", \"click a button\", \"take a screenshot\", \"scrape data from a page\", \"test this web app\", \"login to a site\", \"automate browser actions\", or any task requiring programmatic web interaction.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fagent-browser\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7CTBKVFYBG78FDSABSDJTTQ","shadcn","Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn\u002Fui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for \"shadcn init\", \"create an app with --preset\", \"switch to --preset\", and for building a design system or applying a DESIGN.md or brand spec to shadcn\u002Fui.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-UI-界面组件\u002FYYC3-UI-界面组件-ui\u002Fskills\u002Fshadcn\u002FSKILL.md",[],[]]