vscode-graphql-syntax 语法高亮演进全解TextMate 语法、嵌入式注入与 GraphQL 作用域设计【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiqlGraphiQL 生态中的vscode-graphql-syntaxGraphQL: Syntax Highlighting是一个独立的 VS Code 语法高亮扩展为.graphql/.gql/.graphqls文件提供完整高亮并将高亮注入到 JavaScript、TypeScript、Vue、Svelte、Astro、Markdown、Python、PHP、Scala、Reason/OCaml、ReScript 等宿主语言中。本文以其 CHANGELOG.md 为骨架结合 grammars/ 下的 TextMate 语法源码与 tests/ 下的 tokenize 测试逐版本还原它的演进脉络讲清楚字符串值 vs 描述的作用域修复、嵌入语法注入机制、可重复指令等关键实现读完你既能快速定位某个高亮行为来自哪个版本/哪条规则也能照着贡献指南为其他语言添加高亮支持。一、扩展定位为什么需要独立的语法高亮扩展在 GraphiQL 仓库中GraphQL 的 VS Code 支持被拆成了两个独立发布的扩展详见 packages/vscode-graphql-syntax/CHANGELOG.md 1.0.4 一节vscode-graphql-syntax本文主题纯语法高亮 括号匹配等语言基础能力vscode-graphqlpackages/vscode-graphql/package.json基于 LSP 的完整语言特性如自动补全、校验、跳转定义、Hover、大纲等。两者通过extensionDependencies关联vscode-graphql声明依赖GraphQL.vscode-graphql-syntax用户安装 LSP 扩展时语法扩展会被自动安装。从 1.0.4 起二者拥有独立的发布生命周期好处是只需要高亮、不需要 LSP 的开发者可以只装语法扩展其他 GraphQL 生态包括非 GraphiQL 系的 LSP 服务器可以共享、复用这套社区语法——它在某种程度上成为了一份共享的工具与标注规范。扩展的engines.vscode要求为^1.63.0类别为Programming Languages版本基线为 1.3.13见 package.json。二、高亮架构一个主语法 七个注入语法整个扩展的核心资产是 grammars/ 下的 JSON 文件全部基于 VS Code 的 TextMate 语法体系通过 package.json 的contributes.grammars注册语法文件scopeName注入目标injectTo用途graphql.jsonsource.graphql无主语法.graphql/.gql/.graphqls文件本体graphql.js.jsoninline.graphqlsource.js、source.ts、source.js.jsx、source.tsx、source.vue、source.svelte、source.astro、text.html.markdown、text.html.derivative、text.html.vueJS/TS 模板字符串、Vue/Svelte/Astro 组件graphql.re.jsoninline.graphql.resource.reason、source.ocaml、text.html.markdown、text.html.derivativeReasonML/OCaml 的%graphql/{gql|...|}graphql.rescript.jsoninline.graphql.ressource.rescript、text.html.markdown、text.html.derivativeReScript 的%graphql(...)graphql.markdown.codeblock.jsoninline.graphql.markdown.codeblocktext.html.markdown、text.html.derivativeMarkdown 中graphql代码块graphql.python.jsoninline.graphql.pythonsource.python、text.html.markdown、text.html.derivativePython 的gql(...)graphql.php.jsoninline.graphql.phptext.html.php、text.html.markdown、text.html.derivativePHP heredoc/nowdoc 与/* GraphQL */注释graphql.scala.jsoninline.graphql.scalasource.scala、text.html.markdown、text.html.derivativeScala 的gql...所有注入语法都通过embeddedLanguages将meta.embedded.block.graphql映射到graphql语言从而让嵌入内容不仅能着色还能参与括号匹配、区块选择等语言能力。三、核心高亮机制剖析3.1 主语法source.graphql的规则组织graphql.json 顶层repository以#graphql为总入口按顺序 include 十余条子规则注释与描述#graphql-comment、#graphql-description-docstring、#graphql-description-string、#graphql-description-singleline定义类#graphql-fragment-definition、#graphql-directive-definition、#graphql-type-interface覆盖type/interface/input/extend、#graphql-enum、#graphql-scalar、#graphql-union、#graphql-schema操作类#graphql-operation-def→#graphql-query-mutation-subscription1.3.9 起支持subscription关键字、选择集#graphql-selection-set、字段#graphql-field、片段展开#graphql-fragment-spread、内联片段#graphql-inline-fragment值类#graphql-value聚合了变量名、浮点/布尔/null/枚举值、string.quoted.double字符串值、string.quoted.triple块字符串值、列表值、对象值内嵌插值#native-interpolation负责模板字符串里的${...}回退 includesource.js/source.ts等宿主作用域#literal-quasi-embedded处理 gql 插值占位。一个典型查询的 tokenize 结果由 tests/fixtures/query.graphql 等 fixture 与快照 graphql-grammar.spec.ts.snap 固化。3.2 JS/TS 注入语法inline.graphql的三种识别模式graphql.js.json 通过injectionSelector精准限定注入位置L:... -source.graphql -inline.graphql -string -comment避免二次注入和干扰字符串/注释支持三类写法// 1) 标签模板字符串graphql、gql、graphql.experimental、Relay.QL含泛型参数 const query gql query getContinents { continents { code name } } ; // 2) 注释标记/* GraphQL */注意是 GraphQL 而非 GraphiQL const query /* GraphQL */ query simple { stuff(id: 1) { id name } } ; // 3) 模板首行 #graphql 注释标记 const query #graphql query simple { stuff(id: 1) { id name } } ;其中/* GraphQL */的分隔符在 1.0.5 的文档勘误中明确过vscode-graphql-syntax与vscode-graphql语言支持的分隔符是/* GraphQL */不是/* GraphiQL */tests/fixtures/test.js、test.ts 中有对应用例。3.3 宿主语言的注入语法Pythongraphql.python.json匹配gql(后跟随的/多行字符串以及以#graphql开头的三引号字符串。fixture test.py 覆盖了单行、多行、跨行 gql 调用与#graphql标记共六种写法。PHPgraphql.php.json匹配GRAPHQLheredoc、GRAPHQLnowdoc、/** lang GraphQL */注释以及/* GraphQL *///* GraphiQL *//// graphql注释后跟随的字符串。Markdowngraphql.markdown.codeblock.json匹配graphql/gql/GraphQL大小写不敏感三或更多反引号/波浪号围栏代码块注入source.graphql同时也支持 Markdown 中的 php、python 等围栏示例见 test.md。ReasonML/OCamlgraphql.re.json匹配{gql|...|gql}与%graphql扩展点。ReScriptgraphql.rescript.json匹配%graphql(后接反引号的写法。Scalagraphql.scala.json匹配gql...、graphql...、schema...及#graphql三引号标记。四、CHANGELOG 逐版本详解从 1.0.4 到 1.3.134.1 1.0.4 —— 独立成包的里程碑这是 1.x 系列最关键的架构变更语法与基础语言支持从vscode-graphql迁移到独立的GraphQL.vscode-graphql-syntax扩展vscode-graphql仅保留 LSP 特性并声明extensionDependencies。对既有用户无破坏性变更但让仅语法用户与生态内其他扩展得以复用这套社区语法。4.2 1.1.0 —— fragment spread 参数高亮为片段展开...Fragment(args)上的参数以及片段上的变量定义fragment F($var: Type) on T补充高亮。对应主语法中#graphql-fragment-spread规则 include 了#graphql-arguments#graphql-fragment-definitioninclude 了#graphql-variable-definitions见 graphql.json。4.3 1.2.x —— 语言矩阵扩容与注入器重构1.2.0新增 Scala 高亮inline.graphql.scala1.2.2修复 ovsx 发布1.2.3大版本——新增 Ruby 语法为 Markdown 代码块打通 js、ts、jsx、tsx、svelte、vue、ruby、rescript、reason、ocaml、php、python 的 GraphQL 注入重构 TextMate 注入器使其更高效、更精准消除冗余配置此版本由社区成员 RedCMD 与 VS Code 团队 aeschli 协助完成。4.4 1.3.x —— 精确化与修复阶段1.3.0新增 Astro 文件支持source.astro注入目标1.3.1升级 ovsx 发布工具链1.3.2修复三引号注释——暂时禁用内联 JS 双引号字符串的误判避免被当作普通字符串1.3.3修复 TextMate 语法使其支持不紧跟函数调用左括号(的字符串字面量即标签模板写法外的独立字符串场景1.3.4暂时回滚上一版高亮修复该修复引发了更多问题1.3.5重新应用 1.3.3 的字符串字面量修复1.3.6移除 Ruby 高亮支持官方建议改用ruby-lsp提供的 GraphQL 高亮1.3.7将捆绑库与测试升级到 graphql 16.9.01.3.8为指令定义新增repeatable关键字高亮keyword.repeatable.graphql见 graphql.json 的#graphql-directive-definition规则1.3.9新增subscription操作高亮新增text.html.vue注入目标因为 vuejs/language-tools 将 Vue 语法作用域从source.vue改为text.html.vue需要两个目标都注入才能兼容新旧工具链修复 VS Code 扩展发布脚本1.3.10 / 1.3.11因上次发布失败而烧版本burning patch1.3.12字符串值 vs 描述的重大修复详见下节1.3.13连续描述与默认值边界修复详见下节。五、重点专题字符串值 vs 描述的作用域区分这是 1.3.12 与 1.3.13 两个版本联手解决的问题也是本扩展设计上最值得学习的一处。问题背景GraphQL 语法中...与...既可能出现在定义位置字段/参数/指令参数/输入字段的文档描述也可能出现在值位置字符串字面量、默认值。旧语法容易把字符串值高亮成注释描述导致默认值、指令参数值、列表项等被误染为注释色而描述又缺少独立作用域主题无法对文档做差异化样式。1.3.12 的修复将字符串值单行与三引号块字符串在指令/字段参数、列表项、默认值等值位置正确高亮为string同时把描述统一纳入文档作用域comment.block.documentation/comment.line.documentation主题可以单独定制样式默认仍回落到注释色。1.3.13 的修复连续字段/参数描述之间没有逗号分隔时描述中的标点如(value)不再泄漏到后续代码导致整段被高亮为文档同时修复了默认值同行后紧跟描述的紧凑写法compact defaults的高亮边界。底层实现主语法 graphql.json 中并存两组规则描述规则只出现在定义位置#graphql-description-string单行字符串描述scopecomment.line.documentation.graphql、#graphql-description-docstring三引号块描述scopecomment.block.documentation.graphql值规则只出现在值位置#graphql-string-valuestring.quoted.double.graphql含转义处理与非法换行标记、#graphql-block-string-valuestring.quoted.triple.graphql含\\\转义。两条规则的注释分别写明单行字符串描述仅在定义位置 include绝不进入可出现字符串值的位置与作为值使用的三引号块字符串不是描述。正是这种按位置分派规则的设计避免了同名 token 的歧义。测试验证测试文件 graphql-grammar.spec.ts 中两个用例直接对应这两个版本should preserve consecutive descriptions and subsequent definitions断言连续描述文本落在comment.line.documentation.graphql/comment.block.documentation.graphql而default value、input default、use user落在string.quoted.double.graphqlblock default、block directive argument落在string.quoted.triple.graphqlfixture 见 consecutive-descriptions.graphqlshould separate defaults from following descriptions断言紧凑默认值与描述同行时边界的正确切分fixture 见 default-description-boundaries.txtshould tokenize descriptions as documentation and argument values as strings对应 1.3.12fixture 见 descriptions-and-values.graphql。六、语言基础能力language-configuration除了语法文件扩展还通过 language/language-configuration.json 提供括号匹配等编辑器基础能力注释行注释#块注释…括号{}、[]、()三组括号匹配自动闭合对括号三组 不在 string/comment 中时环绕对括号三组 双引号 单引号。七、测试体系与本地开发7.1 测试如何工作测试基于vscode-textmatevscode-oniguruma见 package.json devDependencies用 vitest 驱动对 fixture 文件做真实 tokenize 后与快照比对js-grammar.spec.ts覆盖 TS、JS、Vue SFC、Vue SFC含script编译块、Svelte、Astro 的inline.graphql注入markdown-grammar.spec.ts、python-grammar.spec.ts、php-grammar.spec.ts、reason-grammar.spec.ts、scala-grammar.spec.ts 分别验证各宿主语言的注入graphql-grammar.spec.ts验证source.graphql主语法除上述边界用例还有简单查询 query.graphql、高级查询 kitchen-sink.graphql、Schema StarWarsSchema.graphql。快照产物统一存放在 tests/snapshots/ 下按语言分别命名为graphql-grammar.spec.ts.snap、js-grammar.spec.ts.snap等。7.2 本地运行# 安装依赖后在扩展工作区运行全部 tokenize 测试 yarn test # 更新快照新增 fixture 或改动语法后必须执行 yarn test -u # 打包 vsix 扩展用于在 VS Code 中手动验证 yarn vsce:package手动验证流程执行yarn vsce:package生成 vsix在 VS Code 中右键安装再打开对应 fixture 文件观察着色或使用命令面板的Developer: Inspect Editor Tokens Scopes查看任意 token 的作用域名称。7.3 如何为一个新语言添加高亮README 的贡献指南给出了标准的 TDD 流程在tests/__fixtures__中按现有示例添加你的语言文件写入 bug 用例或新分隔符示例运行yarn test -u观察 vscode-textmate 是否正确 tokenize新增/修改 grammars/ 下对应语法的 pattern再次运行测试期望看到meta.embedded.block.graphql作用域出现在快照中在 package.json 的contributes.grammars中注册新语法injectTo目标、scopeName、path、embeddedLanguages语法命名保持inline.graphql.{lang}一致性scope 采用宿主语言官方语法提供的source.{lang}作用域新增测试 spec 断言快照并在 fixture 中用 TODO 注释记录已知的未支持用例如字符串插值、泛型场景手动用yarn vsce:package打包验证。八、与其他 GraphQL 扩展的关系与使用建议由于 1.0.4 之后的独立生命周期设计vscode-graphql-syntax可以与任意 GraphQL 相关扩展共存vscode-graphql会把高亮作为extensionDependencies自动带入不使用 graphql-config、或想用其他 LSP 服务器的用户也可以单独安装本扩展。扩展采用 MIT 协议LICENSE社区鼓励其他扩展作者直接复用这份语法资产。结语从 1.0.4 的独立拆分到 1.3.13 的描述边界修复vscode-graphql-syntax的每一次版本演进都对应着 CHANGELOG.md 中一条可回溯的修改而这些修改又都能在 grammars/ 的规则与 tests/ 的断言中找到一一对应的实现证据。理解描述与字符串值的按位置分派注入语法与embeddedLanguages映射快照驱动的 TDD 流程这三个设计点你就掌握了这套跨语言 GraphQL 高亮方案的灵魂也为扩展它的语言矩阵做好了准备。【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考