router-query-integration

Router × Query Integration 技能是為 React 開發人員設計的專業工作流組件，專注於構建高效能單頁應用 (SPA)。此技能解決了消除請求瀑布流 (request waterfalls) 並提升路由轉換時感知效能的挑戰，透過將路由級資料擷取與全域查詢狀態管理同步來達成目標。它主要針對使用 TanStack Router 和 TanStack Query 的團隊，提供標準化且具備型別安全的資料編排方案。透過在組件渲染前使用路由載入器 (loaders) 啟動資料擷取，使用者可確保導航過程流暢，同時保有快取去重複與 stale-while-revalidate 模式的優勢。此技能涵蓋了多種實作策略，從簡單的查詢預擷取到複雜的相依請求與並行載入，並確保透過整合路由器錯誤邊界與 suspense 組件實現穩健的錯誤處理。

• 使用 ensureQueryData、prefetchQuery 與 fetchQuery 模式實作路由級資料預擷取。

• 利用路由載入器內的 Promise.all 實現資料並行載入，以最大化導航期間的處理效率。

• 透過 Query Options 模式 (queryOptions) 強化型別安全與程式碼重複利用。

• 管理相依查詢，處理後續資料請求依賴於先前載入器資料的場景。

• 提供變更 (mutation) 後手動清除快取的模式，確保 UI 狀態與伺服器保持同步。

• 支援開發階段除錯，協助自動掛載 Router 與 Query Client 的開發者工具。

• 輸入包括 React 路由定義、現有的 TanStack Query 客戶端，以及用於資料擷取的 API 服務函式。

• 輸出包含優化的載入器配置與查詢整合模式，旨在最小化請求延遲。

• 開發人員應集中定義查詢鍵 (query keys) 以確保應用程式整體的快取一致性。

• 當頁面渲染必須依賴資料時，建議使用 ensureQueryData 以防止不必要的重複擷取。

• 利用 staleTime 配置來平衡資料新鮮度需求與網路效能。

• 務必將路由級載入器與組件層中的 React Query hooks 搭配使用，以維護對即時資料狀態與後台自動更新功能的存取。