Relay 编辑器支持深入指南基于 Rust 编译器的 LSP 与官方 VS Code 扩展【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay本文基于仓库website/versioned_docs/version-v17.0.0/editor-support.md编写并结合作者所在仓库中vscode-extension/与compiler/crates/relay-lsp/的源码、配置与测试进行纵深展开。自 Relay v14.0.0 起全新的 Rust 版 Relay 编译器不仅能编译 GraphQL还能把编译器内部对代码中 GraphQL 的深刻理解直接变成编辑器里的语言能力诊断、自动补全、Hover 类型信息、跳转定义与快速修复。这篇文章将带你完整认识这套基于 Language Server ProtocolLSP的编辑器支持体系——从语言服务器relay-lsp的底层实现到官方 VS Code 扩展的安装、配置与多项目实战让你拿到即可用、出问题也能快速定位。从编译器到编辑器Relay 编辑器支持的架构Relay 编译器长期依赖代码中对graphqltagged template 的解析、对 schema 的建模以及对 Relay 特有指令的语义分析因此编译器本身比任何通用工具都更懂 Relay 代码。为了让这份理解直接服务开发者官方自 v14.0.0 起将新版 Rust 编译器扩展为编辑器侧的语言服务语言服务器Language Server基于 Language Server Protocol 实现协议标准化意味着理论上可被多种编辑器复用官方 VS Code 扩展与语言服务器配套发布扩展名为Relay GraphQLpublisher 为meta市场标识meta.relay由来自 Coinbase 的 Terence Bezman 贡献与本仓库中的 vscode-extension 目录对应Rust 编译器内核LSP 与编译器共享同一套解析、schema 与 IR 逻辑能力来自 compiler 下的多个 crate其中语言服务器本体位于 compiler/crates/relay-lsp。一句话总结架构VS Code 扩展TypeScript 客户端→ 通过stdio与JSON-RPC通信 →relay-lspRust 语言服务器→ 复用relay-compiler的 schema、解析与校验能力。开箱即用的六大语言特性原文档明确了这套编辑器支持带来的核心体验以下逐条展开并给出仓库内对应实现模块作为佐证。1. 编译错误以红色波浪线直接呈现在编辑器Relay 编译器诊断诊断会以 LSPpublishDiagnostics通知的形式映射为编辑器 Problems 面板里的红色波浪线不再需要切到终端看编译输出。错误信息来自relay-compiler的校验与类型检查再经由 diagnostic_reporter.rs 转换为 LSP 诊断且很多诊断会附带快速修复见第 6 点。2. GraphQL tagged template 内的自动补全在graphql字符串模板、.graphql文件甚至 Relay docblock 中扩展提供基于当前 schema 与已定义 fragment 的补全建议。对应实现为 completion.rs并配有专门测试 completion/test.rs。3. Hover 查看类型信息与 Relay 特性文档鼠标悬停在字段、类型或指令上即可看到类型信息与 Relay 特定说明相关文档可进一步链接到官方文档站。实现位于 hover.rs其中 hover/with_resolution_path.rs 负责把节点解析为 schema 中的具体路径后生成悬停内容。4.deprecated字段以删除线呈现被标记为deprecated的 schema 字段在补全、Hover 等场景中以strikethrough渲染让开发者一眼识别不建议使用的内容。5. Fragment、字段与类型的点击跳转定义对 fragment、字段、GraphQL 类型等符号提供 Go to Definition。实现拆分为两类goto_graphql_definition.rs处理 GraphQL 代码内的跳转goto_docblock_definition.rs处理 Relay docblock如RelayResolver等注释语法内的跳转。6. 常见错误的快速修复建议部分诊断支持 Quick Fix 代码动作典型例子是 code_action/create_name_suggestion.rs 提供的命名建议类修复。转换链路在 lib.rs 的diagnostics_to_code_actions中可见诊断先经DiagnosticReporter发布再对每条诊断调用get_code_actions_from_diagnostic生成 CodeAction。扩展能力不止这六项从 relay-lsp 的模块清单 看语言服务器还内置了更多语言特性references.rs查找引用rename.rs符号重命名inlay_hints.rs内联提示inlay hintsfind_field_usages字段使用位置查找type_information.rs类型信息解析。语言服务器relay-lsp底层实现速览语言服务器本体是 Rust craterelay-lsp入口为 lib.rs 的start_language_server通过Connection::stdio()建立基于标准输入输出的传输层完成 LSP 的 JSON-RPC 握手initialize进入 server.rs 的run主循环等待请求/通知。服务器要处理的文件形态由Feature枚举刻画见 lib.rsExecutableDocumentgraphqltagged template 与.graphql查询文档DocblockIrRelay docblock 注释RelayResolver、weak等指令的 JS 侧描述SchemaDocument.graphqlschema 定义文件。也就是说LSP 不是只懂查询字符串而是把 Relay 生态里的三类GraphQL 存在形式统一建模。服务器内部按职责拆分为 server/lsp_request_dispatch.rs、server/lsp_notification_dispatch.rs、server/lsp_state.rs、server/task_queue.rs 与 server/heartbeat.rs 等模块分别负责请求分派、状态管理与后台任务调度。测试用例集中在 relay-lsp/tests含大量.graphql输入与.expected期望输出可用于验证各语言特性的行为。官方 VS Code 扩展安装与前置条件安装在 VS Code 扩展面板搜索Relay GraphQL安装市场标识meta.relay或通过命令行安装。扩展的激活条件覆盖了javascript、javascriptreact、typescript、typescriptreact、graphql与plaintext等语言见 package.json 的 activationEvents。四个前置条件参考 vscode-extension/README.md要让扩展正常工作需要满足项目内至少存在一个 Relay 配置文件。支持标准格式.yml、.js、.json也支持package.json中的relay字段扩展对relay.config.json与package.json还注册了 JSON Schema 校验见 package.json 的 jsonValidation项目中安装了relay-compiler。最低版本要求为 v13语言服务器围绕新 Rust 编译器构建能通过命令行运行relay-compiler。README 给出的自检标准很实用如果yarn relay-compiler能跑通扩展大概率也能工作移除或禁用其他冲突的 GraphQL 扩展避免诊断、补全相互干扰。扩展启动时会在 extension.ts 中通过findRelayBinaryWithWarnings定位relay-compiler二进制默认在node_modules中查找找不到有效二进制会直接停止扩展并输出提示信息。配置项详解扩展配置统一挂在relay.*命名空间下声明见 package.json 的 contributes.configuration读取逻辑见 config.ts。部分配置仅在单/多 Relay 项目场景下生效以下分类说明。公共配置配置项默认值说明relay.autoStartCompilerfalse打开项目时是否自动以 watch 模式启动 Relay Compiler。关闭时可通过命令手动启动relay.compilerOutputLevelverbose编译器输出级别quiet、quiet-with-errors、verbose、debugrelay.lspOutputLevelquiet-with-errors语言服务器输出级别取值同上relay.pathToRelaynull指向 Relay 二进制的路径相对项目根目录。未指定时自动在node_modules中查找源码细节config.ts 中compilerOutputLevel的兜底值是info与 README/package.json 声明的verbose存在出入实际值以你安装版本的设置为准建议显式配置以免歧义。单 Relay 项目配置配置项默认值说明relay.namedefault项目名称用于展示该项目相关的输出信息relay.rootDirectory项目根目录相对 VS Code 项目根目录的路径。改变它会影响查找relay-compiler模块的起点也会影响 LSP 启动目录进而影响 Relay 配置的发现。适用于项目位于嵌套目录的场景relay.pathToConfignull相对rootDirectory的 Relay 配置文件路径。不设置时编译器自动搜索配置。同样适用于嵌套目录场景多 Relay 项目配置配置项默认值说明relay.projectsnull项目配置数组元素形如{name: string, rootDirectory: string, pathToConfig: string}。省略时假定工作区使用单个 Relay 配置编译器自动搜索。工作区存在多个各自带配置文件的 Relay 项目时必须使用此项relay.pathToLocateCommandnullimplementation-first GraphQL schema 下用于查找 GraphQL 实体实际定义位置的外部脚本路径。需要 Relay compiler 15.0.0relay.pathToLocateCommand的脚本协议值得单独说明每当 LSP 收到 goto definition 请求时调用该脚本而不是打开 schema 文件脚本接收 2 个参数第一个是 Relay 项目名第二个是要定位的实体形式为Type或Type.field分别表示类型或类型的字段脚本必须输出单行结果格式为/absolute/file/path:1:2其中1为文件中的行号、2为该行中定义起始的字符位置若输出无法匹配该格式或脚本执行失败LSP 会回退为打开 GraphQL schema。扩展提供的命令扩展注册了四个命令见 package.json 的 contributes.commands实现位于 commands命令标识作用Relay: Restartrelay.restart重启 Relay 语言服务器配置变更或 LSP 异常时的首选恢复手段Relay: Start Compilerrelay.startCompiler手动启动编译器watch 模式Relay: Stop Compilerrelay.stopCompiler停止正在运行的编译器Relay: Copy Operationrelay.copyOperation复制当前操作如查询/变更的文本其中 Start Compiler 的实现位于 compiler.ts它在集成终端中执行relay-compiler --watch --outputcompilerOutputLevel [pathToConfig]且按relay.pathToConfig自动追加配置文件路径参数。为什么需要 Relay 专用扩展而非通用 GraphQL 扩展GraphQL 基金会提供了官方的通用 GraphQL 语言服务器与 VS Code 扩展GraphQL.vscode-graphql能提供不错的基线体验。但对于 Relay 用户而言直接从 Relay 编译器获取信息有两点不可替代的优势错误即 problems且常带快速修复Relay 编译器的错误如 fragment 未定义、字段类型不匹配、缺失arguments等直接呈现在编辑器 Problems 面板不少错误还附带 Quick Fix闭环了报错 → 一键修复的体验Hover 感知 Relay 特有特性与指令connection、arguments、refetchable、RelayResolver等 Relay 专属指令与特性会得到正确解析悬停信息可以链接到对应官方文档。同时注意扩展依赖GraphQL.vscode-graphql-syntax提供 GraphQL 语法高亮见 package.json 的 extensionDependencies因此在安装 Relay 扩展时建议保留语法高亮扩展、禁用功能重叠的通用 LSP 扩展。已知限制与故障排查版本边界语言服务器围绕新版 Rust 编译器v13构建官方无计划支持 v13 之前的编译器见 README 的 Known Issues二进制缺失找不到relay-compiler时扩展会停止执行请先确认yarn relay-compiler可用可通过relay.pathToRelay显式指定二进制位置输出通道扩展创建了Relay编译器输出与Relay LSP Logs语言服务器日志两个输出通道排查问题时建议把relay.lspOutputLevel调到verbose或debug后重启语言服务器命令Relay: Restart多项目工作区多个 Relay 项目共存时必须配置relay.projects否则扩展只会按单个配置搜索implementation-first schema需要relay.pathToLocateCommand提供外部定位脚本且要求 Relay compiler 15.0.0否则跳转会回退到 schema 文件。延伸阅读VS Code 扩展完整说明扩展 manifest命令与配置声明语言服务器入口与诊断转 CodeAction语言服务器模块与测试Rust 编译器工作区【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Relay 编辑器支持深入指南：基于 Rust 编译器的 LSP 与官方 VS Code 扩展
Relay 编辑器支持深入指南基于 Rust 编译器的 LSP 与官方 VS Code 扩展【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay本文基于仓库website/versioned_docs/version-v17.0.0/editor-support.md编写并结合作者所在仓库中vscode-extension/与compiler/crates/relay-lsp/的源码、配置与测试进行纵深展开。自 Relay v14.0.0 起全新的 Rust 版 Relay 编译器不仅能编译 GraphQL还能把编译器内部对代码中 GraphQL 的深刻理解直接变成编辑器里的语言能力诊断、自动补全、Hover 类型信息、跳转定义与快速修复。这篇文章将带你完整认识这套基于 Language Server ProtocolLSP的编辑器支持体系——从语言服务器relay-lsp的底层实现到官方 VS Code 扩展的安装、配置与多项目实战让你拿到即可用、出问题也能快速定位。从编译器到编辑器Relay 编辑器支持的架构Relay 编译器长期依赖代码中对graphqltagged template 的解析、对 schema 的建模以及对 Relay 特有指令的语义分析因此编译器本身比任何通用工具都更懂 Relay 代码。为了让这份理解直接服务开发者官方自 v14.0.0 起将新版 Rust 编译器扩展为编辑器侧的语言服务语言服务器Language Server基于 Language Server Protocol 实现协议标准化意味着理论上可被多种编辑器复用官方 VS Code 扩展与语言服务器配套发布扩展名为Relay GraphQLpublisher 为meta市场标识meta.relay由来自 Coinbase 的 Terence Bezman 贡献与本仓库中的 vscode-extension 目录对应Rust 编译器内核LSP 与编译器共享同一套解析、schema 与 IR 逻辑能力来自 compiler 下的多个 crate其中语言服务器本体位于 compiler/crates/relay-lsp。一句话总结架构VS Code 扩展TypeScript 客户端→ 通过stdio与JSON-RPC通信 →relay-lspRust 语言服务器→ 复用relay-compiler的 schema、解析与校验能力。开箱即用的六大语言特性原文档明确了这套编辑器支持带来的核心体验以下逐条展开并给出仓库内对应实现模块作为佐证。1. 编译错误以红色波浪线直接呈现在编辑器Relay 编译器诊断诊断会以 LSPpublishDiagnostics通知的形式映射为编辑器 Problems 面板里的红色波浪线不再需要切到终端看编译输出。错误信息来自relay-compiler的校验与类型检查再经由 diagnostic_reporter.rs 转换为 LSP 诊断且很多诊断会附带快速修复见第 6 点。2. GraphQL tagged template 内的自动补全在graphql字符串模板、.graphql文件甚至 Relay docblock 中扩展提供基于当前 schema 与已定义 fragment 的补全建议。对应实现为 completion.rs并配有专门测试 completion/test.rs。3. Hover 查看类型信息与 Relay 特性文档鼠标悬停在字段、类型或指令上即可看到类型信息与 Relay 特定说明相关文档可进一步链接到官方文档站。实现位于 hover.rs其中 hover/with_resolution_path.rs 负责把节点解析为 schema 中的具体路径后生成悬停内容。4.deprecated字段以删除线呈现被标记为deprecated的 schema 字段在补全、Hover 等场景中以strikethrough渲染让开发者一眼识别不建议使用的内容。5. Fragment、字段与类型的点击跳转定义对 fragment、字段、GraphQL 类型等符号提供 Go to Definition。实现拆分为两类goto_graphql_definition.rs处理 GraphQL 代码内的跳转goto_docblock_definition.rs处理 Relay docblock如RelayResolver等注释语法内的跳转。6. 常见错误的快速修复建议部分诊断支持 Quick Fix 代码动作典型例子是 code_action/create_name_suggestion.rs 提供的命名建议类修复。转换链路在 lib.rs 的diagnostics_to_code_actions中可见诊断先经DiagnosticReporter发布再对每条诊断调用get_code_actions_from_diagnostic生成 CodeAction。扩展能力不止这六项从 relay-lsp 的模块清单 看语言服务器还内置了更多语言特性references.rs查找引用rename.rs符号重命名inlay_hints.rs内联提示inlay hintsfind_field_usages字段使用位置查找type_information.rs类型信息解析。语言服务器relay-lsp底层实现速览语言服务器本体是 Rust craterelay-lsp入口为 lib.rs 的start_language_server通过Connection::stdio()建立基于标准输入输出的传输层完成 LSP 的 JSON-RPC 握手initialize进入 server.rs 的run主循环等待请求/通知。服务器要处理的文件形态由Feature枚举刻画见 lib.rsExecutableDocumentgraphqltagged template 与.graphql查询文档DocblockIrRelay docblock 注释RelayResolver、weak等指令的 JS 侧描述SchemaDocument.graphqlschema 定义文件。也就是说LSP 不是只懂查询字符串而是把 Relay 生态里的三类GraphQL 存在形式统一建模。服务器内部按职责拆分为 server/lsp_request_dispatch.rs、server/lsp_notification_dispatch.rs、server/lsp_state.rs、server/task_queue.rs 与 server/heartbeat.rs 等模块分别负责请求分派、状态管理与后台任务调度。测试用例集中在 relay-lsp/tests含大量.graphql输入与.expected期望输出可用于验证各语言特性的行为。官方 VS Code 扩展安装与前置条件安装在 VS Code 扩展面板搜索Relay GraphQL安装市场标识meta.relay或通过命令行安装。扩展的激活条件覆盖了javascript、javascriptreact、typescript、typescriptreact、graphql与plaintext等语言见 package.json 的 activationEvents。四个前置条件参考 vscode-extension/README.md要让扩展正常工作需要满足项目内至少存在一个 Relay 配置文件。支持标准格式.yml、.js、.json也支持package.json中的relay字段扩展对relay.config.json与package.json还注册了 JSON Schema 校验见 package.json 的 jsonValidation项目中安装了relay-compiler。最低版本要求为 v13语言服务器围绕新 Rust 编译器构建能通过命令行运行relay-compiler。README 给出的自检标准很实用如果yarn relay-compiler能跑通扩展大概率也能工作移除或禁用其他冲突的 GraphQL 扩展避免诊断、补全相互干扰。扩展启动时会在 extension.ts 中通过findRelayBinaryWithWarnings定位relay-compiler二进制默认在node_modules中查找找不到有效二进制会直接停止扩展并输出提示信息。配置项详解扩展配置统一挂在relay.*命名空间下声明见 package.json 的 contributes.configuration读取逻辑见 config.ts。部分配置仅在单/多 Relay 项目场景下生效以下分类说明。公共配置配置项默认值说明relay.autoStartCompilerfalse打开项目时是否自动以 watch 模式启动 Relay Compiler。关闭时可通过命令手动启动relay.compilerOutputLevelverbose编译器输出级别quiet、quiet-with-errors、verbose、debugrelay.lspOutputLevelquiet-with-errors语言服务器输出级别取值同上relay.pathToRelaynull指向 Relay 二进制的路径相对项目根目录。未指定时自动在node_modules中查找源码细节config.ts 中compilerOutputLevel的兜底值是info与 README/package.json 声明的verbose存在出入实际值以你安装版本的设置为准建议显式配置以免歧义。单 Relay 项目配置配置项默认值说明relay.namedefault项目名称用于展示该项目相关的输出信息relay.rootDirectory项目根目录相对 VS Code 项目根目录的路径。改变它会影响查找relay-compiler模块的起点也会影响 LSP 启动目录进而影响 Relay 配置的发现。适用于项目位于嵌套目录的场景relay.pathToConfignull相对rootDirectory的 Relay 配置文件路径。不设置时编译器自动搜索配置。同样适用于嵌套目录场景多 Relay 项目配置配置项默认值说明relay.projectsnull项目配置数组元素形如{name: string, rootDirectory: string, pathToConfig: string}。省略时假定工作区使用单个 Relay 配置编译器自动搜索。工作区存在多个各自带配置文件的 Relay 项目时必须使用此项relay.pathToLocateCommandnullimplementation-first GraphQL schema 下用于查找 GraphQL 实体实际定义位置的外部脚本路径。需要 Relay compiler 15.0.0relay.pathToLocateCommand的脚本协议值得单独说明每当 LSP 收到 goto definition 请求时调用该脚本而不是打开 schema 文件脚本接收 2 个参数第一个是 Relay 项目名第二个是要定位的实体形式为Type或Type.field分别表示类型或类型的字段脚本必须输出单行结果格式为/absolute/file/path:1:2其中1为文件中的行号、2为该行中定义起始的字符位置若输出无法匹配该格式或脚本执行失败LSP 会回退为打开 GraphQL schema。扩展提供的命令扩展注册了四个命令见 package.json 的 contributes.commands实现位于 commands命令标识作用Relay: Restartrelay.restart重启 Relay 语言服务器配置变更或 LSP 异常时的首选恢复手段Relay: Start Compilerrelay.startCompiler手动启动编译器watch 模式Relay: Stop Compilerrelay.stopCompiler停止正在运行的编译器Relay: Copy Operationrelay.copyOperation复制当前操作如查询/变更的文本其中 Start Compiler 的实现位于 compiler.ts它在集成终端中执行relay-compiler --watch --outputcompilerOutputLevel [pathToConfig]且按relay.pathToConfig自动追加配置文件路径参数。为什么需要 Relay 专用扩展而非通用 GraphQL 扩展GraphQL 基金会提供了官方的通用 GraphQL 语言服务器与 VS Code 扩展GraphQL.vscode-graphql能提供不错的基线体验。但对于 Relay 用户而言直接从 Relay 编译器获取信息有两点不可替代的优势错误即 problems且常带快速修复Relay 编译器的错误如 fragment 未定义、字段类型不匹配、缺失arguments等直接呈现在编辑器 Problems 面板不少错误还附带 Quick Fix闭环了报错 → 一键修复的体验Hover 感知 Relay 特有特性与指令connection、arguments、refetchable、RelayResolver等 Relay 专属指令与特性会得到正确解析悬停信息可以链接到对应官方文档。同时注意扩展依赖GraphQL.vscode-graphql-syntax提供 GraphQL 语法高亮见 package.json 的 extensionDependencies因此在安装 Relay 扩展时建议保留语法高亮扩展、禁用功能重叠的通用 LSP 扩展。已知限制与故障排查版本边界语言服务器围绕新版 Rust 编译器v13构建官方无计划支持 v13 之前的编译器见 README 的 Known Issues二进制缺失找不到relay-compiler时扩展会停止执行请先确认yarn relay-compiler可用可通过relay.pathToRelay显式指定二进制位置输出通道扩展创建了Relay编译器输出与Relay LSP Logs语言服务器日志两个输出通道排查问题时建议把relay.lspOutputLevel调到verbose或debug后重启语言服务器命令Relay: Restart多项目工作区多个 Relay 项目共存时必须配置relay.projects否则扩展只会按单个配置搜索implementation-first schema需要relay.pathToLocateCommand提供外部定位脚本且要求 Relay compiler 15.0.0否则跳转会回退到 schema 文件。延伸阅读VS Code 扩展完整说明扩展 manifest命令与配置声明语言服务器入口与诊断转 CodeAction语言服务器模块与测试Rust 编译器工作区【免费下载链接】relayRelay is a JavaScript framework for building>项目地址: https://gitcode.com/gh_mirrors/relay29/relay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考