@graphql-tools/graphql-tag-pluck 从代码文件中提取 GraphQL 定义:功能演进、配置选项与源码原理全解析

原创2026-10-12 23:09:561,697 阅读
文章标签:后端GraphQLAPI设计开发工具

@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-js Source 而非字符串(保留 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):

  1. 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。

  2. createVisitor(...):构造包含 ImportDeclaration、CallExpression、TaggedTemplateExpression、TemplateLiteral、ExpressionStatement 五个分支的 visitor(src/visitor.ts)。

  3. 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 字段)。

九、延伸阅读

登录后查看全文
graphql-tools