前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载Relay 允许开发者通过 Client Schema Extensions客户端 Schema 扩展在浏览器端扩展 GraphQL Schema从而建模只在客户端创建、读取和更新的数据。本文将基于 Relay v19 官方文档client-only-data.md并结合仓库源码完整讲解如何扩展已有类型、新增纯客户端类型、通过 Fragment/Query 读取以及使用 mutation/subscription updater 与本地更新原语写入这些数据帮助你构建更健壮、更灵活的数据驱动 React 应用。什么是 Client-Only Data在典型的 Relay 应用中所有数据都来自服务器端的 GraphQL 响应并通过操作Operation规范化写入 Relay Store。但在真实业务中总有一些数据不需要、也不应该经过服务器——例如为服务器返回的数据补充少量本地信息如这条评论是否是新发布的完全在客户端维护的 UI 状态如某个条目的加载状态、展开/折叠状态、草稿内容表单填写过程中的中间态、尚未提交的用户输入。Relay 为此提供了Client Schema Extensions客户端 Schema 扩展机制你可以在浏览器端也就是客户端扩展 GraphQL Schema去建模这些只在客户端创建、读取和更新的数据。它的两种核心能力分别是修改已有类型为服务器 Schema 中已存在的类型如Comment、User添加新字段创建全新类型定义只存在于客户端的全新类型如FetchStatus枚举、FetchState类型甚至用它们组合出更复杂的客户端数据模型。从 client-only-data.md 的定位可以看出该能力是 Relay 更新数据updating-data主题下的核心章节之一与 mutation、subscription、本地数据更新local data updates紧密配合。扩展已有类型给服务器类型加字段在 Relay 编译器的--src目录中新建任意一个.graphql文件通常放在项目的 schema 扩展目录中并使用标准 GraphQL 的extend关键字来扩展已有类型extend type Comment { is_new_comment: Boolean }在这个示例中使用extend关键字在已有的Comment类型上新增了一个字段is_new_comment: Boolean添加后你可以在组件中像读取普通字段一样读取它并在需要时通过普通的 Relay API 进行更新一个典型场景是用该字段标记这条评论是否是新创建的从而在评论列表中为它渲染不同的视觉样式当用户创建新评论时再将其置为true。编译器如何处理客户端扩展字段从源码结构看Relay 编译器在compiler/crates/relay-transforms/src/client_extensions.rs中实现了ClientExtensionsTransform其 NAME 为ClientExtensionsTransform该 Transform 会在apply_transforms.rs的转换管线中client_extensions(program)执行并为扩展字段生成带build_client_extension_directive()指令的 AST 节点。也就是说这些客户端字段最终会在编译产物中被标记为ClientExtension 节点运行时据此知道它们无需向服务器请求。值得注意的是Relay 编译器还通过 validate.rs调用validate_client_schema_extensions_use_catch对客户端 Schema 扩展的使用做合法性校验确保扩展用法符合规范。新增纯客户端类型定义自己的数据模型除了扩展已有类型你还可以在.graphql文件中定义全新的客户端类型。原文档中给出的示例位于html/js/relay/schema/目录实际项目中该路径由编译器的 schema/source 配置决定下面会详述同一个文件里可以定义多个类型# You can define more than one type in a single file enum FetchStatus { FETCHED PENDING ERRORED } type FetchState { # You can reuse client types to define other types status: FetchStatus # You can also reference regular server types started_by: User! } extend type Item { # You can extend server types with client-only types fetch_state: FetchState }这个示例展示了 Client Schema Extensions 的几个关键特性在一个.graphql文件中可以定义多个类型这里同时定义了枚举FetchStatus和对象类型FetchState客户端类型之间可以互相引用FetchState引用了同为客户端类型的FetchStatus客户端类型可以引用服务器上已有的普通类型started_by: User!引用了服务器端的User你可以用客户端类型扩展服务器类型extend type Item中的fetch_state: FetchState字段就是一个纯客户端字段定义完成后这些数据同样可以通过普通 Relay API 进行读取和更新。仓库中的真实客户端扩展示例仓库的测试基础设施packages/relay-test-utils-internal/schema-extensions/目录下存放着大量真实的客户端 Schema 扩展文件可以当作最佳实践参考。例如ClientAccount.graphql 展示了最简的纯客户端类型定义type ClientAccount { id: ID }ClientInterface.graphql 展示了客户端接口interface以及用客户端类型实现接口的能力同时还演示了extend type Query { client_interface: ClientInterface }这种在根类型上挂客户端字段的写法interface ClientInterface { description: String } type ClientTypeImplementingClientInterface implements ClientInterface { description: String } extend type Query { client_interface: ClientInterface }Todos.graphql 则演示了用客户端类型完整建模一个 Todo 列表Todo、TodoEdge、TodoConnection、TodoConnectionPageInfo以及带枚举的TodoText/TodoTextStyle/TodoTextColor说明客户端扩展完全可以承载复杂的业务状态模型。这些示例证明客户端 Schema 扩展的语法和服务器端 GraphQL 类型定义语法一致支持type、enum、interface、extend等结构可以灵活组合。编译配置如何让编译器识别客户端扩展要使用客户端扩展需要确保编译器配置正确加载这些.graphql文件。Relay 编译器的配置以 relay.config.json 及 compiler/crates/relay-config 中的 schema 加载逻辑为准中schema可以指向.graphql文件或 JSON 文件。客户端扩展通常与服务器 Schema 一同被编译Relay 会解析这些定义将extend的字段并入目标类型将新类型注册为客户端类型。请确认你的编译器--src或source目录配置覆盖了存放扩展文件的路径以保证构建时能发现它们。读取 Client-Only Data客户端字段可以像普通字段一样在 fragment 或 query 中直接选中。以文档中的useFragment为例const data useFragment( graphql fragment CommentComponent_comment on Comment { # We can select client-only fields as we would any other field is_new_comment body { text } } , props.user, );要点is_new_comment是扩展在Comment上的客户端字段写法与普通字段完全一致Relay 编译器会在构建时识别该字段来自客户端扩展并在生成的代码__generated__目录下的.graphql.js文件中将其标记为客户端字段运行时不会向服务器发起该字段的请求读取行为与普通字段一致当该字段的数据被更新时订阅了对应 fragment 的组件会自动重新渲染。更新 Client-Only Data更新客户端数据主要有两类途径在 mutation 或 subscription 的 updater 中更新在服务器操作完成后利用 updater 顺手写入客户端字段使用本地更新原语不依赖任何服务器操作纯粹在客户端对 Relay Store 进行修改例如 commitLocalUpdate 与commitPayload。原文档明确指出你可以在 mutation 或 subscription 的 updater 中常规地更新客户端数据也可以使用 local-data-updates 中的原语做本地更新。commitLocalUpdate纯本地写入commitLocalUpdate是进行纯本地更新的核心 API它不涉及任何网络请求。从源码 commitLocalUpdate.js 可以看到它的实现非常轻量本质上是将 updater 交给环境执行function commitLocalUpdate( environment: IEnvironment, updater: StoreUpdater, ): void { environment.commitUpdate(updater); }使用方式参考 local-data-updates.mdconst {commitLocalUpdate, graphql} require(react-relay); function commitCommentCreateLocally( environment: Environment, feedbackID: string, ) { return commitLocalUpdate(environment, store { // Imperatively mutate the store here // e.g. store.get(comment-id)?.setValue(true, is_new_comment) }); }使用commitLocalUpdate时有几点需要注意它接收两个参数environment与 updater 函数updater 接收的store参数是RecordSourceSelectorProxy的实例允许你命令式地读写 Relay Store——可以创建全新 record、更新或删除已有 record完全掌控更新方式与 mutation/subscription 的 updater 不同commitLocalUpdate的 updater没有第二个参数如response因为这里根本没有网络响应任何本地数据更新都会自动通知订阅了该数据的组件触发重新渲染。在 mutation updater 中同步更新客户端字段结合原文档的设想在创建新评论时把is_new_comment置为true典型做法是在创建评论的 mutation updater 中写入客户端字段function commitCommentCreate( environment: Environment, input: {feedbackID: string, text: string}, ) { return commitMutation(environment, { mutation: graphql mutation CommentCreateMutation($input: CommentCreateInput!) { commentCreate(input: $input) { comment { id body { text } } } } , variables: {input}, updater: store { // 通过 root field 拿到新建评论的 record const root store.getRoot(); const comment root.getLinkedRecord(commentCreate, {input})?.getLinkedRecord(comment); // 写入客户端字段标记这条评论是新的 comment?.setValue(true, is_new_comment); }, }); }这里的核心思想是客户端字段与服务器字段存储在同一个 Relay Store record 中updater 中通过RecordSourceSelectorProxy拿到对应 record 后用setValue(value, fieldName)即可写入客户端字段从而让使用该字段的 fragment 自动获得更新。设计建议与边界结合 client-only-data.md 和仓库中的实际用例使用客户端 Schema 扩展时有几个实用建议小颗粒信息优先用extend只需为服务器数据补充少量本地状态时优先扩展已有类型如is_new_comment: Boolean成本最低、与服务器数据天然关联复杂状态模型用新类型需要建模独立于服务器数据的完整状态机如拉取状态、Todo 列表、接口多态时定义新的客户端类型更清晰且类型之间可以自由组合引用配合 updater 原子化更新客户端字段可以在 mutation/subscription 的 updater 中与服务器数据一起写入保证组件状态一致无需额外触发请求纯本地变更走 commitLocalUpdate不依赖服务器操作的状态变更如折叠/展开、草稿保存直接使用本地更新原语更新会自动广播给订阅组件。总结Client Schema Extensions 是 Relay 在客户端建模本地数据的官方机制通过extend关键字扩展服务器类型、通过标准 GraphQL 语法定义全新客户端类型然后就能在 fragment/query 中正常读取并在 mutation/subscription updater 或commitLocalUpdate等本地更新原语中写入。结合仓库源码可以看到这一能力从编译器client_extensions.rs的ClientExtensionsTransform、validate.rs的校验到运行时commitLocalUpdate委托environment.commitUpdate形成了完整的链路让纯客户端状态与服务器数据在同一个 Relay Store 中和谐共存。进一步阅读Relay 更新数据指南总览本地数据更新commitLocalUpdate / commitPayloadGraphQL MutationsGraphQL SubscriptionsFragments 渲染Queries 渲染测试扩展样例packages/relay-test-utils-internal/schema-extensions赞分享前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载相关推荐Relay Client-Only Data 完全指南用 Client Schema Extensions 在浏览器端扩展 GraphQL 数据模型Relay Client Only Data 完全指南用 Client Schema Extensions 在浏览器端扩展 GraphQL 数据模型 Rela前端开发工具Relay Client-Only DataClient Schema Extensions完全指南在浏览器端扩展 GraphQL Schema 与本地数据建模Relay Client Only DataClient Schema Extensions完全指南在浏览器端扩展 GraphQL Schema 与本地数前端开发工具Relay Client-Only Data 实战使用 Client Schema Extensions 在浏览器端建模与更新本地状态Relay Client Only Data 实战使用 Client Schema Extensions 在浏览器端建模与更新本地状态 导读 Relay 的核前端开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考