使用自訂 QueryClient 來管理快取與請求策略

不喜歡看字的可以看影片：

簡介

在 Vue Query 中，QueryClient 負責管理所有的查詢 (useQuery、useMutation 等)，並提供：

全域快取管理
請求重試 (retry)
自動背景同步 (refetch)
錯誤處理 (onError)
查詢生命週期管理

自訂 QueryClient

我們可以直接使用 VueQueryPlugin 來註冊 QueryClient，並設定全域選項。

這樣做的好處是：

統一管理 API 請求策略（如 staleTime、retry）
避免每個 useQuery 重複設定 retry 或 staleTime
可擴展性強，可根據應用需求調整快取策略

main.js
// main.js
import { createApp } from "vue";
import { VueQueryPlugin, QueryClient } from "@tanstack/vue-query";
import App from "./App.vue";

// 建立 QueryClient，並設定全域選項
const queryClient = new QueryClient({
    defaultOptions: {
        queries: {
            staleTime: 60000, // 設定快取 60 秒內不會重新請求，也就是資料 60 秒內不會過期(fresh)
            retry: (failureCount, error) => {
                if (error.response?.status === 404) return false; // 404 不重試
                return failureCount < 3; // 其餘錯誤最多重試 3 次
            },
        },
    },
});

// 註冊 Vue Query Plugin
const app = createApp(App);
app.use(VueQueryPlugin, { queryClient });
app.mount("#app");

如果你只需要調整 全域預設行為，而不想自己建立 QueryClient，可以直接傳入 QueryClientConfig。

main.js
// main.js
import { createApp } from "vue";
import { VueQueryPlugin } from "@tanstack/vue-query";
import App from "./App.vue";

const vueQueryPluginOptions = {
    queryClientConfig: {
        defaultOptions: {
            queries: {
                staleTime: 3600000, // 1 小時內不會重新請求，也就是資料 1 小時內不會過期(fresh)
                refetchOnWindowFocus: false, // 預設不在視窗聚焦時重新請求
                retry: (failureCount, error) => {
                    if (error.response?.status === 404) return false; // 404 不重試
                    return failureCount < 3; // 其餘錯誤最多重試 3 次
                },
            },
        },
    },
};

const app = createApp(App);

app.use(VueQueryPlugin, vueQueryPluginOptions);
app.mount("#app");

使用自訂 QueryClient 來管理快取與請求策略

簡介​

自訂 QueryClient​

簡介

自訂 QueryClient