前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载本篇技术指南以 Relay 的工作流Workflow概念为核心系统讲解如何在编写 Relay 组件如 Fragment、Query时通过Relay Compiler将 JavaScript 代码中的graphql模板字面量预先编译Ahead-of-Time, AOT为运行时所需的生成产物artifacts。读完本文你将掌握 Relay 项目的完整编译工作流从安装与配置 Relay Compiler、编写relay.config配置文件到执行一次性编译、开启 watch 监听模式再到理解__generated__产物的结构与导入方式并了解当前仓库中 Rust 实现 CLI 的底层参数与行为。工作流概述为什么 Relay 开发离不开 CompilerRelay 的核心设计之一是将 GraphQL 文档的解析与查询构建工作前移到构建期。在开始编写任何 Relay 代码之前首先要完成Relay Compiler 的安装与设置。Relay Compiler 会扫描你 JavaScript 代码中的每一个graphql字面量对其进行分析并生成一组运行时制品artifacts。这些制品在浏览器中运行时被 Relay 使用它们帮助 Relay 读写 Store数据仓库、进行响应归一化、生成用于类型检查的类型声明等。关键在于graphql模板标签永远不会在运行时被执行。它只是给编译器看的编译输入编译器将其转换为可被require()/import的生成文件。这一机制详见 Relay Compiler 指南。因此当你开发 Relay 组件——例如编写 Fragment 或 Query——之后都必须重新运行 Relay Compiler让产物与最新代码保持同步。这是 Relay 日常开发中最重要的循环改代码 → 跑编译器 → 在运行时使用新产物。第一步安装与配置 Relay Compiler在运行编译器之前需要先完成安装与配置。以 npm/yarn 手动安装为例# 安装 React 与 React Relay 运行时 yarn add react react-dom react-relay # 安装编译器作为开发依赖 yarn add --dev relay-compilerrelay-compiler包会在node_modules中安装relay-compiler可执行脚本参见 packages/relay-compiler/package.json 中的bin: cli.js。推荐在package.json中注册一个 npm script而不是直接调用二进制scripts: { relay: relay-compiler }这样在命令行中即可通过yarn run relay或npm run relay触发编译。配置文件relay.config.json 或 package.json 的 relay 键编译器需要一个配置文件来定位源码目录、Schema 与语言类型。最常见的方式是创建relay.config.js// relay.config.js module.exports { // 以下配置项同时被 relay-compiler 命令行工具与 babel-plugin-relay 接受 src: ./src, // 源码目录编译器从这里扫描 graphql 标签 language: javascript, // javascript | typescript | flow schema: ./data/schema.graphql, // GraphQL Schema 文件路径 excludes: [**/node_modules/**, **/__mocks__/**, **/__generated__/**], }这份配置也可以放在package.json的relay字段中。从当前仓库的 Rust 编译器实现看配置查找逻辑会从当前工作目录向上逐级搜索relay.config.json或 package.json 中的relay键见 compiler/crates/relay-bin/src/main.rs 中Config::search(current_dir())的调用。仓库中的真实配置示例可以参考 compiler/test-project/relay.config.json它展示了更完整的配置结构包括root、sources映射、header文件头注释以及projects多项目配置{ root: ../.., header: [Copyright (c) Meta Platforms, Inc. and affiliates.], sources: { compiler/test-project: test }, projects: { test: { customScalarTypes: {}, enumModuleSuffix: .test, schema: packages/relay-test-utils-internal/testschema.graphql, language: javascript } } }关于persistConfig远程持久化 GraphQL 文档、schemaExtensions等更多配置项的定义可以在 compiler/crates/relay-config/src/project_config.rs 中查看其 Rust 结构体与字段注释。配套设置 babel-plugin-relay除编译器外Relay 还要求一个 Babel 插件将代码中的graphql标签转换为对生成产物的require()调用yarn add --dev babel-plugin-relay graphql然后在.babelrc中加入插件{ plugins: [relay] }注意relay插件应先于其他插件或 preset 运行以保证graphql模板字面量被正确转换。另外也可以用babel-plugin-macros方式替代const graphql require(babel-plugin-relay/macro)该插件的实现位于 packages/babel-plugin-relay/BabelPluginRelay.js。第二步运行编译器配置完成后每次修改源码中的graphql标签都需要重新生成产物yarn run relay这条命令会定位并加载配置文件relay.config.json/package.json中的relay键读取 GraphQL Schema 文件如.graphql后缀的 SDL 文件扫描src目录下所有源码文件中的graphql字面量生成一系列与源码文件同目录的__generated__子目录并在其中写入.graphql.js或.graphql.ts产物文件。以官方文档的字典示例为例给定如下两个源码文件src/Components/DictionaryComponent.jsconst DictionaryWordFragment graphql fragment DictionaryComponent_word on Word { id definition { ...DictionaryComponent_definition } } const DictionaryDefinitionFragment graphql fragment DictionaryComponent_definition on WordDefinition { text image } src/Queries/DictionaryQuery.jsconst DictionaryQuery graphql query DictionaryQuery { dictionary { ...DictionaryComponent_word } } 运行编译器后将生成三个产物文件与两个__generated__目录src/Components/__generated__/DictionaryComponent_word.graphql.jssrc/Components/__generated__/DictionaryComponent_definition.graphql.jssrc/Queries/__generated__/DictionaryQuery.graphql.js产物中既包含运行时制品帮助读写 Relay Store 的 Reader/Normalization 节点也包含Flow 类型注释用于编写类型安全的代码。由于查询在构建期就被优化例如合并重复字段Relay 运行时不再负责生成查询字符串从而大幅降低了运行时的解析与处理开销。第三步使用 watch 模式持续编译在开发过程中手动反复运行编译器显然低效。Relay Compiler 支持watch 模式监听源码文件变化并自动重新生成产物yarn run relay --watch注意前提条件watch 模式依赖 watchman 进行文件监听文档中的原始说明如此仓库实现同样印证了这一点。从 compiler/crates/relay-bin/src/main.rs 的should_use_watchman函数可以看到编译器默认会检查watchman二进制是否可用若不可用则回退到目录遍历方式WalkDir而在 watch 模式下如果无法使用 watchman编译器会直接报错退出Cannot run relay in watch mode ifwatchmanis not available. Install watchman or remove the --watch flag.此外设置环境变量FORCE_NO_WATCHMAN或传入--noWatchman标志可显式禁用 watchman但 watch 模式与--noWatchman互斥。更多 CLI 选项来自 Rust 实现的完整视角当前仓库中Relay Compiler 的命令行入口由 Rust 实现入口位于 compiler/crates/relay-bin/src/main.rs。除--watch外其CompileCommand还支持以下实用参数参数说明--watch/-w监听文件变更并自动重新编译需 watchman--project name/-p只编译指定项目可重复传入不传则编译所有项目--config path指定配置文件路径缺省时向上搜索relay.config.json或 package.json 的relay键--noWatchman禁用 watchman改用目录遍历扫描源文件与--watch互斥--validate检查是否存在待写入的产物变更并以非零码退出不实际写盘CI 校验用--repersist即使查询未变化也强制执行持久化流程--output kind日志级别debug/quiet/quiet-with-errors/verbose默认verbose--daemon(Unix)将构建交给后台编译器守护进程复用进程以消除每次构建的启动开销与--watch、--validate等冲突--src/--schema/--artifactDirectory旧版内联配置参数目前直接传入会提示改用配置文件其中--project对应多项目monorepo场景set_project_flag会先禁用所有项目再仅启用被选中的项目。若传入了不存在的项目名会报错并列出可用项目。此外该 CLI 还提供lsp启动语言服务器供 IDE 使用、config-json-schema输出配置的 JSON Schema、codemod、experimental-regenerate-subschema等子命令。如何导入生成的产物日常开发中你通常不需要手动 import 生成文件——babel-plugin-relay 会自动把源码中的graphql字面量转换成对对应生成文件的require()调用。不过编译器同时会生成 Flow 类型注释你可以像下面这样导入类型用于类型检查import type {DictionaryComponent_word} from ./__generated__/DictionaryComponent_word.graphql;在少数需要跨文件复用同一 Query/Mutation/Fragment 的场景下也可以直接导入产物本体import DictionaryComponent_word from ./__generated__/DictionaryComponent_word.graphql;常见问题与工作流要点改了代码但运行时没有新数据先确认yarn run relay或--watch是否在运行产物是否已重新生成——Relay 运行时读取的是磁盘上的产物文件而不是源码中的graphql标签。watch 模式启动失败检查 watchman 是否已安装并位于$PATH中也可用--noWatchman配合一次性编译但 watch 模式必须依赖 watchman。多项目仓库只编译部分代码使用--project精确指定每个项目在projects配置中拥有独立的 schema、language 与输出设置。CI 中如何防止产物漂移使用--validate让编译器在检测到待写入变更时以非零状态退出从而在流水线中拦截未提交的产物更新。产物目录被重复编译在excludes中排除**/__generated__/**、**/node_modules/**等目录避免扫描器把产物当作源码输入。总之Relay 的日常开发工作流可以概括为一条主线安装并配置 Relay Compiler → 编写带graphql标签的组件 → 运行yarn run relay开发时用--watch→ 由 Babel 插件将产物接入运行时。理解这条链路你就掌握了 Relay 从源码到数据层运行的全部关键环节相关安装细节可回看 安装与设置指南编译原理可阅读 Relay Compiler 文档。赞分享前端开发工具【免费下载链接】relayRelay is a JavaScript framework for building>项目地址https://gitcode.com/gh_mirrors/relay29/relay点击查看免费下载相关推荐Relay 开发工作流从配置 Relay Compiler 到生成运行时产物Relay 开发工作流从配置 Relay Compiler 到生成运行时产物 本篇技术指南以 Relay v14 文档中的 Workflow 章节为核心讲解前端开发工具Relay 开发工作流实战掌握 Relay Compiler 的编译、产物生成与 watch 模式Relay 开发工作流实战掌握 Relay Compiler 的编译、产物生成与 watch 模式 本文聚焦 Relay数据驱动的 React 应用框架日前端开发工具Relay 开发工作流用 Relay Compiler 把 graphql 字面量变成运行时产物Relay 开发工作流用 Relay Compiler 把 graphql 字面量变成运行时产物 在 Relay 的日常开发中 graphql 模板标签只负前端开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考