一、引言：从手动造轮子到数据层圣杯

在 Vue 开发中，数据管理一直是痛点：手动缓存、重复请求、竞态条件、分页加载…… 这些问题往往需要开发者编写大量冗余代码。直到遇到TanStack Query Vue—— 这个由 TanStack 团队打造的跨框架数据同步库，彻底改变了我的开发流程。

通过一个下午的实践，我卸载了 Pinia、手写缓存和 el-table，仅用 **@tanstack/vue-query和@tanstack/vue-table** 两个库，就实现了用户列表、搜索、分页等核心功能，代码量减少 60% 以上。这篇文章将结合实战案例，带你从基础到进阶掌握这一数据层利器。

二、核心概念与基础用法

1. 数据获取的极简范式

传统 Vue 开发中，我们用 axios 发起请求后需手动管理 loading、error、data 状态。而 TanStack Query 通过useQuery钩子将这一过程简化为：

vue

<script setup>
import { useQuery } from '@tanstack/vue-query'
import axios from 'axios'

const fetchUsers = async (page = 1) => {
  const res = await axios.get(`/api/users?page=${page}`)
  return res.data
}

const { data, isLoading, isError } = useQuery({
  queryKey: ['users', { page: 1 }], // 唯一标识查询的键
  queryFn: () => fetchUsers(1), // 实际执行请求的函数
  staleTime: 60_000, // 数据新鲜期（毫秒）
  cacheTime: 300_000 // 缓存保留时间（毫秒）
})
</script>

<template>
  <div v-if="isLoading">加载中...</div>
  <div v-if="isError">加载失败，请重试</div>
  <ul v-else>
    <li v-for="user in data" :key="user.id">{{ user.name }}</li>
  </ul>
</template>

• 自动状态管理：isLoading、isError等状态由库自动维护，无需手动声明。
• 智能缓存：相同queryKey的请求自动复用缓存，避免重复请求。
• 后台更新：数据过期后自动在后台重新获取，用户无感知。

2. 数据变更的优雅处理

对于 POST/PUT/DELETE 等操作，useMutation提供了完整的生命周期回调：

vue

<script setup>
import { useMutation, useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()

const createUser = async (user) => {
  const res = await axios.post('/api/users', user)
  return res.data
}

const { mutate, isLoading: isMutating } = useMutation({
  mutationFn: createUser,
  onSuccess: (newUser) => {
    // 数据变更后自动刷新用户列表
    queryClient.invalidateQueries({ queryKey: ['users'] })
  },
  onError: (error) => {
    console.error('创建用户失败:', error)
  }
})

const handleSubmit = () => {
  mutate({ name: 'Alice', age: 30 })
}
</script>

<template>
  <button @click="handleSubmit" :disabled="isMutating">
    创建用户
  </button>
</template>

• 乐观更新：通过onMutate回调实现 UI 即时反馈，失败时自动回滚。
• 缓存失效策略：invalidateQueries会智能匹配相关查询，触发自动刷新。

三、实战进阶：解决复杂场景

1. 分页加载的平滑体验

传统分页实现需手动管理页码状态和请求逻辑，而 TanStack Query 通过placeholderData优化体验：

vue

<script setup>
const fetchUsers = async ({ pageParam = 1 }) => {
  const res = await axios.get(`/api/users?page=${pageParam}`)
  return {
    users: res.data,
    nextPage: pageParam + 1
  }
}

const { data, isLoading, hasNextPage, fetchNextPage } = useInfiniteQuery({
  queryKey: ['users'],
  queryFn: ({ pageParam }) => fetchUsers(pageParam),
  getNextPageParam: (lastPage) => lastPage.nextPage,
  placeholderData: (previousData) => ({
    ...previousData,
    pages: [...previousData.pages, undefined]
  })
})

const loadMore = async () => {
  if (hasNextPage && !isLoading) {
    await fetchNextPage()
  }
}
</script>

<template>
  <ul>
    <li v-for="(users, index) in data.pages" :key="index">
      <div v-for="user in users">{{ user.name }}</div>
      <div v-if="data.pages[index] === undefined">加载中...</div>
    </li>
  </ul>
  <button @click="loadMore" :disabled="!hasNextPage || isLoading">
    加载更多
  </button>
</template>

• 平滑过渡：placeholderData保留上一页数据，避免加载时 UI 闪烁。
• 自动加载：hasNextPage和fetchNextPage简化无限滚动实现。

2. 竞态条件的完美化解

在搜索框等场景中，连续输入可能导致请求顺序错乱。结合 Vue 的watch和onCleanup可优雅解决：

vue

<script setup>
import { useQuery } from '@tanstack/vue-query'
import { ref, watch } from 'vue'

const searchQuery = ref('')
let currentRequest = null

watch(searchQuery, async (newVal, oldVal, onCleanup) => {
  // 取消上一个未完成的请求
  if (currentRequest) {
    currentRequest.cancel()
  }

  const { signal, cancel } = AbortController()
  currentRequest = { signal, cancel }
  onCleanup(() => cancel()) // 组件卸载时取消请求

  try {
    const { data } = await useQuery({
      queryKey: ['search', newVal],
      queryFn: async () => {
        const res = await axios.get('/api/search', {
          signal: currentRequest.signal,
          params: { q: newVal }
        })
        return res.data
      },
      enabled: !!newVal // 空查询时禁用
    })
    // 更新UI
  } catch (error) {
    if (error.name !== 'AbortError') {
      console.error('搜索失败:', error)
    }
  }
}, { immediate: false })
</script>

• 请求中断：通过AbortController取消未完成的请求。
• 资源释放：onCleanup确保组件卸载时清理未完成的请求。

3. 与 Vue Router 的深度集成

虽然 TanStack Router 尚未支持 Vue，但通过watch路由参数可实现动态数据加载：

vue

<script setup>
import { useQuery } from '@tanstack/vue-query'
import { useRoute } from 'vue-router'

const route = useRoute()

const { data } = useQuery({
  queryKey: ['post', route.params.id],
  queryFn: async () => {
    const res = await axios.get(`/api/posts/${route.params.id}`)
    return res.data
  },
  // 路由参数变化时自动刷新
  enabled: !!route.params.id
})
</script>

四、性能优化与最佳实践

1. 缓存策略的精细控制

• stale-while-revalidate：优先展示缓存数据，同时在后台更新，适合新闻列表等场景。
• refetchOnWindowFocus：窗口重新聚焦时自动刷新数据，提升实时性。
• queryKey 设计：将依赖参数包含在queryKey中，确保缓存精准匹配。

2. 大列表的性能革命

结合 **@tanstack/vue-table和@tanstack/vue-virtual** 可实现万行数据流畅渲染：

vue

<script setup>
import { useTable, useVirtual } from '@tanstack/vue-table'
import { computed } from 'vue'

const columns = computed(() => [
  { name: '姓名', accessorKey: 'name' },
  { name: '年龄', accessorKey: 'age' }
])

const {
  getTableProps,
  getTableBodyProps,
  headerGroups,
  rows,
  prepareRow
} = useTable({
  columns,
  data: users.value // 来自useQuery的数据
})

const {
  getVirtualizerProps,
  scrollToRow
} = useVirtual({
  items: rows,
  estimateSize: 35 // 行高预估
})
</script>

<template>
  <div v-bind="getVirtualizerProps()">
    <table v-bind="getTableProps()">
      <thead>
        <tr v-for="headerGroup in headerGroups" :key="headerGroup.id">
          <th v-for="column in headerGroup.headers" :key="column.id">
            {{ column.column.name }}
          </th>
        </tr>
      </thead>
      <tbody v-bind="getTableBodyProps()">
        <tr
          v-for="row in rows"
          :key="row.id"
          v-bind="prepareRow(row)"
        >
          <td v-for="cell in row.cells" :key="cell.id">
            {{ cell.getValue() }}
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

• 虚拟滚动：仅渲染可见区域的行，避免内存爆炸。
• 高性能表格：内置排序、筛选等功能，支持 60 FPS 渲染。

3. 错误处理的分层策略

• 全局拦截：在 axios 拦截器中统一处理网络错误：

javascript

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      router.push('/login')
    }
    return Promise.reject(error)
  }
)

• 局部处理：在组件中通过onError处理业务错误：

vue

const { isError, error } = useQuery({
  // ...
  onError: (err) => {
    ElMessage.error(`请求失败：${err.message}`)
  }
})

五、总结与未来展望

TanStack Query Vue 通过类型安全、跨框架兼容、开发者工具等特性，重新定义了 Vue 应用的数据管理方式。从基础查询到复杂场景，它用极简的 API 解决了 90% 的数据管理痛点，让开发者专注于业务逻辑。

GitHub：https://github.com/tanstack/query

感谢关注【AI码力】，获取更多Vue秘籍！