Vue Query useQueryClient 完全指南获取与注入 QueryClient 实例的原理与实战【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/queryuseQueryClient是 Vue Querytanstack/vue-query中最基础也最常用的 Composition API 钩子用于在任意组件中获取当前应用注入的QueryClient实例。本文围绕 useQueryClient.md 官方参考文档展开结合仓库源码与测试用例深入讲解它的签名、参数、返回值、底层注入机制、多实例场景下的id用法、错误处理以及真实项目中的典型调用模式。快速上手最简单的用法useQueryClient返回当前的QueryClient实例。在 Vue 组件中只需一行代码即可拿到它import { useQueryClient } from tanstack/vue-query const queryClient useQueryClient()调用后queryClient就是应用启动时通过VueQueryPlugin注入的那个实例你可以立即使用它提供的各种方法例如// 使某个查询失效触发重新请求 queryClient.invalidateQueries({ queryKey: [posts] }) // 直接设置查询数据 queryClient.setQueryData([posts], []) // 预取数据 queryClient.prefetchQuery({ queryKey: [posts], queryFn: fetchPosts })完整的QueryClientAPI如invalidateQueries、setQueryData、prefetchQuery、resetQueries、cancelQueries等可参考 QueryClient.md。从源码结构看useQueryClient返回的正是该类型实例类型定义为QueryClient见 useQueryClient.ts。API 签名与参数详解官方参考文档给出的签名如下const queryClient useQueryClient(id?: string)id?: string用途当你配置了多个使用不同queryClientKey的VueQueryPlugin实例时用该参数指定要获取哪个被注入的QueryClient。默认行为不传id时返回**最近上下文nearest context**中注入的QueryClient实例。也就是说id并不是某个客户端名称的随意字符串而必须与插件安装时传入的queryClientKey严格对应才能命中正确的实例。这种设计让一个 Vue 应用可以同时运行多个相互隔离的 QueryClient例如不同业务域使用不同的缓存、默认配置或持久化策略。返回值QueryClient上下文context中注入的QueryClient实例。如果上下文中找不到任何实例useQueryClient会抛出异常详见下文错误处理小节。源码级原理注入与读取的实现机制理解useQueryClient的真正原理需要同时看它的实现与VueQueryPlugin的注入逻辑。1. 注入端VueQueryPlugin 如何提供实例VueQueryPlugin在安装时根据queryClientKey计算出注入键再通过 Vue 的provide机制把实例提供给整棵组件树。核心代码见 vueQueryPlugin.ts// packages/vue-query/src/vueQueryPlugin.ts节选 install: (app: any, options: VueQueryPluginOptions {}) { const clientKey getClientKey(options.queryClientKey) // ... app.provide(clientKey, client) }在 Vue 2 环境下由于没有原生provide/inject插件通过全局 mixin 的beforeCreate钩子把实例挂到每个组件的_provided上this._provided[clientKey] client从而实现等价的注入行为vueQueryPlugin.ts。2. 键的生成getClientKey注入键由getClientKey生成定义在 utils.tsexport const VUE_QUERY_CLIENT VUE_QUERY_CLIENT export function getClientKey(key?: string) { const suffix key ? :${key} : return ${VUE_QUERY_CLIENT}${suffix} }可以看到不传key时默认注入键就是字符串VUE_QUERY_CLIENT传入key例如foo时注入键变为VUE_QUERY_CLIENT:foo。这解释了id参数的作用原理useQueryClient(id)内部同样调用getClientKey(id)得到完全相同的键再执行inject(key)取出对应实例。键必须匹配才能取到正确的客户端。3. 读取端useQueryClient 的实现useQueryClient的完整实现非常精简useQueryClient.tsimport { hasInjectionContext, inject } from vue-demi import { getClientKey } from ./utils import type { QueryClient } from ./queryClient export function useQueryClient(id ): QueryClient { // 确保 inject() 可以被使用 if (!hasInjectionContext()) { throw new Error( vue-query hooks can only be used inside setup() function or functions that support injection context., ) } const key getClientKey(id) const queryClient injectQueryClient(key) if (!queryClient) { throw new Error( No queryClient found in Vue context, use VueQueryPlugin to properly initialize the library., ) } return queryClient }实现分三步上下文检查调用hasInjectionContext()确认当前处于 Vue 的注入上下文setup()或支持注入上下文的函数中否则inject不可用按键读取通过getClientKey(id)计算出注入键并调用injectQueryClient(key)兜底校验若inject返回空值抛出明确错误提示需要先安装VueQueryPlugin。4. 测试用例佐证仓库中的单元测试useQueryClient.test.ts逐一验证了上述行为上下文中存在实例时返回该实例且inject以默认键VUE_QUERY_CLIENT被调用一次第 23-32 行上下文中不存在实例时抛出No queryClient found in Vue context, use VueQueryPlugin to properly initialize the library.第 34-42 行在setup()之外使用时抛出vue-query hooks can only be used inside setup() function or functions that support injection context.第 44-51 行传入自定义键foo时inject以VUE_QUERY_CLIENT:foo被调用第 53-62 行。这些测试直接印证了上文对参数、返回值和错误行为的全部描述。多 QueryClient 场景使用 id 选择实例默认情况下一个 Vue 应用只安装一个VueQueryPlugin此时useQueryClient()无参调用即可。但某些复杂场景需要多个彼此隔离的 QueryClient例如不同模块使用不同的缓存时长、离线持久化策略或 devtools 开关此时就需要id参数。安装多个插件实例在VueQueryPlugin的安装选项中传入不同的queryClientKey并各自配置独立的queryClientConfig或queryClientimport { VueQueryPlugin, QueryClient } from tanstack/vue-query const app createApp(App) app.use(VueQueryPlugin, { queryClientKey: main, queryClientConfig: { defaultOptions: { queries: { staleTime: 60_000 } } }, }) app.use(VueQueryPlugin, { queryClientKey: admin, queryClientConfig: { defaultOptions: { queries: { retry: 0 } } }, })从 vueQueryPlugin.ts 的类型定义可见插件选项既可以是queryClientConfig由插件内部new QueryClient(clientConfig)创建也可以是直接传入的queryClient实例。在组件中按 id 获取对应地组件里用id命中目标实例import { useQueryClient } from tanstack/vue-query const mainClient useQueryClient(main) // 注入键VUE_QUERY_CLIENT:main const adminClient useQueryClient(admin) // 注入键VUE_QUERY_CLIENT:admin// 在 admin 域组件中使 admin 客户端的数据失效 adminClient.invalidateQueries({ queryKey: [settings] })注意如果传入的id与任何已安装插件的queryClientKey都不匹配inject将返回空值useQueryClient会抛出错误。因此id必须与queryClientKey一一对应。错误处理两种典型的抛错场景官方文档明确指出如果上下文中找不到实例则抛出异常结合源码实际存在两种抛错路径场景错误信息原因在setup()或注入上下文之外调用vue-query hooks can only be used inside setup() function or functions that support injection context.hasInjectionContext()返回falseinject不可用上下文存在但无对应实例No queryClient found in Vue context, use VueQueryPlugin to properly initialize the library.未安装插件或id与已安装的queryClientKey不匹配最常见的根因忘记在应用入口注册VueQueryPlugin。官方快速入门quick-start.md演示了正确姿势——先安装插件再在组件中通过useQueryClient使用import { useQueryClient, useQuery, useMutation } from tanstack/vue-query // 组件 setup 内 const queryClient useQueryClient()实战调用模式useQueryClient 在典型场景中的位置在 Vue Query 生态中useQueryClient很少单独出现它通常是组合式逻辑的接线员。以下是仓库文档中出现的高频调用模式可直接套用。1. 在 mutation 成功后使查询失效最经典的场景修改数据后让相关查询重新拉取。invalidations-from-mutations.md 展示了这一组合import { useMutation, useQueryClient } from tanstack/vue-query const queryClient useQueryClient() const mutation useMutation({ mutationFn: addTodo, onSuccess: () { queryClient.invalidateQueries({ queryKey: [todos] }) }, })2. 与持久化插件配合在createPersister场景中同样通过useQueryClient拿到客户端来执行setQueryDefaults等持久化相关配置createPersister.md。3. 在 SSR 中获取服务端实例服务端渲染时需要拿到服务端的QueryClient实例来做预取与dehydrate。ssr.md 中明确提到使用useQueryClient获取服务端侧的queryClient实例第 113 行并给出了完整调用import { useQuery, useQueryClient, dehydrate } from tanstack/vue-query // 优先使用 SSR context 中共享的实例否则回退到 useQueryClient() (ssrContext ! null ssrContext.VueQuery) || useQueryClient()4. 内部钩子的隐式依赖从源码结构看useQueryClient还是其他 Vue Query 钩子的底层依赖例如 useBaseQuery.ts 在未显式传入queryClient时会调用useQueryClient()获取默认实例。useMutation、useQueries、useIsFetching、useIsMutating、useMutationState等钩子也都在各自实现中引用了它见 packages/vue-query/src 下的对应文件。这解释了为什么未安装插件的错误会波及几乎所有的 Vue Query 钩子。小结useQueryClient是 Vue Query 的入口钥匙无参调用返回最近上下文注入的默认QueryClient带参调用useQueryClient(id)通过VUE_QUERY_CLIENT:id注入键命中多实例场景下对应的客户端它在setup()之外或找不到实例时会抛出明确错误指引开发者正确安装VueQueryPlugin底层由 utils.ts 的getClientKey与 Vue 的provide/inject机制协作完成行为已由 useQueryClient.test.ts 全面覆盖验证。掌握它你就掌握了在 Vue 组件中操作查询缓存、失效、预取与 SSR 预取的全部入口。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考