TanStack Query 5.x 版本中 Vue 适配器的正确使用方式

在使用 TanStack Query (原 React Query) 的 Vue 适配器时，许多开发者会遇到一个常见错误："client.defaultQueryOptions is not a function"。这个问题主要出现在从 v4 升级到 v5 版本时，由于 API 使用方式发生了变化。

问题背景

TanStack Query v5 对 Vue 适配器的 API 进行了重大调整，特别是在 useQuery 钩子的调用方式上。在 v4 版本中，开发者可以这样使用：

useQuery(['todos'], fetchTodos)

但在 v5 版本中，这种调用方式已被弃用，必须改为对象形式的参数传递：

useQuery({ 
  queryKey: ['todos'], 
  queryFn: fetchTodos 
})

错误原因分析

当开发者继续使用 v4 的调用方式时，Vue 的响应式系统会尝试访问 client.defaultQueryOptions 方法，但由于参数格式不正确，该方法不存在于当前上下文中，导致运行时错误。

正确使用方式

在 v5 版本中，useQuery 必须接受一个配置对象作为参数，其中必须包含 queryKey 和 queryFn 两个属性：

const { data } = useQuery({
  queryKey: ['todos', id],
  queryFn: () => fetchTodoById(id),
  staleTime: 1000 * 60 * 5, // 5分钟缓存
  retry: 2 // 失败重试2次
})

与 Vue 响应式系统的集成

当需要将 Vue 的响应式数据(如 ref 或 computed)作为查询参数时，正确的做法是：

const id = ref(1)

const { data } = useQuery({
  queryKey: ['todos', id.value], // 使用.value访问响应式值
  queryFn: () => fetchTodoById(id.value)
})

最佳实践建议

1. 明确区分查询键和查询函数：将查询键(queryKey)和查询函数(queryFn)分开定义，提高代码可读性

2. 合理使用查询选项：利用 staleTime、retry 等选项优化查询行为

3. 类型安全：TypeScript 用户应充分利用泛型参数确保类型安全

4. 错误处理：在查询函数中妥善处理错误情况

5. 依赖管理：确保查询键中包含所有影响查询结果的依赖项

升级注意事项

从 v4 迁移到 v5 时，开发者需要：

1. 检查所有 useQuery 调用，改为对象参数形式
2. 更新相关类型定义
3. 测试查询键的稳定性
4. 验证响应式依赖是否正常工作

通过遵循这些指导原则，开发者可以避免常见的升级陷阱，充分利用 TanStack Query v5 提供的新特性和改进。