前言¶
接口寫到第十個版本，團隊裏通常會出現這些情況：同一個資源一會兒叫 /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。
