tanstack-query

本技能為 TanStack Query v5 提供全面的實作指南，專注於現代 React 應用程式中高效的非同步狀態管理。它專為需要處理複雜伺服器狀態、資料擷取和快取失效的工程師設計。本技能涵蓋了從 v4 到 v5 的遷移過程，包括單一物件 Hook 簽章、gcTime 配置以及移除舊版回呼屬性。它作為查詢鍵工廠、樂觀更新和 SSR 整合等架構模式的中心化參考，確保 SPA 與 Next.js 或 Remix 等框架的一致性效能。

• 實作標準化的查詢鍵工廠，以防止快取鍵衝突並確保型別安全。

• 配置生產等級的預設值，包括 staleTime、gcTime 和重試邏輯，以減少伺服器負載並提升使用者體驗。

• 提供進階變異工作流的模式，包括樂觀 UI 更新以及透過 QueryCache 全域回呼實現的強健錯誤處理。

• 支援伺服器端渲染 (SSR) 與資料串流，整合 @tanstack/react-query-next-experimental。

• 支援一等公民級的 Suspense 整合，實現宣告式的載入狀態與資料擷取。

• 最適合使用 React 18+ 且需要高效能資料同步與背景重新擷取的專案。

• 使用此技能透過執行提供的 codemod 指令來進行自動匯入更新，以遷移遺留實作。

• 輸入通常包含 API 端點定義與資料擷取函式；輸出則是為您的特定架構需求所配置的結構化 React Hooks。

• 請注意，v5 的個別 Hook 已移除 onSuccess、onError 和 onSettled 回呼；請利用全域 queryCache 處理器來避免重複執行副作用。

• 請確保嚴格遵守所提供的「伺服器 vs 用戶端」配置對照表，以優化 SSR 環境中的邊緣情況處理。