vue-query 使用

Vue3 + TanStack Query 企业级使用规范

📘 Vue3 + TanStack Query 企业级使用规范

📦 一、安装依赖

npm i @tanstack/vue-query axios

✅ 说明：@tanstack/vue-query 是 Vue3 的数据请求状态管理库，axios 用于 HTTP 请求。

⚙️ 二、全局注册（main.ts）

import { createApp } from 'vue'
import App from './App.vue'
import { VueQueryPlugin } from '@tanstack/vue-query'

const app = createApp(App)

app.use(VueQueryPlugin, {
  queryClientConfig: {
    defaultOptions: {
      queries: {
        retry: 1,                      // 失败重试次数
        refetchOnWindowFocus: false,   // 窗口聚焦时不重新请求
        refetchOnReconnect: false,     // 网络重连时不重新请求
        staleTime: 1000 * 30,          // 数据新鲜时间（30秒）
      },
    },
  },
})

app.mount('#app')

📋 配置参数说明

参数	说明	推荐值
retry	请求失败重试次数	1
refetchOnWindowFocus	窗口重新聚焦时是否重新请求	false
refetchOnReconnect	网络重连时是否重新请求	false
staleTime	数据新鲜时间（毫秒）	1000 * 30（30秒）

📄 三、页面完整代码结构

3.1 引入依赖

import { reactive } from 'vue'
import { ElMessage } from 'element-plus'
import { useQuery, useMutation, useQueryClient } from '@tanstack/vue-query'
import {
  getUserList,
  createUser,
  updateUser,
  deleteUser,
} from '@/api/user'

3.2 查询条件

const query = reactive({
  keyword: '',
  page: 1,
  size: 10,
})

3.3 查询列表

const { data: list, isLoading, refetch } = useQuery({
  queryKey: ['userList', query],
  queryFn: () => getUserList(query),
})

const queryClient = useQueryClient()

3.4 搜索 & 重置

const handleSearch = () => {
  query.page = 1
  refetch()
}

const handleReset = () => {
  query.keyword = ''
  query.page = 1
  refetch()
}

3.5 新增用户

const addMut = useMutation({
  mutationFn: createUser,
  onSuccess: () => {
    ElMessage.success('新增成功')
    queryClient.invalidateQueries(['userList'])
  },
})

3.6 编辑用户

const updateMut = useMutation({
  mutationFn: updateUser,
  onSuccess: () => {
    ElMessage.success('修改成功')
    queryClient.invalidateQueries(['userList'])
  },
})

3.7 删除用户

const delMut = useMutation({
  mutationFn: deleteUser,
  onSuccess: () => {
    ElMessage.success('删除成功')
    queryClient.invalidateQueries(['userList'])
  },
})

3.8 表单数据与方法

const form = reactive({
  username: '',
  phone: '',
})

const handleAdd = () => {
  addMut.mutate(form)
}

const handleEdit = (id: number) => {
   // 编辑逻辑：获取用户详情、回显表单、触发
 updateMut.mutate()
}

const handleDelete = (id: number) => {
  delMut.mutate(id)
}

🧠 四、核心概念说明

概念	说明
useQuery	用于数据查询，自动管理缓存、加载状态
useMutation	用于增删改操作，配合 invalidateQueries 刷新列表
queryKey	缓存唯一标识，变化时自动重新请求
invalidateQueries	使指定缓存失效，触发重新获取

✨ 五、最佳实践建议

• 统一 API 层：所有接口请求统一放在 @/api 目录下管理。
• 查询条件使用 reactive：确保 queryKey 能正确监听到变化。
• 增删改后刷新列表：统一使用 invalidateQueries 使列表缓存失效。
• 全局配置统一：在 main.ts 中统一配置默认行为，避免重复代码。
• 错误处理：建议在 useMutation 中添加 onError 回调处理异常。

🔧 六、企业级进阶配置（可选）

对于复杂场景，还可以考虑以下增强模式：

• 全局错误统一处理：配置 queryClient.setDefaultOptions 中的 onError 钩子。
• 持久化缓存：搭配 @tanstack/query-persist-client-core 将缓存存入 localStorage。
• 分页/无限滚动：使用 useInfiniteQuery 优化体验。
• 请求取消：利用 AbortController 与 queryFn 集成。

💡 提示：以上规范已在多个中大型项目中落地，确保代码可维护性及响应式性能。

---

📎 附录：Word 导出 / 打印建议

您可以直接复制整个页面内容粘贴到 Word 中，保留绝大部分样式（表格、代码块、背景色）。若需微调：

• 代码块背景在 Word 中可能转为灰底，可通过“设计 -> 颜色”调整为深色。
• 推荐使用等线 / Consolas 字体展示代码段。
• 表格表头建议加粗并添加浅灰色底纹。

Vue3 + TanStack Query 企业级规范 · 生产级参考 · 版本 1.0