tanstack-query-best-practices 是做什麼的？
TanStack Query (React Query) 在資料擷取、快取、突變及伺服器狀態管理方面的最佳實踐。適用於建構依賴伺服器狀態的資料驅動型 React 應用程式時啟用。
查詢鍵設計
- 使用結構化陣列作為查詢鍵，以唯一識別查詢。
- 第一層為描述查詢範圍的字串（例如
'todos'、'users'）。 - 第二層包含查詢參數（例如
{ status: 'done' }、id）。 - 確保查詢鍵序列化後能一致地代表查詢相依性。
預設查詢選項
- 透過
QueryClient設定全域預設值，例如staleTime、gcTime和retry。 staleTime應根據資料變更頻率設定：靜態資料設較長時間（例如 5 分鐘），頻繁變動的資料設較短時間（例如 10 秒）。- 對不常讀取的資料啟用
refetchOnWindowFocus，但若資料在應用程式中已足夠新，則考慮關閉。
平行與相依查詢
- 使用
useQueries鉤子平行執行多個獨立查詢。 - 對相依查詢，使用條件性
enabled選項，僅在前置查詢成功後才啟動後續查詢。
分頁與無限查詢
- 使用
useQuery配合參數式查詢鍵處理分頁。 - 使用
useInfiniteQuery處理「載入更多」或無限滾動場景。 - 在
getNextPageParam中正確傳回cursor或pageParam。
突變與樂觀更新
- 使用
useMutation處理寫入操作。 - 在
onMutate中執行樂觀更新，並在onError中回滾。 - 使用
queryClient.invalidateQueries在成功後重新擷取相關查詢。 - 避免在
onSettled中同時重新擷取，以免競態條件。
錯誤處理與載入狀態
- 使用
isLoading（首次載入且無資料）與isFetching（任何擷取動作）的區別。 - 在元件層級使用
error與isError優雅地顯示錯誤。 - 考慮將全域錯誤處理加入
QueryClient的defaultOptions中。
防止競態條件
- 讓 TanStack Query 透過查詢鍵管理並行請求。
- 使用
keepPreviousData選項在分頁時維持舊資料顯示。 - 避免手動取代查詢快取，除非必要。
開發工具
- 加入
ReactQueryDevtools以在開發過程中檢查查詢狀態。 - 僅在開發環境中條件式渲染。
效能優化
- 使用
select選項從快取資料中轉換或提取部分資料。 - 避免在查詢鍵中使用內建物件，使用穩定參考。
- 對靜態資料或低優先級更新考慮設定
notifyOnChangeProps: ['data']。
資料庫與 API 整合
- 將
queryFn包裝在一個唯一致力於資料擷取的層級中（例如 API 函式庫）。 - 在查詢層級處理特殊錯誤代碼（例如 401 執行重導向、403 顯示權限錯誤）。
- 對長時間輪詢或 WebSocket 更新考慮設定
refetchInterval。