该技能面向 REST API 的设计与维护，提供一套可执行的规范与示例。
用途： 适用于设计新的 REST API、审查或重构现有端点、定义错误响应、分页或版本控制策略、编写 OpenAPI/Swagger 文档，以及实现 HATEOAS 或限流。
主要能力按主题分为六部分：
-
资源命名：以表格给出 GET/POST/PUT/PATCH/DELETE 集合、单资源、子集合等模式的示例。规则包括使用复数名词而非动词（/users 而非 /getUsers）、统一使用 kebab-case 或 snake_case 而不混用、按归属而非便利嵌套且最多两层、仅对非 CRUD 操作用动词（如 POST /orders/42/cancel）。
-
版本控制：比较 URI 路径（GET /v1/users，显式、可缓存、易路由，但破坏性变更污染 URL）、Header（Accept: application/vnd.myapp.v1+json，URL 干净、内容协商，但发现难、缓存复杂）、查询参数（GET /users?version=1，易测试但污染查询空间、不友好缓存）三种策略。建议公共 API 用 URI 路径，内部或微服务用 Header。
-
错误处理：采用 RFC 9457（application/problem+json），给出包含 type、title、status、detail、instance、timestamp 的示例，并列出 HTTP 状态码语义对照（400、401、403、404、409、422、429、500），强调不得用 5xx 表示客户端错误或用 4xx 表示服务端故障。
-
分页：游标分页适合大数据集，示例为 GET /users?cursor=...&limit=20，响应含 data 与 pagination.next/limit；偏移分页适合小型或管理数据集，示例为 GET /users?page=1&size=20，响应含 page、size、total、total_pages。
-
HATEOAS：响应中通过 _links 提供 self、cancel、pay 等链接及 method，客户端无需硬编码 URL；提及 Spring Boot 依赖 org.springframework.boot:spring-boot-starter-hateoas。
-
限流与文档：比较令牌桶（固定速率、允许突发，通用）、滑动窗口（滚动时间窗、严格限流）、漏桶（平滑输出、队列处理）三种策略，给出 X-RateLimit-Limit/Remaining/Reset 响应头；OpenAPI 部分使用 springdoc-openapi（springdoc-openapi-starter-webmvc-ui 用于 Boot 3+），并给出 @Operation、@ApiResponse、@Parameter 注解示例，要求为每个端点添加注解而非依赖自动生成名称。
使用方式： 按上述六部分逐项对照设计或审查接口；运行命令方面，可用 curl localhost:8080/v3/api-docs | jq . 在运行时生成 OpenAPI 规格，或打开 http://localhost:8080/swagger-ui.html 查看 UI。
反模式清单： 每条路由都加 /api 前缀（应交给 api.example.com 或网关处理）、嵌套资源超过三层、以 200 返回错误体、生产环境泄漏堆栈跟踪（用 @ControllerAdvice 清理）、无版本或迁移窗口就破坏现有客户端、URL 中使用动词如 /getAllUsers。
适用场景与限制： 适合 REST API 设计与文档化；正文以 Spring Boot 生态示例为主，其他框架需自行适配；游标与偏移分页的取舍、版本策略的选择依赖具体场景，资料给出的是建议而非强制；未提供该技能的安装、收费或运行平台信息。