从 2014
年 Vue 诞生到今天,Axios 几乎成了前端工程里的"钉子户"------稳定
、简单
、易上手
,但十年过去,它依旧是 "裸 HTTP 客户端"。
想要分页
、缓存
、并行
/依赖请求
、自动重试
、请求取消
、乐观更新
?对不起,全部自己手搓。
现在,随着 Hooks 思想 在前端的普及,Vue3 终于有了属于自己的 "一站式数据层" ------TanStack Query Vue。

这一次,真的可以跟 Axios 说再见了!
什么是 TanStack Query Vue
TanStack Query Vue (npm 名 @tanstack/vue-query
)是 React Query
的 Vue
兄弟版本,定位 "数据层操作系统" ,而非简单的 HTTP
客户端。

它对任何返回 Promise
的函数(axios/fetch/GraphQL
SDK 等)做二次封装,提供:
自动缓存
/失效
/重取
分页
、无限滚动
、并行
/依赖查询
请求取消
、乐观更新
、后台重试
SSR
&Suspense
(实验)- 官方
Devtools
调试面板
一句话:只关心数据长什么样,其余交给框架。
TanStack Query Vue 的优势
能力 | TanStack Query Vue | 纯 Axios |
---|---|---|
数据缓存 | ✅ 内置 LRU,自动垃圾回收 | ❌ 自己写 Map |
分页/无限加载 | ✅ useInfiniteQuery 一行搞定 |
❌ 自行维护页码、累加数组 |
请求取消 | ✅ cancel() 或 AbortSignal 自动 |
❌ 手动 AbortController |
依赖查询 | ✅ enabled 条件触发 |
❌ 自己写 watch |
并行/串行 | ✅ 同时发或按依赖发 | ❌ Promise.all / then 链 |
乐观更新 | ✅ onMutate + 回滚 |
❌ 自己写快照 & 回滚 |
调试 | ✅ 官方 Devtools | ❌ console.log |
这里没有贬低 Axios 的意思,目前为止我依然觉得 Axios 是最伟大的的请求库!
与 Axios 的对比总结
场景 | Axios 代码量 | TanStack Query Vue |
---|---|---|
列表 + 下拉加载 | 50+ 行 | 10 行 |
详情页切换 ID 重新拉取 | 写 watch |
queryKey 自动触发 |
提交表单后刷新列表 | 手动再次 get() |
onSuccess 里一句 invalidateQueries |
断网重连自动重试 | 自己写定时器 | retry:3 一行配置 |
Vue3 快速上手(3 分钟跑通)
- 安装
bash
npm i @tanstack/vue-query
- 注册插件
ts
// main.ts
import { VueQueryPlugin } from '@tanstack/vue-query'
createApp(App).use(VueQueryPlugin).mount('#app')
- 组件内直接请求
html
<script setup>
import { useQuery } from '@tanstack/vue-query'
const { data, isLoading, isError } = useQuery({
queryKey: ['posts'],
queryFn: () => fetch('/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>
4 个高频实战案例
1. 条件查询(依赖请求)
js
const { data } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetch(`/api/user/${userId.value}`).then(r => r.json()),
enabled: !!userId.value // userId 存在才发请求
})
2. 无限滚动
js
const {
data,
fetchNextPage,
hasNextPage,
isFetchingNextPage
} = useInfiniteQuery({
queryKey: ['comments'],
queryFn: ({ pageParam = 1 }) =>
fetch(`/api/comments?page=${pageParam}`).then(r => r.json()),
getNextPageParam: (last) => last.nextPage ?? false
})
3. 并行多个请求
js
const ids = [1, 2, 3]
const queries = ids.map(id =>
useQuery({
queryKey: ['item', id],
queryFn: () => fetch(`/api/item/${id}`).then(r => r.json())
})
)
// queries[i].data 即对应结果
4. 表单提交 + 乐观更新
js
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'])
})
当然除了以上几种常用案例,还有更多高级功能比如:轮询/实时查询
、窗口聚焦时重新获取
、离线支持
、滚动恢复
等;
更多的使用方法这里不做过多讲解,想要学习的同学可以移步官方文档:https://tanstack.com.cn/query/latest/docs/framework/vue/overview
调试神器:@tanstack/vue-query-devtools
一行代码开启浏览器调试面板:
ts
import { VueQueryDevTools } from '@tanstack/vue-query-devtools'
app.use(VueQueryDevTools)

效果:
- 实时查看缓存
key
、数据
、失效时间
; - 一键手动触发
refetch
/invalidate
; - 支持黑暗 / 亮色主题,比
console.log
爽10
倍!
写在最后
Axios 依旧是伟大的 HTTP 客户端,但在 "数据层" 需求日益复杂的今天,TanStack Query Vue 把「取数据、管数据、刷新数据」
做成了 配置驱动。
从简单列表到企业级中台,10 行代码 就能搞定过去 100 行 的逻辑。
新项目,不妨试试 Vue3 + TanStack Query ,让业务代码真正回归业务,而不是迷失在无尽的 loading
、error
、retry
之中。
- TanStack Query Vue 中文 :
https://tanstack.com.cn/query/latest/docs/framework/vue/overview