api-integration

api-integration 技能為後端 OpenAPI 規格與 React 前端架構之間提供了一個強大的橋樑。透過利用 apidog-mcp-server，它為 API 定義建立了單一事實來源，確保 AI 代理程式生成準確且型別安全的程式碼，並與後端保持同步。此技能專為優先考慮可維護性並希望消除編寫 HTTP 請求、型別定義與複雜資料獲取邏輯之瑣碎工作（boilerplate）的工程團隊而設計。

• 自動化型別生成：與 openapi-typescript 和 orval 整合，直接從 OpenAPI 3.0/3.1 規格產生精確的 TypeScript 介面，減少執行時期錯誤與 schema 不匹配的情況。

• 查詢層編排：使用 TanStack Query 鉤子實作結構化的資料夾模式（queries/mutations），包含查詢鍵（query key）工廠、快取配置與 stale time 管理，以優化資料獲取效率。

• 韌性 HTTP 客戶端：配置基於 axios 的客戶端，包含用於自動 JWT/Bearer Token 管理與 Token 更新流程的攔截器（interceptors），可妥善處理 401 錯誤以維持會話持久性。

• 基於 MCP 的配置：透過 .claude/mcp.json 支援動態配置，使代理程式能夠讀取基於本機檔案的規格或遠端 URL，並透過平行的 MCP 伺服器定義支援多 API 專案。

• 設定專案時，請在 MCP 配置中定義 API 規格來源（URL 或本機路徑），以確保代理程式擁有對 schema 的讀取權限。

• 依照建議的 types.ts、client.ts 以及基於功能的 query/mutation 檔案模式，在 /src/api 目錄中組織 API 相關程式碼。

• 結合 Zod schemas 與 OpenAPI 定義，為來自後端的資料提供執行時期的驗證。

• 代理程式能夠適應各種身分驗證策略；請確保客戶端攔截器已針對您的特定身分驗證中介軟體需求進行調整。

• 對於大型 API，請依賴 orval 等自動化程式碼生成工具，而非手寫型別，以最大程度減少 API 合約與前端實作之間的落差。