前端【免费下载链接】urqlThe highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.项目地址https://gitcode.com/gh_mirrors/ur/urql点击查看免费下载导读本文围绕仓库中的examples/with-solid-start示例展开讲解如何在 SolidStart 全栈框架中集成 URQL GraphQL 客户端涵盖Provider上下文注入、createQuery查询、路由级预加载preload、服务端渲染SSR自动水合以及 Suspense 集成。读完本文你将掌握在 SolidStart 项目中完整配置 URQL 客户端、编写带缓存键的查询、通过 SolidStart action 机制执行 mutation以及理解 SSR 数据流在服务端与客户端之间的传递原理。示例概览与项目结构examples/with-solid-start是一个基于 SolidStart 的 Pokemon 列表演示应用核心目标是展示 URQL 与 SolidStart 原生原语query、action、createAsync如何协同工作。示例目录结构如下src/app.tsx—— 创建 URQL 客户端、配置 exchanges并挂载Router与Providersrc/routes/index.tsx—— 首页路由演示createQuery查询、createMutation提交、路由预加载与 Suspenseapp.config.ts—— SolidStart 配置文件package.json—— 依赖与启动脚本使用vinxi dev驱动开发服务器tsconfig.json—— 基于solid-js的 JSX 配置jsx: preserve、jsxImportSource: solid-js。对应的运行时依赖见 examples/with-solid-start/package.json包括urql/core^6.0.3—— URQL 核心运行时urql/solid-start^0.2.0—— 面向 SolidStart 的集成包solidjs/router^0.15.4与solidjs/start^1.2.1—— 路由与框架原语solid-js^1.9.10—— 响应式核心vinxi^0.5.0—— 开发/构建工具。启动命令pnpm start实际执行vinxi devpnpm install pnpm start随后在浏览器打开http://localhost:3000即可看到 Pokemon 列表页与新增 Pokemon 表单。客户端初始化与 Provider 注入在 SolidStart 应用中URQL 客户端在 src/app.tsx 中创建并注入import { Router, action, query } from solidjs/router; import { FileRoutes } from solidjs/start/router; import { Suspense } from solid-js; import { createClient, Provider, cacheExchange, fetchExchange, } from urql/solid-start; const client createClient({ url: https://trygql.formidable.dev/graphql/basic-pokedex, exchanges: [cacheExchange, fetchExchange], }); export default function App() { return ( Router root{props ( Provider value{{ client, query, action }} Suspense{props.children}/Suspense /Provider )} FileRoutes / /Router ); }几个关键点客户端配置createClient接收url和exchanges两个核心选项。cacheExchange提供文档级缓存document cachefetchExchange负责实际发送 fetch 请求两者共同构成最基础的 exchange 管线。Provider 注入三件套urql/solid-start的Provider接收{ client, query, action }三个值其中query与action直接来自solidjs/router这样createQuery与createMutation就能通过 SolidStart 上下文自动取得路由原语无需手动逐层传参。这一点在 packages/solid-start-urql/src/context.ts 中有明确实现Provider只是createContextUrqlContext()的.Provider而useClient()、useQuery()、useAction()三个 hook 分别从该上下文取出对应值并在缺失时抛出 No client/context/action has been specified using urqls Provider 的开发期错误。Suspense 边界在Router的 root 中包裹Suspense为后续路由预加载和createAsync提供的 suspense 数据源提供回退渲染能力。值得注意urql/solid-start的入口 packages/solid-start-urql/src/index.ts 还导出了createSubscription以及urql/core的全部内容gql、类型等因此在示例页面中可以直接从urql/solid-start引入gql编写查询文档。查询createQuery createAsync 组合示例首页 src/routes/index.tsx 中查询被组织成文档 → 查询函数 → async 数据源三步import { createAsync, useAction, useSubmission } from solidjs/router; import { gql } from urql/core; import { createQuery, createMutation } from urql/solid-start; const POKEMONS_QUERY gql query Pokemons { pokemons(limit: 10) { id name } } ; // 在组件顶层创建查询函数 const queryPokemons createQuery(POKEMONS_QUERY, list-pokemons); // 交给 createAsync 获得响应式数据源 const result createAsync(() queryPokemons());createQuery的底层实现位于 packages/solid-start-urql/src/createQuery.ts其签名与内部流程如下createQueryData, Variables( queryDocument: DocumentInputData, Variables, key: string, options?: { variables?: Variables; requestPolicy?: RequestPolicy; context?: PartialOperationContext; } )它的实现要点自动获取 query 原语函数内部调用useQuery()从 Provider 中取出 SolidStart 的query函数再将其包装成可复用的查询函数并注册到路由缓存中缓存键就是传入的key如示例中的list-pokemons。参数重载判断包装后的函数通过判断首参是否具有executeQuery方法即是否为Client实例来区分两种调用方式——传入 client 或仅传 variables。示例中createAsync(() queryPokemons())属于第二种此时内部自动调用useClient()获取客户端。构造请求并执行最终使用createRequest(queryDocument, variables)构造Operation合并requestPolicy与context覆盖项调用client.executeQuery(request, finalContext).toPromise()返回 Promise。返回的数据结构是 URQL 标准的OperationResult包含data、error、stale、operation等字段组件中通过result()!.data!.pokemons访问结果并用Show与For渲染列表Suspense fallback{pLoading.../p} Show when{result() result()!.data} ul For each{result()!.data!.pokemons} {pokemon li{pokemon.name}/li} /For /ul /Show /Suspense关于缓存键与请求策略key是必须提供的它作为 SolidStart 路由层的缓存与去重键。缓存键应具备应用内唯一性、语义化如user-profile、todos-list与可读性便于调试。options.requestPolicy可控制缓存行为四种取值与语义如下策略行为cache-first默认命中缓存直接用否则发起网络请求cache-only只读缓存绝不发起网络请求network-only忽略缓存总是请求网络cache-and-network先返回缓存数据再后台发起网络请求刷新若查询依赖响应式变量可通过options.variables传入信号值或在调用查询函数时以变量作为首参const queryUser createQuery(UserQuery, user-details, { variables: { id: userId() }, }); const user createAsync(() queryUser());路由级预加载Route Preloading示例 README 中重点强调的路由预加载是 SolidStart 的核心能力在路由组件渲染之前就开始发起数据请求让页面挂载时数据已就绪配合 Suspense 实现无闪烁渲染。README 中给出的骨架如下export const route { preload: () { const pokemons createQuery({ query: POKEMONS_QUERY }); return pokemons(); // Start fetching }, } satisfies RouteDefinition;在当前示例中preload与createQuery的组合可以理解为把createQuery创建的查询函数放在route.preload内执行提前触发client.executeQuery返回的 Promise 在路由渲染前即开始解析随后组件内的createAsync(() queryPokemons())会复用同一查询函数及其结果避免重复请求。这正是 SolidStartquery原语与 URQL 缓存机制共同作用的结果——同一缓存键key下的查询会被去重。服务端渲染与自动水合README 明确说明查询在 SSR 阶段于服务端自动执行并在客户端水合时直接复用服务端数据不会重新请求refetch。这也是urql/solid-start区别于urql/solid的根本原因urql/solid面向纯客户端 SPA使用 SolidJS 原生响应式模式createQuery返回[AccessorOperationResult, ReExecute]urql/solid-start面向 SolidStart SSR 应用查询包装成路由query原语并配合createAsync消费mutation 则包装成路由action原语。从 packages/solid-start-urql/README.md 的对照表可以看出urql/solid-start的查询在服务端执行、通过流式响应传输到客户端水合阶段不再重复发起请求从而获得自动 SSR、请求去重、流式响应、action 渐进增强与细粒度响应式五项能力。如果只构建纯客户端 SolidJS 应用则应改用urql/solid对应实现见 packages/solid-urql/src/createQuery.ts 等文件。Mutation基于 SolidStart action 的渐进增强虽然示例 README 的 Features 列表只提到查询但 src/routes/index.tsx 实际还演示了完整的 mutation 流程这是理解urql/solid-start集成深度的关键补充const ADD_POKEMON_MUTATION gql mutation AddPokemon($name: String!) { addPokemon(name: $name) { id name } } ; // 在组件内部创建 mutation action必须能访问到 context const addPokemonAction createMutation(ADD_POKEMON_MUTATION, add-pokemon); const addPokemon useAction(addPokemonAction); const submission useSubmission(addPokemonAction); const handleSubmit async (e: Event) { e.preventDefault(); const name pokemonName(); if (!name) return; const result await addPokemon({ name }); if (result.data) { setPokemonName(); } };其底层实现见 packages/solid-start-urql/src/createMutation.tsexport function createMutationData, Variables( mutation: DocumentInputData, Variables, key: string ): CreateMutationActionData, Variables { const client useClient(); const action useAction(); return action( async (variables: Variables, context?: PartialOperationContext) { const request createRequest(mutation, variables); return pipe( client.executeMutation(request, context), filter(result !result.hasNext), take(1), toPromise ); }, key ); }关键设计必须调用自组件内部createMutation通过useClient()与useAction()读取 Provider 上下文因此不能在模块顶层调用——这正是示例源码中注释 Create the mutation action inside the component where it has access to context 的含义。返回的是 SolidStart ActionAction[variables, context?], OperationResult可配合useAction()执行、useSubmission()订阅状态submission.pending控制按钮禁用与文案切换submission.result展示错误或成功信息。这意味着表单在禁用 JavaScript 的环境下也能工作渐进增强这是纯客户端urql/solid的 mutation API 所不具备的。流式结果处理mutation 结果通过 wonka 的pipe管线过滤——filter(result !result.hasNext)丢弃增量结果take(1)只取第一个最终结果再toPromise转成 Promise 供await使用。运行与验证启动开发服务器后页面应呈现两部分Add Pokemon 表单输入名称提交后调用AddPokemonmutation按钮在 pending 状态显示 Adding... 并禁用成功时绿色提示 Added: 失败时红色显示submission.result.error.messagePokemon 列表由POKEMONS_QUERY渲染前 10 个 Pokemon加载期间显示 Loading... 回退数据到达后逐条渲染。验证 SSR 效果时可查看服务端响应中的 HTMLPokemon 列表应已内联在服务端渲染结果中客户端水合后不会对同一缓存键发起重复请求可通过开发者工具 Network 面板观察。与仓库其余部分的关联urql/solid-start建立在urql/core之上见 packages/core/src/index.tsclient 与 exchange 机制完全复用核心实现示例中的 GraphQL 文档类型TypedDocumentNode、错误结构CombinedError等也全部来自urql/core。若需要订阅subscription能力createSubscription同样由 packages/solid-start-urql/src/createSubscription.ts 提供它接受query、variables、context、pause四个可为响应式MaybeAccessor的参数并支持可选的累加 handler例如(prev [], data) [...prev, data.messageAdded]以支持实时消息流的增量展示。仓库中还包含面向其他框架的同类示例可供横向参考React 见 examples/with-reactSvelte 见 examples/with-svelteVue 见 examples/with-vue3客户端 SPA 版 Solid 集成则参考 examples/with-solid以及 docs/basics/solid-start.md 中的官方文档说明。赞分享前端【免费下载链接】urqlThe highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.项目地址https://gitcode.com/gh_mirrors/ur/urql点击查看免费下载相关推荐urql × SolidStart 集成指南用 urql/solid-start 打造服务端渲染的 GraphQL 应用urql × SolidStart 集成指南用 urql/solid start 打造服务端渲染的 GraphQL 应用 本指南系统讲解如何在 SolidS前端urql 与 Next.js 集成实战从 urql/next 的 RSC 与 SSR 模式到 pages 路由迁移指南urql 与 Next.js 集成实战从 urql/next 的 RSC 与 SSR 模式到 pages 路由迁移指南 导读 本指南以仓库中的 with n前端urql/next 集成指南在 Next.js App Router 中实现 urql 的 SSR 与 RSC 数据水合urql/next 集成指南在 Next.js App Router 中实现 urql 的 SSR 与 RSC 数据水合 导读 urql/next 仓库前端上一篇Leantime部署指南多环境配置与CI/CD集成下一篇co代码风格异步编程ESLint配置终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考