Vue Query ：现代 Vue 应用的服务器状态管理利器

查询 (Queries): useQuery

• 用途: 从异步源（通常是 API）获取 (读取) 数据。
• 基本用法:

  import { useQuery } from '@tanstack/vue-query';
  import axios from 'axios';

  // 在 setup 函数或 <script setup> 中使用
  const {
  data: todos, // 获取的数据，响应式 ref
  status, // 'pending', 'error', 'success'
  isLoading, // 是否首次加载 (v5 前常用)
  isPending, // 是否首次加载 (v5 推荐)
  isFetching, // 是否任何形式的获取中 (包括后台刷新)
  isError, // 是否出错
  error, // 错误对象
  refetch // 手动触发重新获取的函数
  } = useQuery({
  queryKey: ['todos'], // 必需：唯一标识此查询的键 (数组或字符串)
  queryFn: async () => { // 必需：执行数据获取的异步函数
  const response = await axios.get('/api/todos');
  return response.data;
  },
  // 可选配置项:
  // staleTime: 5 * 60 * 1000, // 数据在 5 分钟内保持新鲜
  // gcTime: 10 * 60 * 1000, // 无活跃观察者 10 分钟后清除缓存
  // refetchOnWindowFocus: false, // 窗口聚焦时不自动刷新
  // enabled: computed(() => !!userId.value), // 仅当 userId 存在时才执行
  });

• queryKey: 极其重要。它用于内部缓存和依赖跟踪。键的改变会触发新的查询。通常包含资源名称和依赖参数，如 ['todos'], ['todos', { status: 'done' }], ['post', postId]。
• queryFn: 必须返回一个 Promise。Vue Query 会处理 Promise 的解析和拒绝。
• 状态管理: Vue Query 自动管理 isLoading/isPending, isFetching, isError, status 等状态，你可以直接在模板中使用这些响应式 ref。
• 缓存与同步: 内置 Stale-While-Revalidate 策略、后台自动刷新、窗口聚焦刷新等功能（可通过 options 配置）。

变更 (Mutations): useMutation

• 用途: 执行改变服务器数据的操作（POST, PUT, DELETE 等）。
• 基本用法: import { useMutation, useQueryClient } from '@tanstack/vue-query';
  import axios from 'axios';

  const queryClient = useQueryClient(); // 获取 QueryClient 实例

  const {
  mutate, // 触发变更的函数 (不返回 Promise)
  mutateAsync, // 触发变更并返回 Promise 的函数
  status, // 'idle', 'pending', 'error', 'success'
  isPending, // 是否正在执行变更
  isError,
  error,
  data: mutationResult // 变更成功后的结果
  } = useMutation({
  mutationFn: async (newTodo) => { // 必需：执行变更的异步函数
  const response = await axios.post('/api/todos', newTodo);
  return response.data;
  },
  // 可选配置项:
  onSuccess: (data, variables, context) => {
  // 变更成功后的回调，极其常用！
  // 1. 使相关查询失效，让它们在下次访问时重新获取
  queryClient.invalidateQueries({ queryKey: ['todos'] });

  // 2. 或者，直接手动更新缓存 (更即时，但可能更复杂)
  // queryClient.setQueryData(['todos'], (oldData) => […oldData, data]);

  console.log('Todo added!', data);
  },
  onError: (error, variables, context) => {
  console.error('Failed to add todo:', error);
  // 可以在这里处理错误，例如显示通知
  },
  // onMutate: (variables) => {
  // // 乐观更新：在 mutationFn 执行前立即修改缓存
  // // 需要返回 context 用于 onError 回滚
  // },
  // onSettled: (data, error, variables, context) => {
  // // 无论成功失败都执行
  // }
  });

  // 在方法或事件处理中调用:
  function addTodo() {
  mutate({ title: 'New Task', completed: false });
  }

• 核心流程: 调用 mutate 或 mutateAsync 传入需要提交的数据 (variables) -> 执行 mutationFn -> 根据结果调用 onSuccess 或 onError -> 调用 onSettled。
• 缓存交互: onSuccess 中最常见的做法是使用 queryClient.invalidateQueries 来智能地让依赖该数据的查询失效，从而触发自动更新。

查询客户端 (QueryClient)

• 核心: 是 Vue Query 的“大脑”，管理所有查询的缓存、状态和配置。
• 设置: 通常在你的 Vue 应用入口 (如 main.js / main.ts) 创建一个 QueryClient 实例，并通过 VueQueryPlugin 提供给整个应用。 import { createApp } from 'vue';
  import App from './App.vue';
  import { VueQueryPlugin, QueryClient } from '@tanstack/vue-query';

  const app = createApp(App);
  const queryClient = new QueryClient({
  defaultOptions: { // 可以设置全局默认选项
  queries: {
  staleTime: 5 * 60 * 1000, // 全局默认 5 分钟新鲜期
  },
  },
  });

  app.use(VueQueryPlugin, { queryClient }); // 注册插件
  app.mount('#app');

• 交互: 可以通过 useQueryClient() hook 在组件中获取 queryClient 实例，然后调用其方法手动与缓存交互，如 invalidateQueries, setQueryData, refetchQueries 等。

缓存机制 (Stale-While-Revalidate)

• Vue Query 默认采用此策略：
  • Stale Time (staleTime): 数据保持“新鲜”的时间。默认 0。
  • GC Time (gcTime): 数据在无活跃观察者后，在缓存中保留多久才被垃圾回收。默认 5 分钟。
• 当数据被视为“过时”（超过 staleTime）但未被回收时，Vue Query 会：
• 立即返回缓存的过时数据 (UI 快速响应)。
• 在后台自动发起重新获取请求 (isFetching 为 true)。
• 请求成功后更新缓存和 UI。