TanStack Vue Query 与 GraphQL 集成指南基于 graphql-request 与代码生成的全类型化数据获取【免费下载链接】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/queryVue Query 是 TanStack Query 在 Vue 生态中的官方实现其数据获取机制建立在 Promise 抽象之上因此可以与包括 GraphQL 在内的任意异步数据获取客户端无缝协作。本文将以 docs/framework/vue/graphql.md由 React 版对应文档 经replace: { React: Vue, react-query: vue-query }规则自动生成为核心骨架系统讲解 Vue Query 与 GraphQL 的结合方式、类型安全边界并给出基于graphql-request与 GraphQL Code Generator 的完整可运行方案。读完本文你将掌握在 Vue 应用中用 Vue Query 驱动 GraphQL 查询、用代码生成工具获得端到端类型检查的完整能力。为什么 Vue Query 能与 GraphQL 天然协作Vue Query 的请求机制是传输层无关transport/protocol/backend agnostic的。官方文档明确说明由于 Vue Query 的获取机制基于 Promise 构建你可以将 Vue Query 与任何异步数据获取客户端配合使用包括 GraphQL。这一点在 packages/vue-query/README.md 的快速特性列表中也得到印证Transport/protocol/backend agnostic data fetching (REST, GraphQL, promises, whatever!)。从源码结构看这一能力源于其分层架构useQuery只是薄薄的一层 Vue 响应式封装底层委托给核心库的QueryObserver。以 packages/vue-query/src/useQuery.ts 为例export function useQueryTQueryFnData, TError, TData, TQueryKey extends QueryKey( options: MaybeRefOrGetterUseQueryOptionsTQueryFnData, TError, TData, TQueryFnData, TQueryKey, queryClient?: QueryClient, ): UseQueryReturnTypeTData, TError | UseQueryDefinedReturnTypeTData, TError { return useBaseQuery(QueryObserver, options, queryClient) }queryFn的契约只有一个返回一个 Promise。因此无论你内部调用fetch、Axios、graphql-request还是任何 GraphQL 客户端只要最终产出 PromiseVue Query 就能接管其状态管理、缓存、重试、去重与失效刷新。这意味着 GraphQL 集成不需要任何特殊适配器直接即插即用。一个必须知道的边界不支持规范化缓存在开始集成之前官方文档特别提醒了一个重要边界请记住Vue Query不支持规范化缓存normalized caching。虽然绝大多数用户实际上并不需要规范化缓存甚至可能没有他们想象中那么受益但确实存在极少数场景可能需要它——请务必先确认这真的是你所需要的功能。这意味着Vue Query 的缓存以查询键 → 查询结果的扁平结构存储而不是像 Apollo Client 那样把每条实体记录规范化到全局 store 中再按引用拼接。对大多数应用而言这反而更简单、可预测但如果你确实依赖跨查询的实体级共享缓存那么 Vue Query 并非为这种场景设计需要评估其他方案。准备工作安装与初始化 Vue Query要让 GraphQL 查询真正跑起来首先需要一个已初始化 VueQueryPlugin 的 Vue 应用。根据 packages/vue-query/README.md安装方式如下npm i tanstack/vue-query # 或 pnpm add tanstack/vue-query # 或 yarn add tanstack/vue-query # 或 bun add tanstack/vue-query注意如果你使用的是 Vue 2.6需要额外配置 vue/composition-api 也给出了实际的依赖组合示例。然后在入口文件中通过插件安装参考 examples/vue/basic/src/main.tsimport { createApp } from vue import { VueQueryPlugin } from tanstack/vue-query import App from ./App.vue createApp(App).use(VueQueryPlugin).mount(#app)初始化完成后即可在任意组件的setup()中使用useQuery。第一步用 graphql-request 发起 GraphQL 查询graphql-request是最轻量的 GraphQL 客户端之一它把一个 GraphQL 文档和变量直接映射为一个 Promise与 Vue Query 的queryFn契约完美契合。仓库中提供了真实可参考的集成示例examples/react/basic-graphql-request/React 版演示逻辑同样适用于 Vue。其依赖组合见 examples/react/basic-graphql-request/package.json展示了核心依赖graphql-request^7.1.2与graphql^16.9.0。在 Vue 项目中只需把tanstack/react-query换成tanstack/vue-query即可。一个基础的 Vue 组合式写法如下import { defineComponent } from vue import { request, gql } from graphql-request import { useQuery } from tanstack/vue-query const endpoint https://graphqlzero.almansi.me/api type Post { id: number title: string body: string } export default defineComponent({ name: Posts, setup() { const { status, data, error, isFetching } useQuery({ queryKey: [posts], queryFn: async () { const { posts: { data }, } await request{ posts: { data: ArrayPost } }( endpoint, gql query { posts { data { id title } } } , ) return data }, }) return { status, data, error, isFetching } }, })这里的要点queryKey是缓存的唯一标识[posts]标识该查询的缓存条目Vue Query 据此完成去重、失效与后台刷新。queryFn返回 Promisegraphql-request的request()天然满足这一要求无需额外包装。返回值为响应式Vue Query 通过 Vue 的reactive/ref机制暴露status、data、error、isFetching等状态见 packages/vue-query/src/useBaseQuery.ts 的实现模板中可直接使用。首次访问加载、二次访问秒开示例中明确指出访问过的查询再次进入时会instant load background refresh这正是 Vue Query 缓存与后台刷新的效果。第二步类型安全与代码生成GraphQL Code Generator手写gql模板字符串虽然可用但无法获得字段级类型检查。官方文档推荐的正规方案是Vue Query graphql-request5 GraphQL Code Generator三者组合可提供完全类型化的 GraphQL 操作fully-typed GraphQL operations。工作流如下在项目中安装并配置 GraphQL Code Generator让它根据你的 GraphQL schema 和操作文档生成类型定义从生成的./gql/gql模块导入graphql函数用这个graphql()函数包裹查询文档Code Generator 会为每个操作生成对应的类型将这些类型化文档传给graphql-request与useQuery即可获得端到端类型检查——data完全类型化连查询变量variables也经过类型检查。完整示例类型化查询 变量检查以下示例来自官方文档已转换为 Vue 语法演示了带变量查询的完整类型化链路import { defineComponent } from vue import request from graphql-request import { useQuery } from tanstack/vue-query import { graphql } from ./gql/gql const allFilmsWithVariablesQueryDocument graphql(/* GraphQL */ query allFilmsWithVariablesQuery($first: Int!) { allFilms(first: $first) { edges { node { id title } } } } ) export default defineComponent({ name: Films, setup() { // data 是完全类型化的 const { data } useQuery({ queryKey: [films], queryFn: async () request( https://swapi-graphql.netlify.app/.netlify/functions/index, allFilmsWithVariablesQueryDocument, // 变量同样经过类型检查 { first: 10 }, ), }) return { data } }, })这段代码中graphql()包裹的模板字符串会被 Code Generator 解析生成AllFilmsWithVariablesQueryDocument这一携带类型信息的文档对象request()的第二个参数接收该文档后第三个参数{ first: 10 }会被约束为{ first: number }——如果传错字段名或类型TypeScript 直接报错useQuery的data会基于文档的返回类型被推断为{ allFilms: { edges: { node: { id: string; title: string } }[] } }的结构模板渲染时享受完整补全与校验。如果项目使用 Vue 的script setup语法可进一步简化为script setup langts import request from graphql-request import { useQuery } from tanstack/vue-query import { graphql } from ./gql/gql const allFilmsWithVariablesQueryDocument graphql(/* GraphQL */ query allFilmsWithVariablesQuery($first: Int!) { allFilms(first: $first) { edges { node { id title } } } } ) const { data } useQuery({ queryKey: [films], queryFn: async () request( https://swapi-graphql.netlify.app/.netlify/functions/index, allFilmsWithVariablesQueryDocument, { first: 10 }, ), }) /script template ul li v-foredge in data?.allFilms.edges :keyedge.node.id {{ edge.node.title }} /li /ul /templateMutation 的代码生成配合类型化并不局限于查询。Vue Query 的useMutation同样接受返回 Promise 的mutationFn源码见 packages/vue-query/src/useMutation.ts因此代码生成的 mutation 文档可以直接传入graphql-requestimport { defineComponent } from vue import request from graphql-request import { useMutation, useQueryClient } from tanstack/vue-query import { graphql } from ./gql/gql const createReviewMutationDocument graphql(/* GraphQL */ mutation createReview($input: ReviewInput!) { createReview(input: $input) { id stars commentary } } ) export default defineComponent({ name: CreateReview, setup() { const queryClient useQueryClient() const { mutate, isPending, isError, error } useMutation({ mutationFn: (variables: { input: { stars: number; commentary: string } }) request( https://swapi-graphql.netlify.app/.netlify/functions/index, createReviewMutationDocument, variables, ), onSuccess: () { queryClient.invalidateQueries({ queryKey: [films] }) }, }) return { mutate, isPending, isError, error } }, })这里mutationFn的入参variables可以显式绑定到文档推断出的变量类型成功后可调用invalidateQueries让依赖的查询自动重新获取——这正是 Vue Query 管理写操作后的数据同步的惯用姿势。进阶用响应式选项驱动动态 GraphQL 查询Vue 版的useQuery相比 React 版有一个重要差异options 支持传入响应式值MaybeRefOrGetter当queryKey、enabled等发生变更时会自动重新执行查询。这在 GraphQL 场景下尤其适合根据当前状态改变查询变量的需求。官方 READMEpackages/vue-query/README.md与 useQuery 类型定义 共同说明了这一点import { ref } from vue import { request, gql } from graphql-request import { useQuery } from tanstack/vue-query const id ref(1) const enabled ref(false) const { data } useQuery({ queryKey: [post, id], // queryKey 可以是 ref queryFn: () request( https://graphqlzero.almansi.me/api, gql query post($id: ID!) { post(id: $id) { id title body } } , { id: id.value }, ), enabled, // enabled 也可以是 ref })当id.value变化时queryKey随之变化Vue Query 会以新键发起新查询并保留旧数据的缓存当enabled为false时查询保持挂起状态。这一机制让分页、详情联动、条件加载等 GraphQL 场景的实现非常直观。结合仓库继续深入官方文档本文对应文档为 docs/framework/vue/graphql.md其内容由 docs/framework/react/graphql.md 经替换规则生成Vue Query 的完整入门见 docs/framework/vue/overview.md快速开始见 docs/framework/vue/quick-start.md。源码实现查询入口 packages/vue-query/src/useQuery.ts、变更入口 packages/vue-query/src/useMutation.ts以及底层useBaseQuery实现 packages/vue-query/src/useBaseQuery.ts。可运行示例graphql-request 的完整请求/缓存演示见 examples/react/basic-graphql-request/Vue 项目的插件初始化与查询用法见 examples/vue/basic/ 与 examples/vue/simple/。包说明安装、初始化与响应式选项的官方说明见 packages/vue-query/README.md。小结Vue Query 与 GraphQL 的结合不需要任何适配层只要queryFn返回 PromiseVue Query 就能完整接管状态管理与缓存配合graphql-request和 GraphQL Code Generator还能获得文档即类型的端到端类型安全体验。在动手集成前请记住文档中反复强调的边界——Vue Query 提供的是扁平化查询缓存而非规范化缓存明确这一点后你就能在绝大多数应用场景中安全地享受这套轻量、可预测的 GraphQL 数据获取方案。【免费下载链接】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），仅供参考