api-design

api-design 技能為構建強大、可擴展且標準化的後端服務提供了結構化的框架。它專為後端工程師和系統架構師而設計，確保 API 的一致性、可維護性以及客戶端與伺服器組件之間的清晰溝通。無論您是在構建新的微服務、實作 GraphQL schema，還是重構現有的 REST 端點，此技能都能透過行業標準的設計模式，協助您減少技術債並提升開發速度。

• 資源導向架構：強制使用複數名詞和邏輯資源巢狀結構，嚴格避免在 URL 中使用動詞，以保持 RESTful 路徑的可預測性。

• HTTP 方法對齊：驗證正確使用 GET、POST、PUT、PATCH 和 DELETE 動詞，並強調冪等性以確保系統作業安全。

• 標準化回應模式：實作一致的資料包裝、分頁元資料欄位，以及使用適當 HTTP 狀態碼的統一錯誤報告結構。

• 進階查詢能力：利用標準化查詢參數，簡化強大的篩選、排序、欄位選取和搜尋機制的設計。

• API 生命周期管理：支援有效的版本控制策略（包括基於 URL 和 Header 的版本控制），並提供 OpenAPI 3.0/Swagger 文件模板。

• GraphQL 最佳實踐：提供 schema 設計模式、輸入驗證、自訂錯誤處理以及類型安全的 mutation 結構。

• 常見輸入包括新資源的技術需求、資料庫 schema 定義或需要現代化的舊版 API 端點。

• 常見輸出包括乾淨的路由定義、OpenAPI YAML 文件、JSON 回應契約，以及分頁或驗證處理程序的實作藍圖。

• 使用者應遵守既定的命名規範（小寫/連字號），以確保團隊間 API 的一致性。

• 實作複雜篩選時，請善用所提供的範圍篩選模式（如 created_gte、price_min），以保持系統的可預測性。

• 確保所有錯誤回應都能提供可執行的詳細資訊，例如錯誤代碼和欄位層級訊息，並避免洩漏敏感的內部堆疊追蹤或資料庫細節。