用途
API Designer 是一个用于设计 REST 和 GraphQL API 的架构技能，目标是帮助构建健壮、可扩展、可维护的 API。它会在以下场景激活：设计新 API、审查 API 设计、改进现有 API、创建 API 规范。
主要能力
REST API 设计原则
-
资源导向设计：推荐使用
GET /users、POST /users、GET /users/{id}、PATCH /users/{id}、DELETE /users/{id}这类以资源为中心的路径；避免POST /getUsers、POST /users/create、GET /users/get/{id}等冗余或方法误用形式。 -
HTTP 方法语义：GET 安全且幂等，用于读取资源；POST 非安全非幂等，用于创建资源；PUT 非安全但幂等，用于替换资源；PATCH 非安全非幂等，用于更新资源；DELETE 非安全但幂等，用于删除资源。
-
状态码：200 用于成功的 GET、PATCH、DELETE；201 用于成功的 POST；204 用于无响应体的成功 DELETE；400 表示输入无效；401 表示缺少或无效认证；403 表示已认证但未授权；404 表示资源不存在；409 表示资源已存在；422 表示语法有效但语义错误；429 表示超出速率限制；500 表示服务器错误。
-
命名约定：URL 使用 kebab-case（如
/user-preferences）；JSON 使用 camelCase（如{"userId": "123"}）；查询参数使用 snake_case 或 camelCase（如?page_size=10）。 -
分页：示例为
GET /users?page=1&page_size=20，响应包含data数组和pagination对象，其中含page、page_size、total、total_pages。 -
过滤与排序：示例为
GET /users?status=active&sort=-created_at,name，其中-created_at表示降序，name表示升序。
GraphQL API 设计
Schema 设计示例包含 Query 类型（user、users）、Mutation 类型（createUser、updateUser）、User 类型、UserConnection、UserEdge、PageInfo 等。最佳实践包括：默认使用非空类型，仅在合适时使用可空；列表使用基于游标的分页（Connections）；使用 mutation payload 实现一致的错误处理；为所有类型和字段编写描述。
API 版本控制
提供两种方式：URL 版本控制（推荐，如 /api/v1/users、/api/v2/users）和 Header 版本控制（如 Accept: application/vnd.myapi.v2+json）。版本控制指南包括：从 v1 开始；尽可能保持向后兼容；弃用旧版本时提前通知；记录破坏性变更。
认证与授权
认证方式包括 JWT Bearer Token（Authorization: Bearer <token>）、API Key（X-API-Key: <key>）、OAuth 2.0（Authorization: Bearer <access_token>）。授权方面建议使用角色/权限，记录每个端点所需权限，授权失败返回 403。
速率限制
响应头示例包含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。推荐限制：公共 API 每小时 100–1000 次请求；已认证 API 每小时 1000–10000 次请求；Webhook 每分钟 10–100 次请求。
文档要求
所有端点均需文档化，包含请求/响应示例、认证要求、错误响应格式、速率限制，以及可用的 SDK 示例。
使用方式
该技能附带脚本：
生成 API 脚手架：
python3 scripts/generate_api.py --name <resource-name> --output api-design.md
校验 API 设计：
python3 scripts/validate_api.py --input api-design.md
参考文档包括 references/rest-patterns.md（REST 设计模式）和 references/graphql-patterns.md（GraphQL 设计模式），以及 REST API Tutorial 和 GraphQL Best Practices 等外部参考。
适用场景
适合需要设计新 REST 或 GraphQL API、审查现有 API 设计、改进已有 API、编写 API 规范文档的开发与架构场景。
限制
资料未提供该技能的具体运行环境要求、依赖版本、脚本的完整参数说明、错误处理细节，以及是否支持除 REST 和 GraphQL 之外的其他 API 风格。