@graphql-codegen/core 6.x 变更全解：从核心编排到 DocumentTransform 与 Federation 支持

开发工具【免费下载链接】graphql-code-generatorA tool for generating code based on a GraphQL schema and GraphQL operations (query/mutation/subscription), with flexible support for custom plugins.项目地址https://gitcode.com/gh_mirrors/gr/graphql-code-generator点击查看免费下载导读graphql-codegen/core是 graphql-code-generator 的核心编排引擎负责将 schema、documents、plugins、presets 组装成一次完整的代码生成流水线。本文以 packages/graphql-codegen-core/CHANGELOG.md 为主线梳理从 1.17 到 6.2.0 的演进脉络重点讲解DocumentTransform 文档变换机制、disableFederationDirectiveAndScalarInjection配置、skipDocumentsValidation验证控制、Node 版本支持策略、ESM/TypeScript 兼容性等核心变更。读完本文你将掌握 core 包的关键配置项语义、它的内部执行流水线以及如何在codegen.ts中落地这些能力。一、core 包在架构中的定位graphql-codegen/core不直接参与 CLI 交互而是提供程序化调用入口。从 packages/graphql-codegen-core/src/index.ts 可以看到它只导出两个东西export { codegen } from ./codegen.js; export { executePlugin, ExecutePluginOptions } from ./execute-plugin.js;codegen(options: Types.GenerateOptions): Promisestring—— 一次完整的代码生成流水线输入 schema documents plugins输出拼接好的代码字符串executePlugin(...)—— 单个插件的执行器负责校验插件格式、调用plugin.validate与plugin.plugin。它的依赖见 packages/graphql-codegen-core/package.json运行时依赖graphql-codegen/plugin-helpers类型与工具函数、graphql-tools/schemaschema 合并、graphql-tools/utils文档校验并以graphql为 peerDependency。这正是 6.2.0 中依赖更新的落点。一句话理解CLI 负责读配置、加载插件/预设core 负责把一切编排成字符串输出。二、最新版本6.x核心变更2.1 6.2.0依赖升级与 GraphQL 17 支持依赖graphql-tools/utils从^11.0.0升到^11.2.0peerDependencies 中的graphql范围扩展为^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0新增 GraphQL 17 支持同时联动更新graphql-codegen/plugin-helpers7.1.0。从 packages/graphql-codegen-core/package.json 的exports字段可以看到该包同时提供 CJSrequire→dist/cjs/index.js与 ESMimport→dist/esm/index.js双入口这与 2.1.0 引入的 ESM 支持一脉相承。2.2 6.1.0新增disableFederationDirectiveAndScalarInjectionFederation v2 友好这是 6.1.0 唯一的功能变更新增disableFederationDirectiveAndScalarInjection配置用于更好地支持 Federation v2。其底层行为在 packages/graphql-codegen-core/src/codegen.ts 中清晰可见const federationInConfig: boolean pickFlag(federation, options.config); const disableFederationDirectiveAndScalarInjection: boolean pickFlag( disableFederationDirectiveAndScalarInjection, options.config, ); const isFederation prioritize(federationInConfig, false); if ( isFederation !disableFederationDirectiveAndScalarInjection !hasFederationSpec(options.schemaAst || options.schema) ) { additionalTypeDefs.push(federationSpec); }含义拆解当federation: true且 schema 中尚未包含 Federation 指令key、requires、provides、external判断逻辑见 packages/graphql-codegen-core/src/utils.ts时core 会自动注入 legacy Federation v1 的指令与标量定义如key、external、_FieldSet在 Federation v2 场景下这些 v1 指令可能与子图 schema 冲突或造成冗余注入因此将disableFederationDirectiveAndScalarInjection: true可显式关闭自动注入。用法示例codegen.tsimport type { CodegenConfig } from graphql-codegen/cli; const config: CodegenConfig { schema: ./schema.graphql, generates: { ./src/types.ts: { plugins: [typescript, typescript-operations], config: { federation: true, disableFederationDirectiveAndScalarInjection: true, // 关闭 v1 指令自动注入 }, }, }, }; export default config;2.3 6.0.0移除 Node 20 支持6.0.0 的破坏性变更只有一条Drop Node 20 support并同步升级graphql-codegen/plugin-helpers7.0.0。这与 5.0.0Drop Node 18、4.0.0要求 Node ≥ 16、移除 Node 14、3.0.0移除 Node 12、2.0.0移除 Node 10一脉相承——core 包持续跟进 LTS 策略具体以 packages/graphql-codegen-core/package.json 中engines: { node: 16 }为准。需要说明该文档记录的 Node 支持策略为逐步放弃旧版本、跟随当时活跃 LTS。以 6.0.0 的措辞为准使用前应检查你的 Node 版本与所选版本是否匹配。三、3.1.0DocumentTransform —— 插件执行前的文档变换管道3.1.0 是 3.x 中最重要的功能里程碑引入 DocumentTransform允许在插件处理 documents 之前对 GraphQL 文档进行修改。3.1 工作原理执行时机与调用链可以精确对应到源码在 packages/graphql-codegen-core/src/codegen.tscore 读取options.documentTransforms并调用transformDocumentspackages/graphql-codegen-core/src/transform-document.ts 按顺序逐个执行 transform每个 transform 接收{ documents, schema, config, pluginContext }返回修改后的DocumentFile[]变换后的 documents 才会进入文档校验validate与各插件执行阶段。transform 函数签名定义在 packages/utils/plugins-helpers/src/types.tsexport type DocumentTransformFunctionConfig object (options: { documents: Types.DocumentFile[]; schema: DocumentNode; config: Config; pluginContext?: { [key: string]: any }; }) Types.PromisableTypes.DocumentFile[]; export type DocumentTransformObjectT object { transform: DocumentTransformFunctionT; };3.2 在codegen.ts中使用内联 transformimport type { CodegenConfig } from graphql-codegen/cli const config: CodegenConfig { schema: https://localhost:4000/graphql, documents: [src/**/*.tsx], generates: { ./src/gql/: { preset: client, documentTransforms: [ { transform: ({ documents }) { // Make some changes to the documents return documents } } ] } } } export default config3.3 实战用visit删除自定义指令例如移除localOnlyDirective该指令仅存在于本地文档、不应出现在 schema 定义中import type { CodegenConfig } from graphql-codegen/cli import { visit } from graphql const config: CodegenConfig { schema: https://localhost:4000/graphql, documents: [src/**/*.tsx], generates: { ./src/gql/: { preset: client, documentTransforms: [ { transform: ({ documents }) { return documents.map(documentFile { documentFile.document visit(documentFile.document, { Directive: { leave(node) { if (node.name.value localOnlyDirective) return null } } }) return documentFile }) } } ] } } } export default config3.4 用文件方式声明 transform将变换逻辑独立成模块通过文件名引用// my-document-transform.js module.exports { transform: ({ documents }) { // Make some changes to the documents return documents } }import type { CodegenConfig } from graphql-codegen/cli const config: CodegenConfig { schema: https://localhost:4000/graphql, documents: [src/**/*.tsx], generates: { ./src/gql/: { preset: client, documentTransforms: [./my-document-transform.js] } } } export default configCLI 侧的文件加载逻辑见 packages/graphql-codegen-cli/src/documentTransforms.ts它会按graphql-codegen/name、graphql-codegen/name-document-transform、name、当前工作目录解析路径的顺序尝试加载并给出清晰的可安装包提示。此外还支持带配置的 transform{ [transformName]: config }形式见同文件isTransformFileConfig分支配置会与顶层options.config合并后传给 transform见 packages/graphql-codegen-core/src/transform-document.ts。一个典型用途把client/rest等客户端专用指令在生成前剥离或统一注入/改写 fragments。四、2.x 时代沉淀的关键能力2.x 的多次 Minor 变更奠定了当前 core 的能力基座很多能力至今仍在使用。4.1skipDocumentsValidation2.2.02.2.0 引入用skipDocumentsValidation跳过某些指定校验规则的能力。其语义在 packages/graphql-codegen-core/src/utils.ts 中有完整实现分为三个维度取值效果true跳过全部文档校验重复校验 对 schema 校验{ skipDuplicateValidation: true }仅跳过重复定义校验{ skipValidationAgainstSchema: true }仅跳过对 schema 的校验{ ignoreRules: [...] }保留校验但忽略指定的 GraphQL 规则ignoreRules的实际作用见 packages/graphql-codegen-core/src/codegen.ts默认忽略NoUnusedFragments、NoUnusedVariables、KnownDirectives三条规则ignoreRules追加进忽略列表后再执行validateGraphQlDocuments。当同时提供 schema hash 与options.cache时校验结果会按[schemaHash, ...documentHashes, fragments]组成的 key 缓存避免重复校验同文件cacheKey逻辑这也是 2.5.1 Cache validation of documents 的延续。配置示例const config: CodegenConfig { schema: ./schema.graphql, documents: [./src/**/*.graphql], skipDocumentsValidation: { ignoreRules: [NoUnusedFragments], }, generates: { ./src/types.ts: { plugins: [typescript] } }, };4.2 重复定义检测2.6.6 修复2.6.6 修复了 fragment/operation 命名冲突的校验问题。检测逻辑在 packages/graphql-codegen-core/src/codegen.tscore 会遍历所有文档文件按kind name建立映射比对打印后的定义内容若同名定义内容不同则抛出异常并列出所有涉及的文件路径帮助快速定位重复定义来源。4.3 GraphQL 16 兼容2.3.0 / 2.4.02.3.0 添加 GraphQL v16 兼容2.4.0 将其正式纳入 peerDependenciesgraphql16随后逐步扩展至 176.2.0。4.4 ESM 支持与 TypeScript 解析修复2.1.0支持 ESM2.6.0支持 TypeScript ESM 模块module: node16moduleResolution: node162.6.1修复 CommonJS TypeScript 在node16/nodenext解析下的类型加载问题。这些在 package.json 的exports双入口CJS/ESM 各带独立.d.ts/.d.cts类型中得到了最终形态。4.5 性能 Profiler2.5.02.5.0 引入性能 Profiler--profile。在 packages/graphql-codegen-core/src/codegen.ts 中profiler.run(...)包裹了validateDuplicateDocuments、Create schema instance、Validate documents against schema、每个插件的Plugin name execution等关键步骤可将各阶段耗时输出用于定位生成瓶颈。4.6 prepend 排序1.17.81.17.8 过滤并排序插件返回的prepend/append内容避免多余空行。排序规则见 packages/graphql-codegen-core/src/codegen.ts注释/*、//、*、*/、*/→package→import→ 其他保证头部注释与 import 顺序稳定对应测试见 packages/graphql-codegen-core/tests/prepend.spec.ts。五、core 的完整执行流水线综合 6.x 源码一次codegen()调用的完整顺序为对应 packages/graphql-codegen-core/src/codegen.ts重复文档校验有 documents 且未跳过时执行validateDuplicateDocuments收集插件附加 schema调用每个插件的addToSchema得到additionalTypeDefsFederation 注入federation: true且未禁用注入、schema 无 Federation 指令时注入federationSpecv1 指令/标量合并 schema无schemaAst或有附加定义时用mergeSchemas合并否则直接使用schemaAst执行 DocumentTransform按顺序变换 documents对 schema 校验 documents按skipDocumentsValidation控制支持缓存执行每个插件依次调用executePlugin收集字符串输出或{ prepend, append, content }复合输出拼装最终结果prepend排序后 各插件内容 append过滤空值后以换行拼接。这条流水线同时解释了graphql-codegen/plugin-helpers中Types.GenerateOptions含documents、schema、schemaAst、config、plugins、pluginMap、documentTransforms、skipDocumentsValidation、cache、profiler等字段的职责分配。六、升级与使用建议Node 版本以你选用的 core 版本的engines与破坏性变更说明为准升级 major 版本前先核对 Node 版本当前仓库 packages/graphql-codegen-core/package.json 声明16而 6.0.0 起不再支持 Node 20 之前的旧 LTS实际请按发行说明判断Federation 用户使用 Federation v2 子图时建议显式设置disableFederationDirectiveAndScalarInjection: true避免 v1 指令被自动注入文档校验瓶颈大批量文档时可用skipDocumentsValidation: { ignoreRules: [...] }精确豁免规则而非全量关闭需要预处理文档优先使用documentTransforms内联函数或独立文件均可它发生在校验与插件执行之前是先改写、再生成的标准入口程序化集成如需在自有构建脚本中调用直接使用codegen(options)与executePlugin这两个公开 API。参考文件索引变更记录主体packages/graphql-codegen-core/CHANGELOG.md核心流水线实现packages/graphql-codegen-core/src/codegen.tsDocumentTransform 执行器packages/graphql-codegen-core/src/transform-document.ts插件执行器packages/graphql-codegen-core/src/execute-plugin.ts校验/Federation 工具函数packages/graphql-codegen-core/src/utils.tsCLI 侧 transform 加载packages/graphql-codegen-cli/src/documentTransforms.ts类型定义packages/utils/plugins-helpers/src/types.ts测试示例packages/graphql-codegen-core/tests/prepend.spec.ts赞分享开发工具【免费下载链接】graphql-code-generatorA tool for generating code based on a GraphQL schema and GraphQL operations (query/mutation/subscription), with flexible support for custom plugins.项目地址https://gitcode.com/gh_mirrors/gr/graphql-code-generator点击查看免费下载相关推荐MarkText muya 编辑器核心版本演进从 muyajs/core 0.0.x 到 0.2.0 的变更全解与源码实证MarkText muya 编辑器核心版本演进从 muyajs/core 0.0.x 到 0.2.0 的变更全解与源码实证 本文以 packages/muy桌面应用富文本graphql-codegen/typescript-resolvers 演进全解从配置项变革到 Federation 与 Scalar 类型系统的实战指南graphql codegen/typescript resolvers 演进全解从配置项变革到 Federation 与 Scalar 类型系统的实战指南开发工具OpenVINO:开源AI推理优化与部署工具,PyTorch与ONNX模型本地高效运行指南OpenVINO:开源AI推理优化与部署工具,PyTorch与ONNX模型本地高效运行指南 OpenVINO™ 是一个用于优化和部署AI推理的开源工具包:它把用人工智能推理引擎深度学习本地部署模型优化模型量化上一篇VMMRdb车辆识别数据集教程下一篇Chalk源码架构解析理解符号和样式生成机制的技术深度创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考