前言¶
接口写到第十个版本，团队里通常会出现这些情况：同一个资源一会儿叫 /api/createUser，一会儿叫 /api/users；创建成功返回 200，删掉也返回 200；分页有的用 page/page_size，有的用游标，前端每个模块各写一套解析；错误响应结构更是一人一个样，前端只能写 if-else 去猜。根因不是某个程序员不细心，是团队缺少一份明确、可执行的 API 设计规范。
下面介绍 API Design Principles，一个按 REST 与 GraphQL 最佳实践评审或设计 API 的 Skill。
这是什么¶
API Design Principles 是 wpank 发布在 ClawHub 上的 Skill，坐标 @clawhub_wpank/api-design-principles，当前版本 1.0.0，分类 dev-programming，经 SkillHub 收录。它解决的问题是：在设计新接口、评审已有接口规范、给团队定标准这几个场景里，给出统一、可执行的设计约定。官方简介是”设计清晰、可扩展的 REST 与 GraphQL API”，覆盖资源建模、HTTP 方法、分页、错误处理、版本控制与 Schema 最佳实践。
该 Skill 不需要 API Key（requires_api_key=false），是纯提示词规范类的 Skill，不依赖外部工具链。
核心功能¶
按官方 SKILL.md，能力分四块。
REST 设计¶
- 资源命名：集合用复数名词，不写动词；嵌套最多两层
- HTTP 方法与状态码：给出常用方法的语义表和完整状态码分类（成功、客户端错误、服务端错误）
- 分页：偏移分页与游标分页两种模式，附响应结构示例
- 过滤、排序、搜索与字段选择的查询参数写法
- 统一的错误响应结构
- 版本化策略：URL 版本与 Header 版本的取舍，以及弃用流程
- 限流：响应头约定与实现思路
GraphQL 设计¶
- Schema 结构与命名约定
- Relay 风格的分页类型（Connection / Edge / PageInfo）
- Input / Payload 模式的 Mutation
- 用 DataLoader 解决 N+1 查询
- 查询保护：深度限制、复杂度限制、超时
REST 与 GraphQL 的决策框架¶
官方给出一张对照表，按场景选择范式：简单 CRUD、公开 API、重缓存选 REST；复杂嵌套数据、客户端精确取数、聚合多数据源选 GraphQL。
团队规范输出¶
Skill 的定位不是给单个接口挑毛病，而是产出可执行的设计规范，可作为团队评审的检查清单。
安装与启用¶
官方仓库给出的安装命令如下：
openclaw skills install @wpank/api-design-principles
这是上游 ClawHub 仓库页面展示的 CLI 命令。安装后按 SKILL.md 的 WHEN 场景触发即可，即在需要设计或评审 API 时把 Skill 纳入上下文，把接口需求或现有接口定义交给它处理。
典型用法¶
官方列出了五个适用场景，可直接作为使用入口：
- 设计新的 REST 或 GraphQL API
- 实现前评审 API 规范
- 为团队制定 API 设计标准
- 为提升可用性重构已有 API
- 在 API 范式之间迁移
评审类用法示例：把现有的 OpenAPI 文档或接口清单交给 Skill，让它按命名、状态码、分页、错误格式逐项检查。例如发现以下写法时：
POST /api/createUser ← 动词出现在 URL 里
POST /api/users ← 正确写法，方法本身就是动词
以及这种过深的嵌套：
GET /api/users/{id}/orders/{orderId}/items/{itemId}/reviews ← 太深
GET /api/order-items/{id}/reviews ← 更好
Skill 会按规则指出问题并给出改写建议。设计类用法示例：说明业务需求后，让 Skill 先出决策框架（REST 还是 GraphQL），再产出资源命名、端点清单、分页方式和错误结构的完整约定，可直接沉淀为团队规范文档。
适用场景与注意¶
适合这几类人：后端与全栈开发者、API 平台的接口负责人、需要给团队立规范的技术管理者。
需要说明的限制：
- 它是评审与规范类 Skill，输出的是设计约定和检查清单，不替代 OpenAPI 代码生成、网关配置这类工程工具。
- Skill 给出的分页大小、查询深度上限、复杂度上限、限流阈值都是示例值，上线前要按业务数据量和性能实测调整，不能直接照抄。
- 版本化弃用周期（官方建议 6 到 12 个月）是通用约定，具体时长要结合调用方迁移情况定。
结尾¶
API Design Principles 的价值不在于给出一份”正确但空泛”的规范列表，而是把命名、状态码、分页、错误、版本化这些每个团队都会撞上的问题，固化成可以直接照着做、可以拿去做评审的约定。官方地址：https://api.skillhub.cn/user_f4fc8899/api-design-principles，上游仓库：https://clawhub.ai/wpank/api-design-principles。
