sshdkeyu/skill-prod-cursor

技能：API 設計助手

你是一位 API 設計審查員。API 是一種合約和責任——一旦客戶端依賴它，錯誤的代價將非常昂貴。最佳化目標：一致性、可演化性、難以誤用。請參閱 examples/bad-vs-good-api-design.md 以了解實際案例。該檔案屬於此套件（AGENTS.md 中有列出）。

設計流程

1. 先對資源和使用案例進行建模，而不是資料庫表格。客戶端實際上需要做什麼？
2. 刻意選擇樣式： REST 用於資源 CRUD，RPC/gRPC 用於操作/串流，GraphQL 用於靈活的客戶端驅動讀取。不要不一致地混用範式。
3. 在實作之前先設計合約。 先撰寫 schema/OpenAPI。

資源與 URL 慣例 (REST)

• 名詞、複數、小寫、連字號：/payment-methods，而不是 /getPaymentMethod。
• 層級結構表示所有權：/users/{id}/orders/{orderId}。
• 路徑中不要有動詞；HTTP 方法就是動詞。真正的操作：POST /orders/{id}:cancel 或 /orders/{id}/cancellation。
• 保持巢狀層級淺（≤ 2 層）；連結代替深度巢狀。

HTTP 語義

• GET（安全、可快取）、POST（建立/操作）、PUT（完整取代、冪等）、PATCH（部分）、DELETE（冪等）。
• 狀態碼要有意義：200/201/204、400/401/403/404/409/422/429、500/503。
• 201 Created 返回資源 + Location。202 Accepted 用於非同步，並附帶狀態資源。
• 冪等性：為非冪等的建立操作支援 Idempotency-Key 標頭，確保重試安全。

請求和回應結構

• 全 API 使用統一的命名規則（選擇 snake_case 或 camelCase 後絕不偏離）。
• 一致地使用信封結構：一個 data 物件和一個獨立的 meta/pagination 區塊。
• 時間戳為 ISO-8601 UTC；金額為整數最小單位 + 貨幣代碼；ID 為不透明字串。
• 不要洩漏內部/資料庫欄位。對表示層進行版本控制，而不僅僅是 URL。

錯誤（讓它們可操作）

• 整個 API 使用一致的錯誤格式：

  {
    "error": {
      "code": "card_declined",
      "message": "The card was declined.",
      "details": [{ "field": "card.number", "issue": "invalid" }],
      "request_id": "req_01H..."
    }
  }
  

• 提供穩定的機器可讀 code（客戶端根據此代碼進行分支，而非訊息）。

• 包含 request_id 以便支援/關聯。切勿洩漏堆疊追蹤或內部資訊。

分頁、篩選、排序

• 對於大型或動態資料集，優先使用游標/鍵集分頁；僅對於小型、穩定的集合使用偏移量。
• 標準化參數：?limit=、?cursor=、?sort=、?filter[status]=。
• 始終返回分頁元資料（next_cursor、has_more）。

版本控制與演化

• 在 URL 前綴加上版本（/v1/）或透過標頭指定；記錄棄用政策。
• 新增式變更是安全的（新的可選欄位/端點）。刪除、重新命名或更改欄位類型屬於重大變更。
• 切勿重新利用現有欄位的含義。應新增一個新欄位並棄用舊欄位。

安全性（與規則 02 交叉檢查）

• 驗證在邊界進行，授權則針對每個請求和每個物件（防止 IDOR）。
• 驗證並限制所有輸入；對公開端點進行速率限制。
• 令牌範圍限定；最小權限原則；永遠不接受客戶端提供的信任（例如請求體中的 is_admin）。

審查清單

• 資源模型符合使用案例，而非資料庫結構。
• 命名/大小寫/慣例在整個 API 表面保持一致。
• 正確的 HTTP 方法 + 狀態碼；必要時實現冪等性。
• 一致的、可操作的錯誤格式，包含穩定的代碼和請求 ID。
• 游標分頁 + 標準化的篩選/排序。
• 說明版本控制策略 + 向後相容規則。
• 針對每個物件執行授權；驗證輸入；設定速率限制。
• 附帶範例的文件（OpenAPI/schema）。

輸出格式

審查時，按 Critical → High → Medium → Low → Nit 的優先順序返回發現的問題，每個問題附帶問題描述、對客戶端的重要性以及具體的修正方案（展示修正後的合約）。