Relay 类型安全更新器Typesafe UpdatersFAQ 深度指南readUpdatableQuery 与 readUpdatableFragment 实战解析【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay类型安全更新器Typesafe Updaters是 Relay 提供的一组用于在 Relay Store 中以类型安全且更符合直觉的方式命令式更新本地数据的 API。本文以 Relay 18 官方 FAQ 文档为骨架结合 relay-runtime 中readUpdatableQuery、readUpdatableFragment、createUpdatableProxy等核心源码与配套的 Guided Tour 实战章节系统讲解其设计动机、工作方式、与旧版 updater API 的区别、以及完整的工程落地示例。读完本文你将能熟练运用updatable指令、updatable proxy 读写语义与assignable指令在 mutation updater、乐观更新和commitLocalUpdate中安全地修改标量字段与关联字段linked fields。什么是 Typesafe UpdatersTypesafe updaters 是一个项目代号指代一组用于命令式更新 Relay Store 中数据的、类型安全且更符合人体工学的 API作为既有 API 的替代方案。Store 暴露了两个典型的类型安全更新器readUpdatableFragment通过一个updatable fragment带updatable指令的 fragment读取指定记录上的字段readUpdatableQuery通过一个updatable query带updatable指令的 query从 Store 根节点开始读取字段。这两个 API 都定义在RecordSourceProxy接口上其完整签名可在 Store API 参考文档 的RecordSourceSelectorProxy、RecordSourceProxy小节中查看。为什么要引入它Relay 为服务端数据的获取与管理提供了类型安全且符合人体工学的 API也允许通过client schema extensions定义仅存在于客户端的本地字段。然而此前用于修改这些字段数据的 API 冗长且不直观导致Relay 无法被推荐为本地状态管理的解决方案——这正是 Typesafe Updaters 诞生的背景让 Relay 在管理本地状态包括客户端扩展字段时同样具备类型安全与良好体验。旧 API 的问题FAQ 明确指出旧有 API 存在两个核心缺陷冗长且不类型安全开发者很容易犯下各种错误仅在编写 updater 时才需要学习旧 API 暴露了一套与项目其他部分无关的方法集合例如RecordProxy上的getLinkedRecord、setLinkedRecord、getValue、setValue等见 Store 文档 中的RecordProxy接口这些方法只在 updater 场景中出现。Typesafe Updaters 则复用开发者已经熟悉的 Relay 惯用法——query、fragment、类型收窄type refinement——并通过 getter/setter 而非另学一套方法来完成读写。这样普通 React 组件的写法属性访问、赋值被直接迁移到 Store 更新场景中。开发者的使用方式整个工作流可以概括为三步编写一个 updatable query 或 fragment指明要命令式更新的数据从 Store 中读出该数据调用readUpdatableQuery/readUpdatableFragment得到一个所谓的updatable proxy变更该 proxy通过 setter 赋值例如updatableData.name Godzilla底层仍会调用旧 API但全程带类型检查。什么是 Updatable Query 或 Fragment一个 updatable query 或 fragment就是带有updatable指令的 query 或 fragment。例如fragment StoryLikeButton_updatable on Story updatable { likeCount doesViewerLike }query NameUpdaterUpdateQuery updatable { viewer { name } }需要特别注意的是updatable指令只是表达“这段查询/片段描述的是 Store 中可被命令式修改的数据形状”它并不参与网络请求详见下一节。编译产物层面的事实从源码结构看Relay 编译器为 updatable query 生成的运行时节点会被归为ConcreteUpdatableQuery一类。在 GraphQLTag.js 中getUpdatableQuery会先通过isUpdatableQuery校验传入的 tag 是否为 updatable query再取出其fragment.selections作为代理生成的依据见 readUpdatableQuery.js 与 readUpdatableFragment.js。这印证了 FAQ 的表述updatable query 的运行时节点侧重“selection 结构”而非“网络查询”。Updatable Queries 与 Fragments 不会被获取Not Fetched这是 FAQ 中最重要的语义澄清之一。字段永远不会从服务端拉取服务端根本不知道 updatable query/fragment 的存在其字段永远不会被获取。即使你将一个 updatable fragment 展开spread进一个普通 query 或 fragment 中该 updatable fragment 所选字段也不会作为该请求的一部分被获取。既想获取又想修改怎么办如果你既希望某个字段出现在 UI 数据中又希望在 updater 中修改它必须同时在普通 query/fragment 和 updatable query/fragment 中各选择一次该字段。普通 selection 负责从服务端取数updatable selection 负责描述 Store 中的可写形状。由此带来的一系列后果FAQ 总结了四点直接推论读取可能缺失因为字段不会从服务端获取当你读出 updatable data 时如果 Store 中不存在该数据结果可能为undefined/null代码中必须做空值判断不能在 updatable query/fragment 中展开普通 fragment普通 fragment 的 selection 依赖网络数据与“仅本地读取”的语义冲突编译产物精简updatable query/fragment 生成的 artifact不包含 query ID也不包含 normalization AST后者原本用于把网络数据写入 Store——因为根本没有网络数据要写禁用网络相关指令defer等指令在该上下文中没有意义因此被禁止使用。在 createUpdatableProxy.js 的updateProxyFromSelections中可以看到与之呼应的实现细节它只处理LinkedField、ScalarField、InlineFragment、ClientExtension等本地可读的 selection 种类而对Defer、Stream、ModuleImport、RelayResolver等节点直接抛出 “Encountered an unexpected ReaderSelection variant” 错误FragmentSpread则被显式忽略。这从实现层面佐证了 FAQ 的“后果”清单。从哪里获得storeFAQ 指出类RelayRecordSourceSelectorProxy、RecordSourceProxy和RelayRecordSourceProxy上都有readUpdatableQuery和readUpdatableFragment方法。你可以通过以下途径获取其实例mutation 和 subscription 的 updater 中updater回调的第一个参数mutation 的乐观 updateroptimistic updater中使用RelayModernEnvironment的commitUpdate、applyUpdate等方法时使用独立的commitLocalUpdate方法时。其中commitLocalUpdate在 commitLocalUpdate.js 中的实现极其简单——它只是对environment.commitUpdate(updater)的一层封装因此“在组件点击事件中触发本地更新”是最常见的用法。配套的 imperatively-modifying-store-data.md 给出了更完整的场景清单复杂客户端更新、初始化 client schema extensions 数据、失效invalidate节点、删除节点、查找某字段下所有 connection 等都只能在 updater 中完成。相反如果只是需要副作用应使用onCompleted回调——因为 updater 可能被多次调用而onCompleted保证只调用一次。底层原理Updatable Proxy 如何生成理解 updatable proxy 的行为关键是阅读 createUpdatableProxy.js。readUpdatableQuery/readUpdatableFragment最终都会调用createUpdatableProxyreadUpdatableQuery以proxy.getRoot()作为代理根记录配合调用方传入的 variables从updatableQuery.fragment.selections构建代理readUpdatableQuery.jsreadUpdatableFragment则先从 fragment reference 中取出__id通过proxy.get(id)定位到目标记录再以 fragment 的 selections 构建代理如果找不到该记录会抛出 invariantreadUpdatableFragment.js。注意plural fragment复数 fragment目前不支持。在代理构建过程中ScalarField通过Object.defineProperty定义 getter读取updatableProxyRootRecord.getValue(name, args)缺失时尝试missingFieldHandlers和 setter写入setValue__UNSAFE。但id、__id、__typename、js这些nonUpdatableKeys只提供 getter不提供 setter——这正是 FAQ 所说“类型安全 部分字段不可写”的落地体现LinkedField单值getter 返回嵌套的 updatable proxysetter 接受{__id, ...}对象通过recordSourceProxy.get(__id)找到目标记录后调用setLinkedRecord若 Store 中找不到该__id会抛错赋null则把关联字段置空LinkedField复数setter 要求传入数组且禁止赋null必须赋空数组数组元素不能为null/undefined每个元素都必须携带__id底层调用setLinkedRecordsInlineFragment当记录类型匹配时递归展开 selections这正是“类型收窄”在代理中的实现ClientExtension递归展开客户端扩展字段因此可以被正常读取与写入。此外在开发模式下__DEV__构建出的代理对象会被Object.freeze冻结防止运行时结构被意外篡改。实战一在 mutation updater 中更新标量字段下面的完整示例来自 imperatively-modifying-store-data.md。场景mutation 创建一个 Feedback 对象后将其 client schema extension 字段is_new_comment置为true。# Feedback.graphql extend type Feedback { is_new_comment: Boolean }// CreateFeedback.js import type {Environment} from react-relay; import type { FeedbackCreateData, CreateFeedbackMutation, CreateFeedbackMutation$data, } from CreateFeedbackMutation.graphql; const {commitMutation, graphql} require(react-relay); const {ConnectionHandler} require(relay-runtime); function commitCreateFeedbackMutation( environment: Environment, input: FeedbackCreateData, ) { return commitMutationFeedbackCreateData(environment, { mutation: graphql mutation CreateFeedbackMutation($input: FeedbackCreateData!) { feedback_create(input: $input) { feedback { id # Step 1: 在 mutation 响应中展开 updatable fragment ...CreateFeedback_updatable_feedback } } } , variables: {input}, updater: (store: RecordSourceSelectorProxy, response: ?CreateCommentMutation$data) { // Step 3: 取出并空值检查 feedback 对象 const feedbackRef response?.feedback_create?.feedback; if (feedbackRef null) { return; } // Step 3: 调用 store.readUpdatableFragment const {updatableData} store.readUpdatableFragment( graphql fragment CreateFeedback_updatable_feedback on Feedback updatable { is_new_comment } , feedbackRef ); // Step 6: 直接对 updatableData 赋值 updatableData.is_new_comment true; }, }); } module.exports {commit: commitCreateFeedbackMutation};关键要点updater 的第二参数是 mutation 响应读取结果类型为生成的$data类型的可空版本它只包含 mutation 直接选择的字段不含仅由 fragment 展开的字段——这正是为什么必须在 mutation 响应中显式 spread updatable fragment 才能拿到feedbackRefreadUpdatableFragment返回{updatableData}后续所有字段赋值都会在 updater 结束后统一写入 Store并触发受影响的组件重渲染。实战二在用户交互中更新本地数据同样来自 imperatively-modifying-store-data.md。在点击事件中切换is_selected字段// UserSelectToggle.react.js import type {RecordSourceSelectorProxy} from react-relay; import type {UserSelectToggle_viewer$key} from UserSelectToggle_viewer.graphql; const {useRelayEnvironment, commitLocalUpdate} require(react-relay); function UserSelectToggle({ userId, viewerRef }: { userId: string, viewerRef: UserSelectToggle_viewer$key, }) { const viewer useFragment(graphql fragment UserSelectToggle_viewer on Viewer { user(user_id: $user_id) { id name is_selected ...UserSelectToggle_updatable_user } } , viewerRef); const environment useRelayEnvironment(); return button onClick{() { commitLocalUpdate( environment, (store: RecordSourceSelectorProxy) { const userRef viewer.user; if (userRef null) { return; } const {updatableData} store.readUpdatableFragment( graphql fragment UserSelectToggle_updatable_user on User updatable { is_selected } , userRef ); updatableData.is_selected !viewer?.user?.is_selected; } ); }} {viewer?.user?.is_selected ? Deselect : Select} {viewer?.user?.name} /button }注意commitLocalUpdate的 updater没有第二参数因为不存在关联的网络响应文档同时提示这个例子也可以用environment.commitPayload改写但会失去类型安全。实战三用readUpdatableQuery替代 fragment当你没有现成的 fragment reference、或者想从Query根节点直达目标记录时可以用readUpdatableQuery。FAQ 与配套文档都强调它相比readUpdatableFragment的几个优势不需要 fragment reference例如commitLocalUpdate的调用与某个组件没有明显关联时不需要一个“选中父记录”的 fragment——由于 Relay 已知的类型洞updatable fragment 不能在最顶层top level被 spread可以使用变量目前 updatable fragment 复用传入 query 的 variables无法为 fragment 单独传入变量而readUpdatableQuery每次调用都可以传入不同的 variables。示例修改 viewer 的name// NameUpdater.react.js function NameUpdater({ queryRef }: { queryRef: NameUpdater_viewer$key }) { const environment useRelayEnvironment(); const data useFragment( graphql fragment NameUpdater_viewer on Viewer { name } , queryRef ); const [newName, setNewName] useState(data?.viewer?.name); const onSubmit () { commitLocalUpdate(environment, store { const {updatableData} store.readUpdatableQuery( graphql query NameUpdaterUpdateQuery updatable { viewer { name } } , {} ); const viewer updatableData.viewer; if (viewer ! null) { viewer.name newName; } }); }; }进阶更新关联字段Linked Fields与assignable指令标量字段赋值之外Relay 还支持对关联字段的赋值。完整讲解见 imperatively-modifying-linked-fields.md这里提炼其核心规则。基本模式assignable指令要让updatableData.viewer.best_friend data.user这样的赋值通过类型检查需要引入assignable fragment——带assignable指令、且只含__typename字段的 fragmentfragment AssignBestFriendButton_assignable_user on User assignable { __typename }该 fragment 必须同时展开在两处源位置新的 best friend 上和目的位置updatable query 中viewer.best_friend字段内。示例const environment useRelayEnvironment(); const onClick () { commitLocalUpdate(environment, (store: RecordSourceSelectorProxy) { const {updatableData} store.readUpdatableQuery( graphql query AssignBestFriendButtonUpdatableQuery updatable { viewer { best_friend { ...AssignableBestFriendButton_assignable_user } } } , {} ); if (data.user ! null updatableData.viewer ! null) { updatableData.viewer.best_friend data.user; } }); };文档特别提醒一个陷阱对 linked field 赋null会把 Store 中的关联字段置空大概率不是你想要的因此赋值前务必做空值检查。列表赋值规则FAQ 之外的关联文档补充了一条重要原则赋值右侧的每个 linked field 必须来源于只读的 fragment/query/mutation/subscription。因此updatableData.viewer.best_friends updatableData.viewer.best_friends.concat([newBestFriend])是非法的正确做法是从只读 fragment 中取出现有列表再拼接updatableData.viewer.best_friends [ ...viewer.best_friends, // 来自只读 fragment data.user, // 来自只读 fragment ];抽象类型与 Validator从抽象字段如Node赋给具体字段如实现了Node的User时需用 inline fragment 做类型收窄并配合__typename检查node(id: 4) { ... on User { __typename ...AssignableBestFriendButton_assignable_user } } // 赋值时 if (data.node ! null data.node.__typename User updatableData.viewer ! null) { updatableData.viewer.best_friend data.node; }当目标字段是接口类型如Actor而源类型不能保证实现该接口时就需要validator。原因在于编译器为抽象类型的 assignable fragment 生成的__isFoo_actor字段在“不能保证实现接口”的情况下是可选的__isFoo_actor?: string而 setter 要求非空的__isFoo_actor: string直接赋值无法通过类型检查。解决办法是从生成的 artifact 文件中导入具名validate导出import {validate as validateActor} from Foo_actor.graphql; if (updatableData.viewer ! null data.node ! null) { const validActor validateActor(data.node); if (validActor ! false) { updatableData.viewer.actor validActor; } }validate函数检查__isFoo_actor字段是否存在存在则返回带正确 Flow 类型的同一对象否则返回false。文档也明确指出单纯在代码中检查__isFoo_actor的存在无法让 Flow 推断出“字段非可选”所以 validator 是当前必需的机制。何时该用、何时不该用 updater结合 FAQ 与配套文档可以归纳出清晰的使用边界场景建议复杂客户端更新无法用声明式 mutation 指令覆盖使用 updater初始化 client schema extensions 中的数据使用 updater失效/删除节点、查找 connection 等旧 API 专属能力使用 updater触发其他副作用使用onCompleted回调保证只调用一次updater 可能被反复调用多个乐观响应同时修改同一 Store 值注意回滚不重算第一个乐观响应回滚后第二个的修改仍保留且不会重新计算总结Typesafe Updaters 的核心价值在于把“类型安全 熟悉语法”带入 Relay 的命令式 Store 更新。通过updatable指令描述可写数据形状通过readUpdatableQuery/readUpdatableFragment读出 updatable proxy再用普通赋值完成写入底层由 createUpdatableProxy.js 的 getter/setter 机制安全地翻译为旧 API 调用。理解“updatable 数据不会被服务端获取”“必须在普通 selection 中重复选择需要展示的字段”“linked field 赋值依赖assignable与 validator”这三条规则就能在实际项目中放心地将 Relay 用于本地状态管理。如需继续深入推荐阅读Store API 参考含RecordSourceSelectorProxy/RecordSourceProxy/ConnectionHandler命令式修改 Store 数据标量字段命令式修改关联字段linked fields 与assignable运行时实现readUpdatableQuery.js、readUpdatableFragment.js、createUpdatableProxy.js、commitLocalUpdate.js【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考