RESTful API 设计规范

先说清楚它解决什么问题

REST 接口写起来容易，写好很难。常见的翻车现场包括：资源命名一会儿是 /getUserList，一会儿是 /user/query；版本号直接烧进 URL，却没有人负责兼容；错误响应有十种结构，调用方只能靠猜；鉴权方式在 API Key、OAuth2、JWT 之间反复横跳，直到上线才发现 token 刷新没人处理。更隐蔽的是破坏性更新——字段悄悄改成可选、状态码从 400 变成 422，调用方在几周后才开始报错。

这个 Skill 怎么工作

它按四个核心方法组织，每一项都能单独套用，也可以当成自查清单：

• REST 资源命名与版本策略：以资源为中心建模，用集合名词而不是动词，版本走兼容演进路径，而不是每次改结构就从 v1 全量重开到 v2。
• 统一错误码、分页与限流约定：让 401、403、429 各自承担明确语义，分页参数和响应体结构保持一致，限流策略可预期。
• 鉴权选型对比：API Key、OAuth2、JWT 各自的适用场景，避免把「能用」当成「该用」。
• 文档与变更管理：接口变更有记录、有通知、有过渡期，破坏性更新不靠口头约定。

使用时先明确场景边界，再逐项执行或自查，最后输出结构化的清单、分级或建议，并标注需要人工复核的不确定项。附带的 references/速查卡.md 适合放在手边随时查。

适用边界

规范属于通用建议，具体业务需要自己权衡兼容性与演进节奏。它不连接外部系统、不拉取实时数据，因此不适合高频自动化任务；也不替代法律、医疗、财税等需要持牌专业人士给出的确定性结论。