Relay Store 完全指南：深入解析 RecordSourceSelectorProxy、RecordProxy 与 ConnectionHandler

前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载Relay Store 是 Relay 运行时relay-runtime中维护规范化客户端数据的核心存储本文围绕官方 API 参考文档系统讲解如何在updater函数 中通过编程方式更新客户端数据所需的全部 Store 接口RecordSourceSelectorProxy、RecordProxy、RecordSourceProxy与ConnectionHandler。读完本文你将掌握每个方法的签名、语义、典型用法与底层实现原理能够独立编写 mutation updater、乐观更新与连接Connection增删改等实战代码。一、Relay Store 与 updater 函数在 Relay 中来自服务端的数据会被规范化为一个以dataID为键的记录record集合存入 Store。多数场景下mutation 响应会被自动写入 Store但当更新逻辑超出把网络响应写进 Store这一简单行为时就需要通过 updater 函数进行命令式修改。RecordSourceSelectorProxy正是updater函数 接收的store参数的类型。从源码看这些接口的 Flow 类型定义集中在 RelayStoreTypes.js而具体实现分别位于RelayRecordSourceSelectorProxy.jsRecordSourceSelectorProxy的实现是RecordSourceProxy的子类额外提供访问当前操作根字段的便捷方法RelayRecordProxy.jsRecordProxy的实现提供命令式读写单条记录的 OO 风格 APIRelayRecordSourceProxy.jsRecordSourceProxy的实现负责整个 record source 级别的操作。三个 Proxy 都建立在RelayRecordSourceMutator之上构造时传入__mutatorProxy 本身只是对底层变更集的一层包装——所有修改最终都会累积为变更集在 updater 完成后统一发布到 Store。二、RecordSourceSelectorProxyupdater 收到的 store 参数RecordSourceSelectorProxy是 updater 函数第一个参数的类型接口定义如下interface RecordSourceSelectorProxy { create(dataID: string, typeName: string): RecordProxy; delete(dataID: string): void; get(dataID: string): ?RecordProxy; getRoot(): RecordProxy; getRootField(fieldName: string): ?RecordProxy; getPluralRootField(fieldName: string): ?Array?RecordProxy; invalidateStore(): void; }在 RelayRecordSourceSelectorProxy.js 的构造器中可以看到它额外持有_readSelector当前操作对应的选择器与_missingFieldHandlers这使其能够基于当前 mutation/query 的选择集定位根字段。2.1create(dataID: string, typeName: string): RecordProxy在 Store 中新建一条记录dataID由调用方指定typeName必须是 GraphQL schema 中定义的类型名。返回的RecordProxy可用于继续修改新记录。const record store.create(dataID, Todo);底层实现RelayRecordSourceProxy.js先调用mutator.create(dataID, typeName)然后通过get()返回包装后的RelayRecordProxy。注意它会清除该 dataID 的代理缓存确保返回的是新记录。2.2delete(dataID: string): void按dataID从 Store 中删除一条记录。源码中 RelayRecordSourceProxy.js 对此有一个重要保护不能删除根记录ROOT_ID否则会抛出 invariant 错误。此外删除后对于指向该记录的既有边edge默认情况下即使该字段类型声明为非空读取到的值也会是undefined只有当字段带有throwOnFieldError指令时缺失数据才会抛错。store.delete(dataID);2.3get(dataID: string): ?RecordProxy按dataID取回记录返回RecordProxy用于读写。若记录不存在则返回null。底层实现RelayRecordSourceProxy.js会依据 mutator 的记录状态EXISTENT/NONEXISTENT决定返回代理还是null并用_proxies缓存以避免重复包装。const record store.get(dataID);2.4getRoot(): RecordProxy返回代表 GraphQL 文档根的RecordProxy也就是 ROOT 记录。例如给定文档viewer { id }可以这样访问根下的记录// Represents root query const root store.getRoot(); // Get the viewer linked record const viewer root.getLinkedRecord(viewer);实现上RelayRecordSourceProxy.js会确保根记录存在——若不存在则自动以ROOT_TYPE创建并校验其类型确实是根类型。2.5getRootField(fieldName: string): ?RecordProxy按字段名取回当前操作mutation/query的根字段即把当前操作选择集中的某个顶层字段解析为记录。其实现RelayRecordSourceSelectorProxy.js通过_getRootField()在当前选择器的selections中查找同名LinkedField同时支持RequiredField包装再结合当前变量计算存储键getStorageKey最后从操作根记录上取链接记录。viewer { id }const viewer store.getRootField(viewer);若选择集中不存在该字段或字段的plural属性与方法不匹配会抛出带字段名与文档名的 invariant 错误RelayRecordSourceSelectorProxy.js这有助于及早发现 updater 与文档选择集不匹配的问题。2.6getPluralRootField(fieldName: string): ?Array?RecordProxy与getRootField类似但用于取回表示集合plural 字段的根字段返回RecordProxy数组。nodes(first: 10) { # ... }const nodes store.getPluralRootField(nodes);实现RelayRecordSourceSelectorProxy.js要求目标字段必须声明为 plural否则会抛出 invariant 错误。2.7invalidateStore(): void全局失效整个 Relay Store。失效前写入 Store 的所有数据都会被标记为过期stale下一次用environment.check()检查查询时会被判定为需要重新拉取store.invalidateStore();environment.check(query) stale从实现看RelayRecordSourceProxy.js该方法只是把_invalidatedStore置为true真正生效的链路在发布队列 RelayPublishQueue.js 中——_publishSourceFromPayload()在发布 source 时读取isStoreMarkedForInvalidation()将其作为全局失效标记传递给store.publish()并最终在notify()阶段触发对 stale 数据的重新订阅通知。三、RecordProxy单条记录的读写接口RecordProxy是对 Store 中单条记录的 OO 风格包装接口如下interface RecordProxy { copyFieldsFrom(sourceRecord: RecordProxy): void; getDataID(): string; getLinkedRecord(name: string, arguments?: ?Object): ?RecordProxy; getLinkedRecords(name: string, arguments?: ?Object): ?Array?RecordProxy; getOrCreateLinkedRecord( name: string, typeName: string, arguments?: ?Object, ): RecordProxy; getType(): string; getValue(name: string, arguments?: ?Object): mixed; setLinkedRecord( record: RecordProxy, name: string, arguments?: ?Object, ): RecordProxy; setLinkedRecords( records: Array?RecordProxy, name: string, arguments?: ?Object, ): RecordProxy; setValue(value: mixed, name: string, arguments?: ?Object): RecordProxy; invalidateRecord(): void; }3.1getDataID(): string返回当前记录的dataID。const id record.getDataID();实现RelayRecordProxy.js直接返回构造时持有的_dataID。3.2getType(): string返回当前记录在 GraphQL schema 中定义的类型名。若记录已被删除则抛错RelayRecordProxy.jsconst type user.getType(); // User3.3getValue(name: string, arguments?: ?Object): mixed读取当前记录上某个标量字段的值。字段名与可选参数包都会参与计算稳定存储键viewer { id name }const name viewer.getValue(name);当字段带参数时需要传入与查询中一致的变量包viewer { id name(arg: $arg) }const name viewer.getValue(name, {arg: value});实现RelayRecordProxy.js通过getStableStorageKey(name, args)生成存储键后从 mutator 取值。3.4getLinkedRecord(name: string, arguments?: ?Object): ?RecordProxy取回与当前记录关联的单条链接记录。参数包同样可选rootField { viewer { id name } }const rootField store.getRootField(rootField); const viewer rootField.getLinkedRecord(viewer);带参数的版本rootField { viewer(arg: $arg) { id } }const rootField store.getRootField(rootField); const viewer rootField.getLinkedRecord(viewer, {arg: value});实现RelayRecordProxy.js先从 mutator 取链接记录 ID再通过_source.get(linkedID)解析为RecordProxy。3.5getLinkedRecords(name: string, arguments?: ?Object): ?Array?RecordProxy取回与当前记录关联的一组链接记录rootField { nodes { # ... } }const rootField store.getRootField(rootField); const nodes rootField.getLinkedRecords(nodes);带参数版本rootField { nodes(first: $count) { # ... } }const rootField store.getRootField(rootField); const nodes rootField.getLinkedRecords(nodes, {count: 10});实现RelayRecordProxy.js会把 ID 列表逐一映射为RecordProxynull元素原样保留对应缺失的链接。3.6getOrCreateLinkedRecord(name: string, typeName: string, arguments?: ?Object): RecordProxy取回链接记录若不存在则按typeName创建一条新的客户端记录并建立链接。这一能力在需要确保目标记录一定存在的场景如初始化 client schema extension 字段中非常实用rootField { viewer { id } }const rootField store.getRootField(rootField); const newViewer rootField.getOrCreateLinkedRecord(viewer, User); // Will create if it doesnt exist实现RelayRecordProxy.js先尝试getLinkedRecord若不存在则用generateClientID(当前记录ID, storageKey)生成稳定的客户端 ID先检查该 ID 是否已有客户端记录避免覆盖创建后通过setLinkedRecord建立关联。3.7setValue(value: mixed, name: string, arguments?: ?Object): RecordProxy设置当前记录某标量字段的值返回记录本身可链式调用viewer { id name }viewer.setValue(New Name, name);带参数版本viewer.setValue(New Name, name, {arg: value});实现上RelayRecordProxy.js有一个重要校验isValidLeafValue只允许标量、null或标量数组若传入对象等复杂结构会抛出 invariant 错误。这正是文档提醒RecordSourceProxy 底层 API 不具备类型安全的一个体现。3.8copyFieldsFrom(sourceRecord: RecordProxy): void把传入记录的字段整体复制到当前记录上用于把一个记录的数据迁移到另一个记录的场景const record store.get(id1); const otherRecord store.get(id2); record.copyFieldsFrom(otherRecord); // Mutates record实现RelayRecordProxy.js委托给mutator.copyFields(sourceRecord.getDataID(), this._dataID)。3.9setLinkedRecord(record: RecordProxy, name: string, arguments?: ?Object): RecordProxy在当前记录上建立一条链接记录rootField { viewer { id } }const rootField store.getRootField(rootField); const newViewer store.create(/* ... */); rootField.setLinkedRecord(newViewer, viewer);实现RelayRecordProxy.js要求传入的记录必须是RelayRecordProxy实例否则抛错取record.getDataID()后写入 mutator。3.10setLinkedRecords(records: ArrayRecordProxy, name: string, variables?: ?Object): RecordProxy在当前记录上设置一组链接记录常用于整组替换如重新排序后的 edgesrootField { nodes { # ... } }const rootField store.getRootField(rootField); const newNode store.create(/* ... */); const newNodes [...rootField.getLinkedRecords(nodes), newNode]; rootField.setLinkedRecords(newNodes, nodes);实现RelayRecordProxy.js要求传入真实数组并把每个元素映射为dataID写入 mutator。3.11invalidateRecord(): void使当前记录失效。任何引用了该记录的查询都会被标记为 stale直到下次重新拉取const record store.get(4); record.invalidateRecord();environment.check(query) stale实现RelayRecordProxy.js调用_source.markIDForInvalidation(this._dataID)最终同样通过发布队列收集getIDsMarkedForInvalidation()并随store.publish()一起生效RelayPublishQueue.js。与invalidateStore()的全局失效相比invalidateRecord()只影响引用了该特定记录的查询粒度更细。四、RecordSourceProxy更底层的 Store 修改接口RecordSourceProxy是RecordSourceSelectorProxy的父接口负责整个 record source 级别的修改interface RecordSourceProxy { create(dataID: DataID, typeName: string): RecordProxy; delete(dataID: DataID): void; get(dataID: DataID): ?RecordProxy; getRoot(): RecordProxy; invalidateStore(): void; readUpdatableFragmentTFragmentType: FragmentType, TData( fragment: UpdatableFragmentTFragmentType, TData, fragmentReference: HasUpdatableSpreadTFragmentType, ): UpdatableDataTData; readUpdatableQueryTVariables: Variables, TData( query: UpdatableQueryTVariables, TData, variables: TVariables, ): UpdatableDataTData; }其中create、delete、get、getRoot、invalidateStore与第二节中RecordSourceSelectorProxy对应方法语义一致前者在 RelayRecordSourceProxy.js 实现后者直接委托给前者的实现。:::dangerRecordSourceProxy暴露了大量底层、不具备类型安全的 API。如果你的场景可以被以下替代方案覆盖官方建议优先考虑它们typesafe updaters乐观更新optimistic updatesrelay resolvers。 :::4.1readUpdatableFragment(...)命令式读取可更新 fragment从 Store 中读取一个可更新 fragment以updatable指令声明返回的updatableData上的字段可以被直接赋值从而命令式地修改 Store 数据const fragment graphql fragment StoryLikeButton_updatable on Story updatable { likeCount doesViewerLike } ; const { updatableData } store.readUpdatableFragment( fragment, story ); updatableData.likeCount updatableData.likeCount 1这里story是HasUpdatableSpread类型的 fragment reference。实现位于 RelayRecordSourceSelectorProxy.js委托给readUpdatableFragment模块并传入_missingFieldHandlers。关于命令式修改 Store 的完整流程fragment 中先 spread 可更新 fragment再在 updater 中调用readUpdatableFragment最后对updatableData赋值updater 结束后变更集统一写入 Store 并触发重渲染可参考 guided tour 的命令式修改 Store 数据章节。4.2readUpdatableQuery(...)命令式读取可更新 query与readUpdatableFragment类似但读取的是可更新查询且不需要传入 fragment referenceconst {updatableData} store.readUpdatableQuery( graphql query NameUpdaterUpdateQuery updatable { viewer { name } } , {} ); const viewer updatableData.viewer; viewer.name newName;实现位于 RelayRecordSourceSelectorProxy.js同样委托给readUpdatableQuery模块。五、ConnectionHandler连接Connection操作工具ConnectionHandler是relay-runtime导出的工具模块专门用于操作连接型数据其接口如下interface ConnectionHandler { getConnection( record: RecordProxy, key: string, filters?: ?Object, ): ?RecordProxy, createEdge( store: RecordSourceProxy, connection: RecordProxy, node: RecordProxy, edgeType: string, ): RecordProxy, insertEdgeBefore( connection: RecordProxy, newEdge: RecordProxy, cursor?: ?string, ): void, insertEdgeAfter( connection: RecordProxy, newEdge: RecordProxy, cursor?: ?string, ): void, deleteNode(connection: RecordProxy, nodeID: string): void }实现位于 ConnectionHandler.js配套测试见 ConnectionHandler-test.js其中覆盖了insertEdgeAfter、insertEdgeBefore、deleteNode以及 cursor 匹配含cursor 不存在时的兜底行为等关键路径。5.1getConnection(record, key, filters)定位 connection 字段给定父记录、连接 key 以及可选 filters取回被connection指令标注的连接记录。先看普通连接字段——它和普通字段一样直接访问即可fragment FriendsFragment on User { friends(first: 10) { edges { node { id } } } }// The friends connection record can be accessed with: const user store.get(userID); const friends user user.getLinkedRecord(friends); // Access fields on the connection: const edges friends friends.getLinkedRecords(edges);但使用usePaginationFragment时我们通常会用connection标注需要分页的字段fragment FriendsFragment on User { friends(first: 10, orderby: firstname) connection( key: FriendsFragment_friends, ) { edges { node { id } } } }此时连接记录存放在以 handle key 命名的字段下ConnectionHandler帮助我们定位它import {ConnectionHandler} from relay-runtime; // The friends connection record can be accessed with: const user store.get(userID); const friends ConnectionHandler.getConnection( user, // parent record FriendsFragment_friends, // connection key {orderby: firstname} // filters that is used to identify the connection ); // Access fields on the connection: const edges friends.getLinkedRecords(edges);从源码看ConnectionHandler.jsgetConnection内部先通过getRelayHandleKey(connection, key, null)构造 handle key再执行record.getLinkedRecord(handleKey, filters)。注意filters 是区分同一 key 下不同连接实例的关键当同一个connection(key: ...)字段以不同参数被多次查询时filters 参与了存储键的计算从而定位到正确的那条连接。5.2 边edge的创建与插入三个方法配合使用即可完成往连接里加一条记录的完整流程createEdge(store, connection, node, edgeType)创建一条边。实现ConnectionHandler.js以generateClientID(连接ID, 节点ID)生成稳定边 ID同一节点加到同一连接两次才会冲突而 insertEdge 函数会忽略重复并确保cursor字段显式为null避免undefined被当作缺失数据。insertEdgeBefore(connection, newEdge, cursor?)把边插到连接开头若提供cursor则插到该 cursor 对应的边之前找不到 cursor 时保持不变。insertEdgeAfter(connection, newEdge, cursor?)把边追加到连接末尾若提供cursor则插到该 cursor 对应的边之后。const user store.get(userID); const friends ConnectionHandler.getConnection(user, FriendsFragment_friends); const newFriend store.get(newFriendId); const edge ConnectionHandler.createEdge(store, friends, newFriend, UserEdge); // No cursor provided, append the edge at the end. ConnectionHandler.insertEdgeAfter(friends, edge); // No cursor provided, insert the edge at the front: ConnectionHandler.insertEdgeBefore(friends, edge);insertEdgeAfter与insertEdgeBefore的实现ConnectionHandler.js、ConnectionHandler.js都会处理当前没有 edges的边界情况直接setLinkedRecords([newEdge])并在有 cursor 时遍历比对edge.getValue(CURSOR)来决定插入位置。5.3deleteNode(connection, nodeID)按节点删除边删除连接中所有node.id与给定 ID 匹配的边const user store.get(userID); const friends ConnectionHandler.getConnection(user, FriendsFragment_friends); ConnectionHandler.deleteNode(friends, idToDelete);实现ConnectionHandler.js遍历 edges过滤出node.getDataID() nodeID的边并重写edges字段若连接没有 edges 则直接返回。六、综合实战一个完整的 mutation updater将以上接口组合起来一个典型的 mutation updater 可以完成创建记录 → 更新标量 → 维护连接三类操作。下面的示例把新 Todo 插入连接、并同步更新计数import {ConnectionHandler} from relay-runtime; function commitAddTodo(environment, input) { return commitMutation(environment, { mutation: graphql mutation AddTodoMutation($input: AddTodoInput!) { todo_add(input: $input) { todoEdge { node { id text } } viewer { id totalCount } } } , variables: {input}, updater: (store) { // 1. 从操作根字段拿到响应里的 edge 数据 const todoEdge store.getRootField(todo_add).getLinkedRecord(todoEdge); const node todoEdge.getLinkedRecord(node); // 2. 更新 viewer 的 totalCount const viewer store.getRootField(todo_add).getLinkedRecord(viewer); const count viewer.getValue(totalCount); viewer.setValue(count 1, totalCount); // 3. 维护连接把新 edge 追加到连接末尾 const userRecord store.get(userID); const connection ConnectionHandler.getConnection( userRecord, TodoListFragment_todos, ); const edge ConnectionHandler.createEdge( store, connection, node, TodoEdge, ); ConnectionHandler.insertEdgeAfter(connection, edge); }, }); }这里的每一步都可以在上文对应小节找到依据getRootField用于取根字段第二节setValue/getValue用于标量读写第三节ConnectionHandler.getConnection/createEdge/insertEdgeAfter用于连接维护第五节。七、最佳实践与注意事项优先使用更高级的替代方案RecordSourceProxy的底层 API 不具备类型安全。若场景可被 typesafe updaters、乐观更新 或 relay resolvers 覆盖优先使用它们。不要删除根记录store.delete()对ROOT_ID有硬性保护删除根记录会抛错。setValue 只接受叶子值setValue只允许标量、null或标量数组传入对象会抛 invariant 错误链接关系请使用setLinkedRecord/setLinkedRecords。失效invalidation的粒度选择invalidateStore()全局失效适合数据整体可能过期的场景invalidateRecord()只影响引用该记录的查询粒度更细。两者都会让environment.check(query)返回stale并与 fetch policies如store-or-network协同触发重新拉取。getRootField 必须与文档选择集匹配若字段名不存在于当前操作的选择集中或 plural 属性不匹配会抛出带文档名的 invariant 错误因此 updater 中使用的字段名应始终与 mutation/query 中的选择保持一致。连接查找记得传 filters同一connection(key)字段被不同参数查询时会生成多个连接实例getConnection的 filters 用于精确定位缺省可能导致拿到错误的连接。updater 可能被多次执行不要用 updater 触发副作用副作用应放在onCompleted回调中两个乐观更新同时修改同一值时前一个回滚不会导致后一个重新计算。八、参考链接本 API 参考文档原始来源guided tourGraphQL mutationsupdater 与乐观更新guided tour命令式修改 Store 数据readUpdatableFragment / readUpdatableQueryguided tourtypesafe updaters FAQguided tourfetch policiesthrowOnFieldError 指令说明usePaginationFragment API相关实现源码RelayRecordSourceSelectorProxy.js、RelayRecordProxy.js、RelayRecordSourceProxy.js、ConnectionHandler.js、RelayStoreTypes.js、RelayPublishQueue.js赞分享前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载相关推荐Relay 13 Store API 完全指南RecordSourceSelectorProxy、RecordProxy 与 ConnectionHandler 实战解析Relay 13 Store API 完全指南RecordSourceSelectorProxy、RecordProxy 与 ConnectionHandle前端开发工具Relay Store 编程接口完全指南RecordSourceSelectorProxy、RecordProxy 与 ConnectionHandler 实战参考Relay Store 编程接口完全指南RecordSourceSelectorProxy、RecordProxy 与 ConnectionHandler 实前端开发工具Relay Store API 完全指南用 RecordSourceSelectorProxy、RecordProxy 与 ConnectionHandler 编程式更新客户端数据Relay Store API 完全指南用 RecordSourceSelectorProxy、RecordProxy 与 ConnectionHandler前端开发工具上一篇5分钟搭建企业级即时通讯FreeIM .NET Core实战指南下一篇如何使用MP4Parser构建企业级视频处理系统Java开发者的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考