用途
该技能面向 REST API 设计，提供一套用于构建一致、对开发者友好的 API 的约定与最佳实践。它适用于以下场景：设计新的 API 端点、评审现有 API 契约、为接口添加分页/过滤/排序、实现 API 错误处理、规划 API 版本化策略，以及构建面向公众或合作伙伴的 API。
主要能力
资源设计
URL 结构遵循“资源为名词、复数、小写、kebab-case”的原则。示例：
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
# 不映射到 CRUD 的动作（谨慎使用动词）
POST /api/v1/orders/:id/cancel
POST /api/v1/auth/login
POST /api/v1/auth/refresh
命名规则中，推荐使用 kebab-case 表示多词资源、查询参数用于过滤、嵌套资源表示归属关系；避免在 URL 中使用动词、单数形式、snake_case 或在嵌套资源中使用动词。
HTTP 方法与状态码
方法语义：GET 幂等且安全，用于检索资源；POST 非幂等非安全，用于创建资源或触发动作；PUT 幂等非安全，用于完整替换资源；PATCH 非幂等（正确实现可幂等），用于部分更新；DELETE 幂等非安全，用于删除资源。
状态码参考：成功类包括 200 OK（GET、PUT、PATCH 带响应体）、201 Created（POST，包含 Location 头）、204 No Content（DELETE、PUT 无响应体）；客户端错误包括 400 Bad Request（校验失败、JSON 格式错误）、401 Unauthorized（缺少或无效认证）、403 Forbidden（已认证但未授权）、404 Not Found（资源不存在）、409 Conflict（重复条目、状态冲突）、422 Unprocessable Entity（语义无效）、429 Too Many Requests（超出限流）；服务端错误包括 500 Internal Server Error（不暴露细节）、502 Bad Gateway（上游服务失败）、503 Service Unavailable（临时过载，包含 Retry-After）。
常见错误包括：对所有情况返回 200、对校验错误返回 500、对已创建资源返回 200 而非 201。
响应格式
成功响应使用 data 包装，集合响应包含 data、meta（total、page、per_page、total_pages）和 links（self、next、last）。错误响应包含 error 对象，其中有 code、message 和可选的 details 数组（每个字段错误含 field、message、code）。
响应信封有两种变体：Option A 为带 data 包装的信封（推荐用于公共 API），Option B 为扁平响应（更简单，常用于内部 API），通过 HTTP 状态码区分成功与错误。
分页
偏移分页：GET /api/v1/users?page=2&per_page=20，实现简单，支持跳转到第 N 页，但大偏移量时性能差，并发插入时不一致。
游标分页：GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20，性能与位置无关，并发插入时稳定，但无法跳转到任意页，游标不透明。
选择建议：管理后台、小数据集（<10K）用偏移；无限滚动、信息流、大数据集用游标；公共 API 默认游标、可选偏移；搜索结果用偏移（用户期望页码）。
过滤、排序与搜索
过滤支持简单相等、比较运算符（方括号表示法）、多值（逗号分隔）、嵌套字段（点表示法）。排序支持单字段（前缀 - 表示降序）和多字段（逗号分隔）。全文搜索使用 q 参数，也支持字段特定搜索。稀疏字段集通过 fields 参数返回指定字段以减少负载。
认证与授权
支持 Bearer token（Authorization 头）和 API key（X-API-Key 头，用于服务间通信）。授权模式包括资源级检查（检查归属）和基于角色的权限检查。
限流
响应头包含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset；超出时返回 429 和 Retry-After。限流层级示例：匿名 30/分钟（按 IP）、已认证 100/分钟（按用户）、高级 1000/分钟（按 API key）、内部 10000/分钟（按服务）。
版本化
推荐 URL 路径版本化（/api/v1/users、/api/v2/users），显式、易路由、可缓存；也支持头版本化（Accept: application/vnd.myapp.v2+json），URL 干净但更难测试。版本策略：从 /api/v1/ 开始，最多维护 2 个活跃版本，弃用时间线（公共 API 提前 6 个月通知，添加 Sunset 头，日落后返回 410 Gone）。非破坏性变更无需新版本（添加字段、可选查询参数、新端点）；破坏性变更需要新版本（删除或重命名字段、更改字段类型、更改 URL 结构、更改认证方式）。
使用方式
该技能以约定和代码示例形式提供，包含 TypeScript（Next.js API Route）、Python（Django REST Framework）和 Go（net/http）的实现模式示例，可直接参考用于对应技术栈。还提供发布新端点前的 API 设计检查清单，涵盖资源 URL 命名、HTTP 方法、状态码、输入校验、错误响应格式、分页、认证、授权、限流、响应不泄露内部细节、命名一致性以及文档（OpenAPI/Swagger）更新。
适用场景
适用于设计新 API 端点、评审现有 API 契约、添加分页/过滤/排序、实现 API 错误处理、规划 API 版本化策略，以及构建面向公众或合作伙伴的 API。
限制
资料未提供该技能的安装方式、运行环境要求、收费信息或具体平台支持范围，这些内容暂未提供。