从 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 的优势

这里没有贬低 Axios 的意思，目前为止我依然觉得 Axios 是最伟大的的请求库！

与 Axios 的对比总结

Vue3 快速上手（3 分钟跑通）

• 安装

npm i @tanstack/vue-query

• 注册插件

// main.ts
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: () => 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. 条件查询（依赖请求）

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

2. 无限滚动

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. 并行多个请求

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. 表单提交 + 乐观更新

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

一行代码开启浏览器调试面板：

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