@graphql-tools/graphql-tag-pluck 从代码文件中提取 GraphQL 定义:功能演进、配置选项与源码原理全解析
@graphql-tools/graphql-tag-pluck 从代码文件中提取 GraphQL 定义:功能演进、配置选项与源码原理全解析
@graphql-tools/graphql-tag-pluck 是 graphql-tools 工具链中专用于"从 JavaScript/TypeScript 等代码文件中提取 GraphQL 模板字面量"的核心包。它接收一段代码文本,自动识别 gql、graphql 等标签调用的模板字面量以及 /* GraphQL */ 魔法注释,把它们"拔"出来并转换成带位置信息的 graphql Source 对象,从而让 .js、.ts、.vue、.svelte、.astro、.gts/.gjs 等代码文件可以像 .graphql 文件一样被加载、解析和校验。读完本文,你将掌握该包的完整 API、全部可配置项、多框架支持矩阵,以及它基于 Babel 的底层解析原理,并能把它接入 @graphql-tools/load 的文档加载管线。
一、为什么需要 graphql-tag-pluck
在 GraphQL 的 SDL-first 开发模式中,团队常常把 operation 和 fragment 直接写在代码里,例如:
import gql from 'graphql-tag'
const fragment = gql`
fragment Foo on FooType {
id
}
`
const doc = gql`
query foo {
foo {
...Foo
}
}
${fragment}
`
这些模板字面量虽然内容上是 GraphQL,但以 Babel AST 的角度看它们只是普通的 TemplateLiteral 节点。如果构建工具(如 GraphQL Code Generator、文档校验、schema 合并)想读取这些文档,就必须先扫描代码、定位这些模板字面量并提取出其中的纯 GraphQL 字符串——这正是 graphql-tag-pluck 的职责。该包最初就是为 GraphQL Code Generator 的场景而诞生(官网文档中明确说明 "Originally created because of graphql-code-generator")。
与手写正则或字符串匹配不同,它走的是完整语法解析路线:先用 @babel/parser 把代码解析成 AST,再用 @babel/traverse 遍历 AST,通过"导入来源包名 + 标识符名称 + 模板字面量形态"三重判定来确定哪些模板字面量是 GraphQL 文档,因此可以正确处理别名导入、命名导入、CommonJS require、甚至注释掉的代码(注释在 AST 中不构成节点,自然不会被提取)。
二、安装与快速上手
在项目(Node.js >=16,peer 依赖 graphql ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0,见 package.json)中安装:
npm i @graphql-tools/graphql-tag-pluck
然后通过两个顶层 API 之一提取文档:
import {
gqlPluckFromCodeString,
gqlPluckFromCodeStringSync,
} from '@graphql-tools/graphql-tag-pluck'
import fs from 'fs'
// 异步版本,返回 Promise<Source[]>
gqlPluckFromCodeString(
filePath, // 必填,用于检测文件类型(扩展名)
fs.readFileSync(filePath, 'utf8'),
)
// 同步版本,返回 Source[]
gqlPluckFromCodeStringSync(filePath, fs.readFileSync(filePath, 'utf8'))
两个函数在 src/index.ts 中实现,签名完全一致:(filePath: string, code: string, options?: GraphQLTagPluckOptions)。它们都会先调用 validate() 校验 code 必须是字符串、options 必须是对象,然后根据扩展名分派到对应的"预处理器"(Vue/Svelte/Astro/Glimmer),最后统一走 parseCode 提取。
filePath 参数不是摆设——扩展名决定了解析策略。extractExtension 会校验扩展名必须在支持列表内(src/index.ts):
.js .mjs .cjs .jsx .ts .mts .cts .tsx .flow .flow.js .flow.jsx
.vue .svelte .astro .gts .gjs
返回的每个 Source 对象(来自 graphql 包)包含 body(提取出的纯 GraphQL 文本)、name(原文件路径)以及 locationOffset(在源文件中的起始行/列)。位置信息是 7.0.0 版本引入的破坏性变更:返回类型从 string 变成了 graphql-js 的 Source,同时保留了 locationOffset,这样下游的 parse 可以给出准确的报错定位。
三、从 CHANGELOG 看功能演进:一个包的 8.x 成长史
CHANGELOG.md 记录了该包从 6.2.4 到 8.3.39 的完整演进轨迹。与其把它当作流水账,不如从中提炼出"一个代码级 GraphQL 提取器要解决的真实问题"。
3.1 文件类型覆盖的扩张
| 版本 | 变更 | 意义 |
|---|---|---|
| 6.3.0 | 支持 Vue 文件中的 TypeScript(9ee20108) |
Vue SFC 的 <script lang="ts"> 场景 |
| 6.4.0 | Vue 3 支持(76162cc8) |
适配 @vue/compiler-sfc 解析管线 |
| 7.2.1 / 7.2.2 | 增加 Svelte 文件支持(4e6fe1c1 / cdecc1b5) |
通过 svelte2tsx 把 Svelte 转为 TSX 再解析 |
| 7.4.6 | 支持解析 cjs/mjs 文件(PR #5030) | CommonJS/ESM 双模块体系 |
| 8.2.0 | 增加 .astro 文件支持(PR #5781) |
通过 @astrojs/compiler 转换 frontmatter |
| 8.3.3 | 增加 .gts / .gjs 文件支持(PR #6521) |
Ember Glimmer 模板文件,按 TypeScript 语法解析 |
| 8.3.7 | 支持 content-tag v3 并兼容旧版本(PR #6667) | Glimmer 预处理器的版本兼容 |
这些支持在源码中都能找到对应实现:.vue 走 parseWithVue + @vue/compiler-sfc 的 compileScript(src/index.ts),.svelte 走 svelte2tsx(src/index.ts),.astro 走 @astrojs/compiler 的 transform(src/index.ts),.gts/.gjs 走 content-tag 的 Preprocessor(src/index.ts)。
3.2 语法特性的跟进
- 7.5.0(PR #4877):支持 TypeScript 的
as const断言写法,即graphql(query ...as const)。visitor 中通过isTSAsConstExpression判断TSAsExpression且类型引用为const,再解包出内层模板字面量(src/visitor.ts)。 - 7.4.0(PR #4863):支持 import assertions(
assert { type: "json" }),为此引入@babel/plugin-syntax-import-assertions依赖。 - 8.3.37(PR #8370):改用 Babel 的
importAttributes(并开启deprecatedAssertSyntax以兼容旧assert { ... }语法),同时移除了不再需要的@babel/plugin-syntax-import-assertions依赖(对应 src/config.ts 中的配置注释)。测试中专门覆盖了assert与with两种导入属性写法(tests/graphql-tag-pluck.test.ts)。 - 8.3.0(PR #5920):支持 tc39/proposal-explicit-resource-management 的
using关键字,对应 src/config.ts 中的explicitResourceManagement插件。测试样例(tests/graphql-tag-pluck.test.ts)表明包含using managedResource = createManagedResource()的 TS 文件可以被正常 pluck。 - 8.3.2(PR #6407):修复 ESM 构建中
require is not defined的问题,保证 ESM/CJS 双形态都能正确加载框架编译器。
3.3 工程化与 API 打磨
- 7.0.0:破坏性变更——返回
graphql-jsSource而非字符串(保留locationOffset),并保证带 GraphQL 魔法注释的 operation 只被解析一次(去重)。 - 7.3.0:支持 TypeScript module resolution;7.3.2(PR #4624) 修复
moduleResolution: node16/nodenext下的 CJS 类型解析。 - 8.1.0(PR #5643):新增两个扩展钩子
isGqlTemplateLiteral与pluckStringFromFile,把"判定是否 GraphQL"与"如何提取字符串"两个环节开放给用户自定义。 - 8.0.0(PR #5274):移除 Node 14 支持,要求 Node.js
>= 16。 - 6.2.5:导出
parseCode供底层解析使用,并支持跳过缩进处理(skipIndent)。
四、能被识别的模板字面量形态
visitor(src/visitor.ts)一共处理四类 AST 节点:
1. 来自已注册模块的 tagged template(最主流)
import gql from 'graphql-tag'
const query = gql`
query foo { foo { id } }
`
识别链路:ImportDeclaration 命中 → 记录本地标识符名(如 gql)→ TaggedTemplateExpression 校验 tag 名 → 提取 quasi 内容。测试覆盖了别名导入(import { default as foo })、命名导入(import { graphql } from 'gatsby')、CommonJS require('graphql-tag') 以及动态 await import('graphql-tag')(见 tests/graphql-tag-pluck.test.ts)。
2. 函数调用形式 gql(\...`)`
const fragment = gql(`
fragment Foo on FooType { id }
`)
CallExpression 分支会检查 callee 是否为有效标识符、arguments[0] 是否为 TemplateLiteral。
3. 魔法注释 /* GraphQL */
const MessageType = /* GraphQL */ `
enum MessageType { text media draftjs }
`
TemplateLiteral 与 ExpressionStatement 两个分支都会调用 pluckMagicTemplateLiteral,其默认判定逻辑 defaultIsGqlTemplateLiteral 取节点最后一个 leading comment 的文本,与 gqlMagicComment(默认 graphql,不区分大小写)比对(src/visitor.ts)。带尾部分号、带转义反引号、插值内容为注释等边界情况均有测试覆盖。
4. as const 断言
const doc = graphql(`
query foo { foo { id } }
` as const)
值得注意的细节:没有导入任何模块、也没有魔法注释的裸 gql 模板字面量也会被提取。因为 defaults.globalGqlIdentifierName = <a href="https://link.gitcode.com/i/790935366e1254c8b4ca87bfac9db086" target="_blank">'gql', 'graphql']([src/visitor.ts),全局标识符天然包含这两个名字;测试 'should pluck template literals from gql by default even if not imported from graphql-tag' 验证了这一行为。
提取出的内容会经过 addTemplateLiteralToResult 去重(以 end/start/content 为缓存键),避免同一模板被多个 visitor 分支重复收集。
五、完整配置项说明
GraphQLTagPluckOptions(src/index.ts)支持以下全部选项:
5.1 modules:注册来源模块
默认支持超过 25 个包(src/visitor.ts),包括:
graphql-tag、graphql-tag.macro(默认导出)@apollo/client、@apollo/client/core、apollo-angular、apollo-boost(标识符gql)- 一整套
apollo-server系列(express/koa/hapi/fastify/lambda/micro/azure-functions/cloud-functions/cloudflare,标识符gql) gatsby、react-relay、react-relay/hooks、relay-runtime、babel-plugin-relay/macro(标识符graphql)@urql/core、urql、@urql/preact、@urql/svelte、@urql/vue、graphql.macro(标识符gql)
每个条目结构为 { name: string; identifier?: string }。name 是被导入的包名,identifier 是包内导出的命名标识符;不指定 identifier 时匹配默认导入。匹配时统一小写化比较。可传入自定义模块:
gqlPluckFromCodeString(filePath, code, {
modules: [{ name: 'my-graphql-tag' }],
})
对应测试 'should be able to specify the package name of which the GraphQL identifier should be imported from'(tests/graphql-tag-pluck.test.ts)。
5.2 gqlMagicComment:魔法注释锚点
默认 graphql,对应代码中的 /* GraphQL */。设置为其他值时(如 'GQL')即可识别 /* GQL */ 注释,匹配过程不区分大小写(src/visitor.ts)。
5.3 globalGqlIdentifierName:全局标识符
允许把某个名字当作"全局 gql 函数"而无需模块导入,区分大小写,可传字符串或字符串数组:
// `graphql` 是全局函数
export const usersQuery = graphql`
{
users { id name }
}
`
gqlPluckFromCodeString(filePath, code, {
globalGqlIdentifierName: 'anotherGql',
})
测试(tests/graphql-tag-pluck.test.ts)验证了大小写敏感性:anothergql 不会匹配 anotherGql。
5.4 skipIndent:跳过缩进归一化
默认提取时会通过 freeText(src/utils.ts)做缩进归一化:找到非空行的最小缩进作为基准,统一去掉公共缩进,再 trim 并压缩多余空行。这在模板字面量嵌套在不同缩进层级时很有用。设为 true 则保留原文(若 trim 后为空则仍返回空字符串,避免空白结果混入——对应 7.1.4 的修复 "Fix returning whitespace only results if skipIndent is set to true")。
5.5 isGqlTemplateLiteral:自定义判定钩子(8.1.0+)
默认逻辑是"leading comment 文本 === gqlMagicComment"。覆盖它可支持更复杂的判定,例如模板内容以 #graphql 开头:
gqlPluckFromCodeString(filePath, code, {
isGqlTemplateLiteral: node => {
return (
node.type === 'TemplateLiteral' &&
/\s*#graphql\s*\n/i.test(node.quasis[0]?.value?.raw || '')
)
},
})
对应测试(tests/graphql-tag-pluck.test.ts)演示了默认行为会忽略 #graphql 行内注释、自定义后即可识别。
5.6 pluckStringFromFile:自定义提取钩子(8.1.0+)
默认实现(defaultPluckStringFromFile,src/visitor.ts)会:去掉首尾反引号、删除所有 ${...} 插值(因为最终输出是单一字符串)、还原转义反引号 ```、再走缩进处理。自定义钩子可以改变插值处理策略:
gqlPluckFromCodeString(filePath, code, {
pluckStringFromFile: (code, { start, end }) => {
return code
.slice(start! + 1, end! - 1)
// 把 ${foo} 转成 #EXPRESSION:foo 注释而非删除
.replace(/\$\{([^}]*)\}/g, (_, m1) => '#EXPRESSION:' + m1)
.split('\\`')
.join('`')
},
})
测试(tests/graphql-tag-pluck.test.ts)验证了默认"删除插值"与自定义"保留为注释"两种行为。
5.7 gqlVueBlock:自定义 Vue 块
从 Vue 单文件组件的自定义块(如 <graphql lang="gql">)中提取原始 GraphQL(src/index.ts 的 customBlockFromVue)。设置后,该块内容会作为额外的 Source 追加到结果末尾:
gqlPluckFromCodeString(filePath, vueCode, {
gqlVueBlock: 'graphql',
})
对应测试(tests/graphql-tag-pluck.test.ts)中,<script> 内的 gql 模板与 <graphql> 自定义块中的 query 被同时提取。
六、底层原理:Babel 解析 + AST 遍历管线
整个提取流程(gqlPluckFromCodeString → parseCode)只有三步(src/index.ts):
-
parse(code, generateConfig(...)):按文件扩展名组装 Babel parser 插件列表。基础插件包括asyncGenerators、bigInt、classProperties、decorators-legacy、dynamicImport、explicitResourceManagement、optionalChaining、nullishCoalescingOperator、pipelineOperator(smart proposal)等;.ts/.mts/.cts追加typescript+importAttributes,.tsx追加typescript+jsx,.js/.mjs/.cjs/.jsx追加jsx并视代码中是否含@flow头动态追加 flow 插件,.vue/.svelte追加对应语言插件,.gjs按 TypeScript 解析(见 src/config.ts)。sourceType: 'module'、allowUndeclaredExports: true。 -
createVisitor(...):构造包含ImportDeclaration、CallExpression、TaggedTemplateExpression、TemplateLiteral、ExpressionStatement五个分支的 visitor(src/visitor.ts)。 -
traverse(ast, visitor):收集所有命中的PluckedContent(含content、start/end偏移量与loc行列信息),最后由外层包装成graphql的Source。
框架类文件(Vue/Svelte/Astro/Glimmer)则在解析之前先做"脚本抽取":比如 Vue 用 @vue/compiler-sfc 的 compileScript 把 <script>/<script setup> 编译成纯 TS 再交给 Babel;Svelte 用 svelte2tsx 转成 TSX;Astro 用 @astrojs/compiler 的 transform 提取 frontmatter。这些框架编译器是可选依赖——未安装时抛出的错误会给出明确的安装指引(如 npm install @vue/compiler-sfc,见 src/index.ts 中定义、package.json 的 buildOptions.external 中列为外部依赖)。
七、实战集成:与 CodeFileLoader / loadDocuments 联动
graphql-tag-pluck 的价值在生态中体现得最充分:@graphql-tools/load 的 loadDocuments / loadDocumentsSync 在加载 .js/.ts 文件时正是"使用 graphql-tag-pluck 解析"(见 load/src/documents.ts 的注释)。
更直接的集成方式是 @graphql-tools/loaders/code-file 的 CodeFileLoader(loaders/code-file/src/index.ts),它封装了 pluck 并透出两个配置项:
pluckConfig?: GraphQLTagPluckOptions——原样传给gqlPluckFromCodeString;noPluck?: boolean——设为true跳过 pluck,直接尝试以模块形式加载文件。
构造函数的 config 与调用时的 options 会通过 getMergedOptions 合并(pluckConfig 浅合并)。加载流程(异步版见 loaders/code-file/src/index.ts):读取文件内容 → gqlPluckFromCodeString → 若有命中则把每个 Source 的 body 作为 rawSDL、parse(source) 得到 DocumentNode 返回;若 pluck 结果为空再回退到 require/export 加载。FILE_EXTENSIONS 列表与 pluck 包支持列表保持一致(含 .gts/.gjs),保证扩展名覆盖不掉队。
典型用法:
import { loadDocuments } from '@graphql-tools/load'
import { CodeFileLoader } from '@graphql-tools/loaders/code-file'
const documents = await loadDocuments('queries/*.{js,ts}', {
loaders: [new CodeFileLoader()],
// 可选:透传 pluck 配置
pluckConfig: { skipIndent: true },
})
八、使用边界与注意事项
- 扩展名必须受支持:不支持的扩展名会直接抛出
TypeError: Provided file type must be one of ...(src/index.ts)。 - Vue/Svelte/Astro/Glimmer 需要额外依赖:
@vue/compiler-sfc、svelte2tsx(+svelte)、@astrojs/compiler(同步场景用astrojs-compiler-sync)、content-tag、typescript(Vue 场景)均为可选依赖,缺失时抛出的错误信息自带 npm/yarn 安装命令。这是设计使然:package.json的buildOptions.external明确把这些包排除在 bundle 之外,避免普通 JS/TS 用户背负多余体积。 - 结果可能为空数组:没有命中任何规则时返回
[],而非报错——例如一个不含任何 gql 调用的纯 JS 文件。 gql全局标识符默认启用:未导入任何模块时gql/graphql标识符的模板字面量也会被提取,若希望更严格可自定义globalGqlIdentifierName覆盖默认值。- 缩进与插值处理:默认
freeText会归一化缩进并删除${...}插值;需要保留原文时用skipIndent,需要定制插值策略时用pluckStringFromFile钩子。 - Node 版本:
8.0.0起要求 Node.js>= 16(package.json 中engines字段)。
九、延伸阅读
- 官网使用指南:website/src/content/graphql-tag-pluck.mdx
- 核心实现:src/index.ts、src/visitor.ts、src/config.ts、src/utils.ts
- 完整测试集(2853 行,覆盖全部形态与框架):tests/graphql-tag-pluck.test.ts
- 包元信息与依赖版本:package.json
- 生态集成:loaders/code-file/src/index.ts、load/src/documents.ts
- 版本演进记录:CHANGELOG.md