urql 订阅（Subscriptions）完整实战指南：subscriptionExchange、fetch 流式传输与多框架 useSubscription 深入解析

前端【免费下载链接】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在“基础Basics”章节之外还提供了一套完整、可插拔的 GraphQL 订阅Subscription能力。本指南以 docs/advanced/subscriptions.md 为核心骨架从subscriptionExchange的接入方式、graphql-ws与subscriptions-transport-ws两种 WebSocket 传输的配置到fetchSubscriptions的 HTTP 流式订阅再到 React/Preact、Svelte、Vue 三套框架绑定及脱离框架的一键订阅用法逐一展开同时结合本仓库 packages/core 与各框架绑定的源码实现说明底层的数据流与调用链。读完本文你将能够为任意urql应用接入实时数据通道并理解订阅结果是如何从传输层一路汇聚到 UI 的。订阅与urql的交换器Exchange机制在 Basics 章节 中我们了解了urql的基本用法但订阅这一能力依赖urql的Exchange交换器管线。简单来说Client会把所有 GraphQL 操作query、mutation、subscription、teardown组织成一条 Wonka 流依次送入由开发者配置的 exchanges 列表每个 Exchange 都可以对操作流进行过滤、转发或注入结果流。关于 Exchange 的完整机制可参见 Authoring Exchanges 文档 与 架构说明。订阅之所以特殊是因为它不像 query 那样“请求一次、返回一次”而是需要长期维持一个连接并持续推送多个结果。因此urql并不内置任何 WebSocket 传输实现而是通过一个通用工厂函数subscriptionExchange把“如何与服务器通信”完全交给开发者。接入订阅subscriptionExchange与forwardSubscription要为Client添加订阅能力需要把subscriptionExchange加入exchanges数组并传入一个forwardSubscription函数import { Client, cacheExchange, fetchExchange, subscriptionExchange } from urql; const client new Client({ url: http://localhost:3000/graphql, exchanges: [ cacheExchange, fetchExchange, subscriptionExchange({ forwardSubscription, }), ], });从源码看subscriptionExchange 工厂 接收一个配置对象并返回真正的 Exchange 函数。它不对传输协议做任何假设——无论是 WebSocket、SSE 还是其他自定义协议都由你传入的forwardSubscription来适配。forwardSubscription会在subscriptionExchange收到一个订阅Operation时被调用见 subscription.ts 中forwardSubscription(makeFetchBody(operation), operation)的调用并接收一个GraphQL 请求体其形状与 GraphQL over HTTP 的 JSON 请求输入一致。该请求体由makeFetchBody生成fetchOptions.ts包含以下字段queryGraphQL 文档字符串可选documentId持久化文档标识可选启用 APQ / persisted queries 时出现operationName操作名variables变量对象或undefinedextensions扩展字段或undefined。如果你使用 TypeScript可能会注意到forwardSubscription收到的输入中query是可选属性。这正是因为**持久化查询persisted queries**的支持当请求已被持久化、无需再携带文档全文时query可以省略。对于某些传输协议你可能需要把它默认成空字符串以更贴近 GraphQL over HTTP 规范——这也是下文graphql-ws示例中query: request.query || 这一行的由来。forwardSubscription的完整类型定义在 subscription.tsexport type SubscriptionForwarder ( request: FetchBody, operation: Operation ) ObservableLikeExecutionResult;它必须返回一个Observable-like 对象即遵循 TC39 Observable 提案tc39/proposal-observable。可选配置enableAllOperations与isSubscriptionOperationsubscriptionExchange除了必填的forwardSubscription还支持两个可选配置见 SubscriptionExchangeOptsenableAllOperations?: boolean默认false此时 Exchange 只处理subscription类型的操作。如果你没有使用 fetchExchange / GraphQL over HTTP 作为 query 与 mutation 的传输例如第三方自定义传输可以设为true让该 Exchange 处理所有操作类型query 与 mutation 也会走forwardSubscription。isSubscriptionOperation?: (operation) boolean一个谓词函数用于精确决定哪些Operation由本 Exchange 处理。典型场景是只处理带有live指令的操作当传入该函数时enableAllOperations会被忽略。这两个选项在源码中的落地逻辑位于 subscription.ts默认判定条件是operation.kind subscription再叠加enableAllOperations对 query/mutation 的放行若提供了isSubscriptionOperation则完全以它的返回值为准。Exchange 内部还会把teardown操作与已订阅操作按key配对用takeUntil(teardown$)在取消订阅时终止结果流subscription.ts。另外源码中对订阅结果做了**增量合并incremental**处理当传输层连续推送多个ExecutionResult时后续结果通过mergeResultPatch与首条结果合并subscription.ts这为defer/stream风格的分片结果提供了兼容若传输层在error回调里传入的是GraphQLError[]数组graphql-ws可能出现这种情况也会被转换为{ errors }结果而非直接抛出subscription.ts。订阅流结束时若结果仍有hasNext则补充一条{ hasNext: false }否则对subscription操作回发一个teardown以清理底层连接subscription.ts。方案一使用graphql-ws作为 WebSocket 传输对于支持graphql-ws协议的服务器官方推荐使用graphql-ws客户端该包实现了新版 GraphQL over WebSocket 协议社区更活跃。import { Client, cacheExchange, fetchExchange, subscriptionExchange } from urql; import { createClient as createWSClient } from graphql-ws; const wsClient createWSClient({ url: ws://localhost/graphql, }); const client new Client({ url: /graphql, exchanges: [ cacheExchange, fetchExchange, subscriptionExchange({ forwardSubscription(request) { const input { ...request, query: request.query || }; return { subscribe(sink) { const unsubscribe wsClient.subscribe(input, sink); return { unsubscribe }; }, }; }, }), ], });要点拆解createWSClient({ url })创建graphql-ws的底层 WebSocket 客户端forwardSubscription把urql的请求体展开为input并将可能缺失的query兜底为空字符串随后调用wsClient.subscribe(input, sink)返回{ subscribe(sink) { ... } }这个 Observable-like 对象urql会在订阅启动时调用subscribe并把sink即urql内部的 observer包含next/error/complete透传给graphql-wswsClient.subscribe返回的unsubscribe会被urql保存用于组件卸载或 teardown 时终止连接。方案二使用subscriptions-transport-wsApollo 旧协议如果你的服务器只支持旧版subscriptions-transport-ws协议可以使用 Apollo 的subscriptions-transport-ws包。注意该包已不再活跃维护如果 API 支持新协议、或可以替换依赖建议优先使用graphql-ws。import { Client, cacheExchange, fetchExchange, subscriptionExchange } from urql; import { SubscriptionClient } from subscriptions-transport-ws; const subscriptionClient new SubscriptionClient(ws://localhost/graphql, { reconnect: true }); const client new Client({ url: /graphql, exchanges: [ cacheExchange, fetchExchange, subscriptionExchange({ forwardSubscription: request subscriptionClient.request(request), }), ], });这里创建了一个SubscriptionClient传入 URL 与选项如reconnect: true自动重连然后直接利用其request方法返回的 Subscription Observable 作为forwardSubscription的返回值实现最为精简。其余数据流与graphql-ws方案完全一致。方案三通过fetch执行订阅SSE / multipart 流式响应部分 GraphQL 后端例如 GraphQL Yoga内置了基于 HTTP 的流式传输协议可以直接通过一次fetch调用执行订阅。事实上defer与stream指令正是依赖这类传输实现的同一套机制也适用于订阅。此时甚至不需要subscriptionExchangeimport { Client, cacheExchange, fetchExchange, subscriptionExchange } from urql; const client new Client({ url: /graphql, fetchSubscriptions: true, exchanges: [cacheExchange, fetchExchange], });只需在Client上开启fetchSubscriptions: truefetchExchange就会接管订阅操作并把它作为 GraphQL over HTTP 请求发出只要后端支持服务器就会把订阅结果以流式响应持续推送给fetchExchange。从源码看这条路径的底层逻辑非常清晰Client会把fetchSubscriptions写入每个操作的contextclient.tsfetchExchange 的过滤条件为operation.kind ! subscription || !!operation.context.fetchSubscriptions即只有开启该选项后订阅操作才会被 fetch 处理否则订阅操作会被原样转发给下游fetch.tsmakeFetchOptions 对订阅请求会自动设置accept: text/event-stream, multipart/mixed头表明客户端愿意接收 SSE 与 multipart 两种流式响应。本仓库提供了一个可直接运行的完整示例examples/with-subscriptions-via-fetch。其中 App.jsx 以fetchSubscriptions: true结合 Graphcache 使用并在updates.Subscription中把订阅到的alphabet事件写入缓存Songs.jsx 则用useSubscription配合 reducer 把每次推送的字符累积成列表展示是“fetch 订阅 缓存联动”的完整范例。React 与 PreactuseSubscription钩子与 reducer 聚合useSubscription的 API 与我们在 React/Preact 的 Queries 章节 中学到的useQuery极为相似它接受一个选项对象其中可以包含query与variables不同之处在于它还有第二个参数——一个 reducer 函数语义上类似传给Array.prototype.reduce的回调。reducer 的第一个参数是“上一次该函数返回的数据”首次为undefined第二个参数是订阅推送进来的事件数据。你可以借此随时间累积数据——例如把一条条消息拼成一个列表。下面是一个订阅“新消息”事件的示例handleSubscription把新消息插到数组头部实现跨事件的累计展示import React from react; import { useSubscription } from urql; const newMessages subscription MessageSub { newMessages { id from text } } ; const handleSubscription (messages [], response) { return [response.newMessages, ...messages]; }; const Messages () { const [res] useSubscription({ query: newMessages }, handleSubscription); if (!res.data) { return pNo new messages/p; } return ( ul {res.data.map(message ( p key{message.id} {message.from}: {message.text} /p ))} /ul ); };可以看到res.data被handleSubscription持续更新与变换随着新消息不断到达旧消息列表会被依次追加UI 也随之刷新。源码视角钩子内部如何工作React 版本的实现位于 packages/react-urql/src/hooks/useSubscription.ts几个值得注意的点参数类型UseSubscriptionArgs在query、variables之外还支持pause置为true时暂停自动启动订阅与context用于覆盖OperationContext官方建议用useMemo包裹以避免无限重渲染见 useSubscription.tsreducer 的类型SubscriptionHandlerT, R (prev: R | undefined, data: T) RuseSubscription.ts与文档描述完全一致返回结构返回[result, executeSubscription]元组。result是包含fetching、stale、data、error、extensions、operation的状态对象useSubscription.tsexecuteSubscription用于命令式地重启或解除pause后启动订阅useSubscription.ts状态合并updateResult在收到新结果时先计算nextResult若配置了 handler 且新数据非空则调用handlerRef.current(prevData, nextData)完成聚合后再setStateuseSubscription.ts。Preact 版本的useSubscription实现位于 packages/preact-urql/src/hooks/useSubscription.tsAPI 形态与 React 完全一致。更多参数细节可参考 useSubscription API 文档。SveltesubscriptionStoreurql/svelte提供的subscriptionStore与 Svelte 的 Queries 章节 中介绍过的query类似它接受一个通常包含订阅查询的 store 参数。以下示例同样监听新消息script import { gql, getContextClient, subscriptionStore } from urql/svelte; const messages subscriptionStore({ client: getContextClient(), query: gql subscription MessageSub { newMessages { id from text } } , }); /script {#if !$messages.data} pNo new messages/p {:else} ul {#each $messages.data.newMessages as message} li{message.from}: {message.text}/li {/each} /ul {/if}与 React/Vue 一样$messages.data会随订阅推送持续更新subscriptionStore也可选地接受第二个参数——handler 函数用于定制订阅数据的更新行为例如把逐条事件聚合成列表。从 subscriptionStore 源码 看SubscriptionArgs在query、variables之外还接受client必填可用getContextClient()从 Svelte context 取得、context与pausesubscriptionStore.ts。内部实现上它通过 Wonka 的switchMap订阅client.executeRequestOperation(operation)再用scan逐条聚合结果——若传入了 handler则handler(result.data, partial.data)的结果会成为新的datasubscriptionStore.ts返回的 store 还实现了Pausable提供pause()/resume()。更多细节见 subscriptionStore API 文档。VueuseSubscriptionVue 的useSubscriptionAPI 同样与 Vue 的 Queries 章节 中的useQuery高度相似接受包含query与variables的选项对象同时接受第二个参数——reducer 函数用于把历史数据与最新事件合并。template div v-iferror Oh no... {{error}} /div div v-else ul v-ifdata li v-formsg in data{{ msg.from }}: {{ msg.text }}/li /ul /div /template script import { useSubscription } from urql/vue; export default { setup() { const handleSubscription (messages [], response) { return [response.newMessages, ...messages]; }; const result useSubscription({ query: subscription MessageSub { newMessages { id from text } } , }, handleSubscription) return { data: result.data, error: result.error, }; } }; /scriptresult.data会被handleSubscription持续变换新消息不断被追加到历史列表前。Vue 版本的实现在 packages/vue-urql/src/useSubscription.tsuseSubscription(args, handler)返回UseSubscriptionResponse对象其中data、error、extensions等都是响应式RefuseSubscription.ts返回对象还带有executeSubscription方法用于命令式重开订阅。更完整的参数说明见 useSubscription API 文档。一次性订阅Client.subscription与 Wonka 流在不使用任何框架绑定的场景例如纯 Node.js 环境直接执行订阅时可以使用Client的subscription方法——它与 Core Package 章节 中介绍过的 query/mutation 方法类似但始终返回一个 Wonka 流且没有.toPromise()快捷方法Promise 只能承载单个值而订阅会持续推送多个结果。把上面的消息订阅改写成脱离框架的形式import { gql } from urql/core; const MessageSub gql subscription MessageSub { newMessages { id from text } } ; const { unsubscribe } client.subscription(MessageSub).subscribe(result { console.log(result); // { data: ... } });subscribe返回的{ unsubscribe }句柄用于在不再需要时主动终止订阅。从源码看Client.subscription(query, variables, context)本质上是对client.executeSubscription(createRequest(query, variables), context)的薄封装client.ts而executeSubscription生成的流会进入 exchange 管线、最终由subscriptionExchange或fetchSubscriptions模式下的fetchExchange执行。关于 Wonka 流的背景知识pipe、subscribe、takeUntil等操作符的语义可参考 架构文档中的 Wonka 库一节。小结选择哪种订阅方案场景推荐方案关键配置服务器支持 GraphQL over WebSocket 新协议graphql-wssubscriptionExchange({ forwardSubscription })服务器仅支持 Apollo 旧协议subscriptions-transport-ws不活跃维护建议迁移forwardSubscription: request subscriptionClient.request(request)服务器支持 SSE / multipart 流式 HTTP如 GraphQL Yoga纯fetchExchangeClient上fetchSubscriptions: true无框架环境Node.js 等client.subscription(...)消费返回的 Wonka 流所有方案共享同一套框架侧消费方式React/Preact 用useSubscription、Svelte 用subscriptionStore、Vue 用useSubscription并均可通过可选的 reducer/handler 把逐条事件累积为 UI 列表。若想进一步验证subscriptionExchange的行为可在本仓库运行其单元测试 subscription.test.ts其中覆盖了结果透传、forwardSubscription收到的请求体形状、完成后回发 teardown 等核心路径。赞分享前端【免费下载链接】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点击查看免费下载相关推荐HSTrackermacOS平台终极炉石传说套牌追踪器完全指南HSTrackermacOS平台终极炉石传说套牌追踪器完全指南 还在为炉石传说对战中记不住对手卡牌而烦恼吗想要科学管理自己的卡组收藏却无从下手HSTrac前端Relay useSubscription 完全指南在 React 组件中优雅地订阅 GraphQL SubscriptionsRelay useSubscription 完全指南在 React 组件中优雅地订阅 GraphQL Subscriptions useSubscriptio前端开发工具Relay 20 声明式订阅实战useSubscription 钩子完全指南Relay 20 声明式订阅实战useSubscription 钩子完全指南 本文基于当前仓库 relay29/relay 中 useSubscription前端开发工具上一篇Flutter Starter Kit代码生成指南json_serializable实现自动序列化下一篇Warp权限管理多用户环境的安全配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考