Relay 中的 GraphQL Subscriptions 实战指南:useSubscription、事件驱动更新与网络层配置

发布时间:2026/11/17 0:57:04

Relay 中的 GraphQL Subscriptions 实战指南:useSubscription、事件驱动更新与网络层配置 Relay 中的 GraphQL Subscriptions 实战指南useSubscription、事件驱动更新与网络层配置【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay本指南以 Relay v14 文档体系中的 graphql-subscriptions 为核心系统讲解如何在数据驱动的 React 应用中通过 GraphQL subscriptions 订阅服务端事件流并借助useSubscription、requestSubscription等 API 将实时数据写入 Relay store、驱动组件重渲染。读完本文你将掌握订阅的声明方式、GraphQLSubscriptionConfig的完整配置项、事件回调、声明式指令与命令式 updater以及如何在网络层接入graphql-ws或subscriptions-transport-ws完成订阅通道的搭建。什么是 GraphQL SubscriptionGraphQL subscriptions 是一种允许客户端响应服务端事件流stream of server-side events来查询数据的机制。与普通 query 相比它最直观的区别是使用了subscription关键字而非querysubscription FeedbackLikeSubscription($input: FeedbackLikeSubscribeData!) { feedback_like_subscribe(data: $input) { feedback { like_count } } }理解这段订阅需要把握两个关键点建立订阅通道使用这段 GraphQL 建立订阅后每当feedback_like_subscribe事件流上有事件被发出应用就会被通知。feedback_like_subscribe是一个subscription root field订阅根字段也称 subscription field它在后端负责建立订阅。事件驱动查询与 mutation 类似订阅的处理分两步进行——首先服务端发生一个事件然后才执行查询。注意事件流本身可以是完全任意的它可以与所选字段毫无关系即没有任何保证保证订阅中选中的值会在两次通知之间发生变化。feedback_like_subscribe返回一个特定的 GraphQL 类型该类型暴露了我们可以响应服务端事件而查询的数据。在本例中我们查询 Feedback 对象及其更新后的like_count从而实时展示点赞数。客户端收到的一份订阅负载大致如下{ feedback_like_subscribe: { feedback: { id: feedback-id, like_count: 321 } } }在 Relay 中声明 Subscription在 Relay 中订阅同样使用graphql标签来声明const {graphql} require(react-relay); const feedbackLikeSubscription graphql subscription FeedbackLikeSubscription($input: FeedbackLikeSubscribeData!) { feedback_like_subscribe(data: $input) { feedback { like_count } } } ;与 query 和 fragment 一致订阅同样支持引用 GraphQL 变量。这里FeedbackLikeSubscribeData这个类型名派生自顶层订阅字段feedback_like_subscribe并且会从 Relay compiler 生成的graphql.js文件中导出。使用 useSubscription 建立订阅创建订阅有两种 APIuseSubscriptionHook 形式和requestSubscription命令式形式。下面是使用useSubscription的完整示例import type {Environment} from react-relay; import type {FeedbackLikeSubscribeData} from FeedbackLikeSubscription.graphql; const {graphql, useSubscription} require(react-relay); const {useMemo} require(React); function useFeedbackSubscription( input: FeedbackLikeSubscribeData, ) { const config useMemo({ subscription: graphql subscription FeedbackLikeSubscription( $input: FeedbackLikeSubscribeData! ) { feedback_like_subscribe(data: $input) { feedback { like_count } } } , variables: {input}, }, [input]) return useSubscription(config); }GraphQLSubscriptionConfig 的完整字段useSubscription接收一个GraphQLSubscriptionConfig对象其核心字段包括subscription包含订阅的 GraphQL 字面量variables用于建立订阅的变量。从 requestSubscription.js 的类型定义可以看到GraphQLSubscriptionConfig还支持以下可选字段字段类型作用subscriptionGraphQLSubscriptionTVariables, TData, TRawResponse订阅操作的 GraphQL 字面量必填variablesNoInferTVariables建立订阅所需变量必填onCompleted?() void服务端结束订阅时执行的回调onError?(error: Error) void订阅出错时执行的回调onNext?(response: ?TData) void收到订阅负载时执行的回调updater?SelectorStoreUpdaterTData命令式更新 store 的函数configs?ArrayDeclarativeMutationConfig声明式变更配置与updater二选一cacheConfig?CacheConfig缓存配置此外useSubscription还接受一个 Flow 类型参数。与 query 一样订阅的 Flow 类型从 Relay compiler 生成的文件中导出提供该类型后GraphQLSubscriptionConfig也会被静态类型检查——始终提供该类型是官方推荐的最佳实践。订阅的生命周期行为从 useSubscription.js 的源码可以看出 Hook 的完整生命周期逻辑当useFeedbackSubscription这个 Hook 挂载commit时Relay 才会建立订阅。与useLazyLoadQuery这类 API 不同Relay不会在渲染阶段render phase建立订阅而是通过useEffect在组件挂载后执行requestSubscription(environment, config)订阅建立后一旦事件发生后端会选中更新后的 Feedback 对象并取出like_count字段。由于Feedback类型包含id字段Relay compiler 会自动为其补充id的 selection收到订阅响应后Relay 会在 store 中找到id匹配的 feedback 对象并用新收到的like_count更新它如果这些值因此发生变化任何选中了这些字段的组件都会被重新渲染——通俗地说凡是依赖该数据的组件都会刷新。源码同时给出了一个强制警告useSubscription的依赖数组是[environment, config, actualRequestSubscription]也就是说传给useSubscription的GraphQLSubscriptionConfig对象必须被 memoized例如用useMemo否则每次渲染都会先 dispose 掉旧订阅再重新建立订阅造成无谓的重复订阅。源码中的注释也明确写道this will re-subscribe every render if config or requestSubscriptionFn are not memoized. Please do not pass an object defined in-line.如果 config 或 requestSubscriptionFn 未被 memoize则每次渲染都会重新订阅请勿传入内联定义的对象。useSubscription 的测试 也验证了这些行为组件挂载时调用requestSubscription卸载时调用其返回的dispose环境environment变化时先 dispose 再重新订阅。底层执行链路requestSubscription的实现展示了订阅从配置到执行的完整链路见 requestSubscription.js通过getRequest(config.subscription)获取请求定义并校验operationKind必须为subscription否则抛出requestSubscription: Must use Subscription operation用createOperationDescriptor基于订阅与变量创建操作描述符若同时提供updater与configs会触发 warning两者只能取其一提供configs时通过RelayDeclarativeMutationConfig.convert将其转换为 updater调用environment.executeSubscription({operation, updater})获得一个 RelayObservable 并订阅它将complete、error、next分别映射到onCompleted、onError、onNext返回{dispose: sub.unsubscribe}即订阅的销毁句柄。其中onNext的实现细节值得一提收到响应后Relay 会检查响应的extensions.__relay_subscription_root_id若存在则以该 id 构建 reader selector并通过environment.lookup(selector)从 store 中读出数据再传给onNext——也就是说onNext收到的响应数据在 fragment spread 边界处停止。而executeSubscription定义在 RelayModernEnvironment.js它返回一个 Observable其中每次结果都会被归一化normalize并提交到发布队列publish queue。注意 Observable 是惰性的——必须有人订阅它才会真正触发网络请求。使用 Fragment Spread 刷新组件在前面的例子中我们手动选中了like_count。选中该字段的组件会在收到更新值后被重渲染。但更推荐的做法是spread 与要刷新的组件对应的 fragment。这是因为组件选中的数据可能随时变化如果要求开发者知道所有可能获取其组件数据的订阅并持续维护它们就违背了 Relay 想要避免的全局推理global reasoning原则。例如我们可以把订阅改写为subscription FeedbackLikeSubscription($input: FeedbackLikeSubscribeData!) { feedback_like_subscribe(data: $input) { feedback { ...FeedbackDisplay_feedback ...FeedbackDetail_feedback } } }现在每当feedback_like_subscribe事件流上发生事件FeedbackDisplay和FeedbackDetail组件选中的数据都会被重新获取从而让这些组件始终保持在一致状态。Spread fragment 通常优于在订阅事件中手动 refetch 数据因为更新后的数据可以在一次往返single round trip内获取。订阅事件回调onNext、onError、onCompleted除了把更新数据写入 Relay store我们还可能希望在收到订阅负载、出现错误或服务端关闭订阅时执行回调。GraphQLSubscriptionConfig提供了三个回调字段onNext收到订阅负载时执行回调参数是订阅响应数据在 fragment spread 边界处停止与上文源码行为一致onError订阅出错时执行回调参数为发生的错误ErroronCompleted服务端结束订阅时执行。声明式指令Declarative Directives订阅同样支持 声明式 mutation 指令 以及deleteRecord指令。响应订阅事件操作连接ConnectionRelay 让你可以轻松地响应订阅事件向连接即列表中添加或移除条目。例如你可能想把一个新创建的用户追加到某个连接中。具体用法请参考 使用声明式指令 章节。响应订阅事件删除记录如果你想响应订阅事件从 store 中删除某个条目可以在被删除的 id 上添加deleteRecord指令subscription DeletePostSubscription($input: DeletePostSubscribeData!) { delete_post_subscribe(data: $input) { deleted_post { id deleteRecord } } }关于 mutation 场景下的删除可进一步参考 mutation 中删除条目 的说明。命令式修改本地数据updater 函数有时你需要的更新比单纯修改字段值更复杂声明式指令无法覆盖。此时GraphQLSubscriptionConfig的updater函数可以派上用场——它给予你对 store 更新方式的完全控制。updater的类型是SelectorStoreUpdaterTData其签名定义于 RelayStoreTypes.jsexport type SelectorStoreUpdaterin TMutationResponse ( store: RecordSourceSelectorProxy, data: ?TMutationResponse, ) void;即它接收一个绑定到特定 selector 的 store proxy以及订阅响应数据data通过 proxy 提供的 API 命令式地读写 store。完整讨论参见 命令式修改 store 数据 章节。配置网络层Network Layer订阅需要网络层支持。从源码看RelayNetwork.js 的Network.create(fetchFn, subscribe?)接受一个可选的subscribe函数当执行的操作operationKind subscription时若未提供subscribe会抛出 invariant 错误RelayNetwork: This network layer does not support Subscriptions. To use Subscriptions, provide a custom network layer.SubscribeFunction的类型定义为见 RelayNetworkTypes.jsexport type SubscribeFunction ( request: RequestParameters, variables: Variables, cacheConfig: CacheConfig, ) RelayObservableGraphQLResponse;即订阅函数接收请求参数、变量与缓存配置返回一个可产出零个或多个原始服务端响应的RelayObservable。GraphQL subscriptions 通常通过 WebSocket 通信。下面是基于graphql-ws的网络层配置示例import { ... Network, Observable } from relay-runtime; import { createClient } from graphql-ws; const wsClient createClient({ url:ws://localhost:3000, }); const subscribe (operation, variables) { return Observable.create((sink) { return wsClient.subscribe( { operationName: operation.name, query: operation.text, variables, }, sink, ); }); } const network Network.create(fetchQuery, subscribe);也可以使用较早的subscriptions-transport-ws库import { ... Network, Observable } from relay-runtime; import { SubscriptionClient } from subscriptions-transport-ws; const subscriptionClient new SubscriptionClient(ws://localhost:3000, { reconnect: true, }); const subscribe (request, variables) { const subscribeObservable subscriptionClient.request({ query: request.text, operationName: request.name, variables, }); // Important: Convert subscriptions-transport-ws observable type to Relays return Observable.from(subscribeObservable); }; const network Network.create(fetchQuery, subscribe);注意第二种方案中需要显式把subscriptions-transport-ws的 observable 类型转换为 Relay 的RelayObservable。完整配置说明可参考 网络层配置指南。小结GraphQL subscriptions 是构建实时数据驱动 React 应用的关键机制。通过本指南你可以掌握用subscription关键字声明订阅根字段、用useSubscription在组件挂载时建立订阅并牢记对 config 做 memoize、借助 fragment spread 让依赖组件自动刷新、用onNext/onError/onCompleted处理事件流生命周期、用声明式指令与updater灵活更新 store以及通过graphql-ws等库为网络层接入 WebSocket 订阅通道。配合源码层面的执行链路理解requestSubscription→environment.executeSubscription→RelayNetwork.execute的 subscribe 分支你就能在真实项目中可靠地实现点赞实时计数、评论实时列表、删除同步等典型实时场景。【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/16 5:19:37

2018ces源码解析:3步搭好项目,告别只会语法

2018ces源码解析:3步搭好项目,告别只会语法 还在对着IDE发呆吗?你会写 print("hello") ,但一让搭个能跑的项目就懵。别急,今天咱们不整虚的,直接上 2018ces源码解析…

2026/11/16 13:48:22

Java 21+Spring Boot 3构建企业级RAG与智能体工作流

1. 项目概述:为什么在企业级AI工程中,Java 21 Spring Boot 3 是 RAG 与智能体落地的“稳态选择”别卷 Python 了——这句话不是唱衰 Python,而是直击当前 AI 工程化落地中最常被忽视的现实矛盾:原型快 ≠ 上线稳,单点…

2026/11/17 0:53:09

石家庄电焊本电工证怎么考才不被坑?电子证书怎么查?

石家庄电焊本电工证怎么考才不被坑?电子证书怎么查? 不知道去哪报名怕被中介坑?别慌,石家庄电焊本电工证的报考流程其实并不复杂,关键是选对正规渠道。现在很多学员都因为找错了培训机构,结果花了几千块还拿不到电子证书,或者证书被查不到。今天就带你…

2026/11/17 0:53:09

平顶山电工想考低压电工证是哪一个正?通过率揭秘全在这了

平顶山电工想考低压电工证是哪一个正?通过率揭秘全在这了 你现在正为找工作发愁,手上缺一张低压电工证,但不知道低压电工证是哪一个正,更不知道哪里靠谱,考试难不难通过,是不是要花大钱找机构?别急,本文专为像你这样急需特种作业证上岗的平顶山在职建…

2026/11/17 0:53:09

中级维修电工证购买多少钱才能一次过?这3点必须知道

中级维修电工证购买多少钱才能一次过?这3点必须知道 怕考不过白交培训费?中级维修电工证购买确实让人头疼,尤其是当你花了大价钱报名,却连题都看不懂的时候。别急,这篇文章帮你梳理清楚怎么买、怎么学、怎么考,不踩坑。…

2026/11/17 0:53:09

北京市低压电工证办理怕考不过白交培训费?官方报名入口全解析

北京市低压电工证办理怕考不过白交培训费?官方报名入口全解析 怕考不过白交培训费?你不是一个人。尤其是像新乡劳务班组负责人这种天天跟电打交道的,考个低压电工证不是为了面子,而是为了安全和饭碗。今天咱们就聊聊【北京市低压电工证办理】这事儿,从官…

2026/11/17 0:53:09

电工证可以包括没有 怎么报名才能不被拒

电工证可以包括没有 怎么报名才能不被拒 你现在是不是正愁找不到工作?因为很多工地、工厂都明确要求 必须持有电工证 才能上岗。你可能已经听说过电工证的重要性,但不知道自己是不是符合报考条件,甚至不清楚“电工证可以包括没有”这句话到底是什么意思…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/17 0:02:41

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期 证书过期了不知道怎么复审延期,这种情况在电工圈里太常见了。我有个同事,去年刚把低压电工证给弄丢了,直到单位查岗才发现证书已经过期,差点被停工处理。今天就用我真实经历给你讲讲电工证操作…

2026/11/17 0:02:41

机修需不需要电工证 在哪考最靠谱 这些细节必须知道

机修需不需要电工证 在哪考最靠谱 这些细节必须知道 之前考的证在外省能不能转过来?这个问题几乎每个特种作业从业者都问过。特别是像你这样,之前在外省考了证,现在想在本地扎根,或者想换证、换岗的机修人员,最关心的就是【机修需不需要电工证】和【在…

2026/11/17 0:02:41

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么 工地太忙根本没时间复习考试,我理解你。作为一名刚从焦作工程类院校毕业的学生,我也经历过这种困扰。电工证年检步骤是什么,听起来简单,但实际操作中,很多人因为流程不清楚、资料准备不…

2026/11/17 0:49:41

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑