GraphQL Code Generator 中处理外部片段导入的技术解析

背景介绍

GraphQL Code Generator 是一个强大的工具，用于从 GraphQL 模式自动生成类型安全的代码。在实际开发中，我们经常需要在不同的 GraphQL 操作之间共享片段(fragment)，这通常通过 #import 语法实现。然而，当使用 near-operation-file 预设时，默认情况下不会在生成的输出中包含这些外部片段。

问题本质

在迁移自 Apollo Codegen 的项目中，开发者发现 GraphQL Code Generator 对于外部片段导入的处理方式有所不同。具体表现为：

1. 当片段定义在同一个文件中时，会生成独立的片段类型
2. 当片段通过 #import 导入时，不会生成独立的片段类型，而是直接将片段内容内联到操作类型中

这种不一致性可能导致以下问题：

• 迁移成本增加：需要修改大量现有代码中对片段类型的引用
• 开发体验不一致：开发者需要记住片段定义位置会影响生成结果
• 类型复用困难：无法直接引用导入的片段类型

技术解决方案

1. 现有行为分析

默认情况下，GraphQL Code Generator 会：

• 解析所有片段（包括导入的）
• 将片段内容扁平化到操作类型中
• 不生成独立的片段类型定义

2. 解决方案探索

为了支持生成外部片段的独立类型，可以考虑以下方法：

方法一：修改 ClientSideBaseVisitor

最初的解决方案尝试通过修改 ClientSideBaseVisitor 来忽略跳过外部片段的逻辑。这可以通过添加一个配置选项 includeExternalFragments 来实现。

方法二：使用 extractAllFieldsToTypes 选项

该选项会为所有字段生成独立类型，但会产生过多不必要的类型定义，不够精确。

方法三：自定义插件

通过编写自定义插件，可以：

1. 获取外部片段的 AST
2. 使用 TypeScriptDocumentsVisitor 单独处理这些片段
3. 将结果合并到最终输出中

实际应用建议

对于需要此功能的项目，推荐以下实践：

1. 评估必要性：首先确认是否真的需要独立片段类型，扁平化处理在大多数情况下已经足够

2. 渐进式迁移：

   • 可以先使用自定义插件方案
   • 逐步重构代码以适配标准行为
   • 最后移除自定义逻辑

3. 统一代码风格：

   • 要么全部使用内联片段
   • 要么全部使用独立片段类型
   • 避免混合使用两种风格

技术实现细节

深入理解这个问题需要了解 GraphQL Code Generator 的几个关键组件：

1. 文档处理流程：

   • 解析 GraphQL 文档
   • 收集所有片段定义（包括导入的）
   • 构建完整的操作文档

2. 类型生成策略：

   • 对于本地片段：生成独立类型
   • 对于外部片段：默认内联处理

3. 访问者模式应用：

   • ClientSideBaseVisitor：基础访问者实现
   • TypeScriptDocumentsVisitor：特定于 TypeScript 的实现

总结

GraphQL Code Generator 对外部片段的处理体现了框架在灵活性和一致性之间的权衡。虽然默认行为可能不符合所有项目的需求，但通过合理的配置和自定义插件，开发者可以实现所需的代码生成策略。理解这些底层机制有助于更好地利用 GraphQL 生态系统的强大功能，构建更健壮的类型安全应用。