用途
本技能面向 API 的设计与规范制定，帮助开发者构建一致、直观且能在不破坏现有客户端的前提下持续演进的接口。其核心是「API 设计三法则」：可预测（贯穿始终的一致模式）、可发现（自文档化、命名直观）、可演进（可在不破坏客户端的情况下变更）。
技能倡导 API-First 思维，推荐流程为：设计 → 文档 → 模拟 → 构建 → 测试 → 部署，而非先构建、再补文档、最后期待它能正常工作。
主要能力
REST 模式
- 资源命名：集合与单项资源的路径设计，支持嵌套资源，以及在 CRUD 不适用时使用动作式端点（如 /users/{id}/activate、/orders/{id}/cancel）。
- 命名约定：使用复数名词、小写与连字符；避免在 URL 中使用动词、/getUsers 这类形式、camelCase 或下划线。
- HTTP 方法：GET 读取（幂等且安全）、POST 创建、PUT 替换（幂等）、PATCH 更新（设计得当时可幂等）、DELETE 删除（幂等）。
- 状态码：200、201、204、400、401、403、404、409、422、429、500 的语义与使用时机。
请求与响应模式
- 请求体示例（如 email、name、preferences）。
- 单项资源响应结构：包含 data、id、type、attributes、relationships。
- 集合响应结构：包含 data 数组、meta（total、page、perPage）与 links（self、next、last）。
- 错误响应结构：包含 error.code、message、details（字段级错误）与 requestId。
分页模式
- 偏移量分页：简单熟悉，但与实时数据不一致，大数据集上较慢。
- 游标分页：一致且性能好，但无法直接跳到第 N 页；响应中包含 before/after 游标与 hasMore。
- 键集分页：性能很好，但需要可排序的唯一字段。
过滤、排序与搜索
- 过滤：单值、多值（逗号分隔）、操作符（如 created_at[gte]、name[contains]）以及嵌套字段过滤。
- 排序：单字段、降序（-createdAt）、多字段。
- 字段选择：fields=id,name,email，以及按资源类型选择字段。
- 搜索：q 或 search 参数。
版本控制策略
- URL 路径（推荐用于主版本）：显式且可缓存，但会造成 URL 膨胀。
- 请求头：URL 干净，但测试较难、可见性较低。
- 查询参数：易于测试，但破坏缓存且 URL 膨胀。
- 弃用模式：通过 Deprecation、Sunset、Link（rel="successor-version"）响应头声明。
认证模式
- API Key（请求头形式；查询参数形式应避免，因为会记录在 URL 中）。
- Bearer Token（OAuth2/JWT）。
- 请求签名（AWS 风格，HMAC-SHA256，含 SignedHeaders 与 Signature）。
限流
- 响应头：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、Retry-After。
- 429 响应体：包含 error.code（RATE_LIMITED）、message、retryAfter。
- 策略：固定窗口、滑动窗口、令牌桶（允许突发）、漏桶（恒定速率）。
GraphQL 模式
- Schema 设计：User、Post、PostConnection（edges、pageInfo）、Query、Mutation 的类型定义。
- 命名约定：类型用 PascalCase，字段与参数用 camelCase，枚举用 SCREAMING_SNAKE，变更用「动词+名词」（如 createUser、updatePost）。
- 错误处理：响应中 data 与 errors 并列，errors 项包含 message、locations、path 与 extensions（如 code、timestamp）。
OpenAPI 文档
提供 OpenAPI 3.0.3 的基础结构示例，包含 info、servers、paths（含参数与响应引用）、components/schemas（如 User 的 id、email 定义）。
使用方式
技能以模式与规范形式提供，可直接作为团队接口设计的参考约定；具体调用方式与安装命令资料中暂未提供。
适用场景
- 制定团队统一的 REST 或 GraphQL 接口规范。
- 规划 API 版本演进与弃用策略。
- 设计分页、过滤、排序、错误响应与限流方案。
- 编写 OpenAPI/Swagger 文档。
限制
资料未提供本技能的具体安装方式、运行环境、依赖条件、收费信息与实际效果验证，暂未提供相关说明。