TanStack Query Vue -vue的Axios Hooks

前言

随着 Hooks 思想 在前端的普及，Vue3 终于有了属于自己的 “一站式数据层”——TanStack Query Vue。

定义

TanStack Query（曾用名 React Query）是一个强大的数据请求和缓存管理库，它与框架无关，同时提供了针对 Vue 的专门集成（@tanstack/vue-query），定位于 “数据层操作系统”，而非简单的 HTTP 客户端。它解决了前端开发中数据获取、缓存、同步和更新等常见问题，让开发者能更专注于业务逻辑而非数据管理细节。

核心功能

它对任何返回 Promise 的函数（axios/fetch/GraphQL SDK 等）做二次封装，提供：

智能数据缓存

1. 自动缓存请求结果，避免重复请求
2. 支持缓存失效和背景刷新
3. 可配置的缓存时间和失效策略

数据同步与状态管理

1. 自动处理加载、成功、错误等状态
2. 提供乐观更新能力，提升用户体验
3. 支持数据依赖和联动请求

请求优化

1. 请求去重，防止并发重复请求
2. 自动重试失败的请求
3. 支持分页、无限滚动和懒加载

Vue 深度集成

1. 基于 Vue Composition API 设计
2. 提供响应式的数据和状态
3. 与 Vue 的生命周期完美配合

与传统方案对比的优势

减少样板代码
无需手动管理 loading、error、data 等状态，也不需要编写重复的请求逻辑。

提升应用性能
通过智能缓存减少网络请求，降低服务器压力，同时加快应用响应速度。

增强用户体验
背景刷新、乐观更新等特性让应用感觉更流畅，减少等待感。

更好的开发体验
清晰的 API 设计，完善的 TypeScript 支持，以及丰富的调试工具。

灵活的配置选项
可以针对不同请求设置不同的缓存策略、重试机制等。

与 Vue 生态无缝集成
与 Vue 3 的 Composition API 自然契合，支持 Vue 的响应式系统。

与Axios 使用对比

能力	TanStack Query Vue	纯 Axios
数据缓存	✅ 内置 LRU，自动垃圾回收	❌ 自己写 Map
分页/无限加载	✅ useInfiniteQuery 一行搞定	❌ 自行维护页码、累加数组
请求取消	✅ cancel() 或 AbortSignal 自动	❌ 手动 AbortController
依赖查询	✅ enabled 条件触发	❌ 自己写 watch
并行/串行	✅ 同时发或按依赖发	❌ Promise.all / then 链
乐观更新	✅ onMutate + 回滚	❌ 自己写快照 & 回滚
调试	✅ 官方 Devtools	❌ console.log

不同场景应用对比

场景	Axios 代码量	Axios 代码量
列表 + 下拉加载	50+ 行	10 行
详情页切换 ID 重新拉取	写 watch	queryKey  自动触发
提交表单后刷新列表	手动再次 get()	onSuccess 里 invalidateQueries
断网重连自动重试	自己写定时器	retry:3  一行配置

Vue3 快速上手

安装

npm install @tanstack/vue-query

引入（main.js）

import { VueQueryPlugin } from '@tanstack/vue-query'createApp(App).use(VueQueryPlugin).mount('#app')

组件内

<script setup>import { useQuery } from '@tanstack/vue-query'const { data, isLoading, isError } = useQuery({queryKey: ['posts'],queryFn: () => axios.post('/api/posts').then(r => r.json())})</script><template><div v-if="isLoading">加载中...</div><div v-else-if="isError">请求失败</div><ul v-else><li v-for="p in data" :key="p.id">{{ p.title }}</li></ul></template>

不同场景使用案例

1. 条件查询

const { data } = useQuery({queryKey: ['user', userId],queryFn: () => axios.get(`/api/user/${userId.value}`).then(r => r.json()),enabled: !!userId.value   // userId 存在才发请求})

2、无限滚动

const {data,fetchNextPage,hasNextPage,isFetchingNextPage} = useInfiniteQuery({queryKey: ['comments'],queryFn: ({ pageParam = 1 }) =>axios.get(`/api/comments?page=${pageParam}`).then(r => r.json()),getNextPageParam: (last) => last.nextPage ?? false})

3. 并行多个请求

const ids = [1, 2, 3]const queries = ids.map(id =>useQuery({queryKey: ['item', id],queryFn: () => axios.get(`/api/item/${id}`).then(r => r.json())}))// queries[i].data 即对应结果

4. 表单提交 + 自动更新

const queryClient = useQueryClient()const { mutate } = useMutation({mutationFn: (newTodo) => axios.post('/api/todos', newTodo),onMutate: async (newTodo) => {await queryClient.cancelQueries(['todos'])const prev = queryClient.getQueryData(['todos'])queryClient.setQueryData(['todos'], old => [...old, newTodo])return { prev }},onError: (err, vars, context) =>queryClient.setQueryData(['todos'], context.prev),onSettled: () => queryClient.invalidateQueries(['todos'])})

当然除了以上几种案例，还有更多高级功能比如：轮询/实时查询、窗口聚焦时重新获取、离线支持、滚动恢复等;

调试工具

@tanstack/vue-query-devtools 是 TanStack Query 为 Vue 应用提供的开发工具扩展，专为调试和监控基于 @tanstack/vue-query 的数据请求而设计。它能帮助开发者直观地查看和管理应用中的查询状态、缓存数据、请求历史等，极大简化了数据请求相关的调试工作。

特点

查询状态可视化

1. 实时展示所有活跃查询（queries）和变更（mutations）
2. 清晰显示每个请求的状态（加载中、成功、错误）
3. 查看查询的键（queryKey）、缓存数据、响应时间等详细信息

缓存管理工具

1. 直接在开发工具中查看和编辑缓存数据
2. 手动触发查询失效（invalidate）、刷新（refetch）等操作
3. 清除特定或全部缓存，方便测试缓存策略

请求历史追踪

1. 记录所有请求的历史记录，包括参数、响应和错误信息
2. 支持筛选和搜索特定请求，快速定位问题

性能监控

1. 显示请求耗时、重试次数等性能指标
2. 识别重复请求或不必要的请求，帮助优化应用性能

使用：

import { VueQueryDevTools } from '@tanstack/vue-query-devtools'app.use(VueQueryDevTools)

总结

Axios 作为被广泛应用的 HTTP 客户端，但在 “数据层” 需求日益复杂的今天，TanStack Query Vue 把「取数据、管数据、刷新数据」做成了 配置驱动。

总之，TanStack Query Vue 为 Vue 应用提供了现代化的数据请求解决方案，特别适合中大型应用，能够显著提升开发效率和应用质量。