GraphQL Code Generator 中 verbatimModuleSyntax 的兼容性问题解析

问题背景

在使用 GraphQL Code Generator 的 client-preset 预设时，当 TypeScript 配置中启用了 verbatimModuleSyntax 选项时，会遇到类型导入相关的编译错误。这个选项是 TypeScript 4.5 引入的严格模式特性，它要求类型必须显式地使用 import type 语法导入。

问题现象

在构建过程中，TypeScript 编译器会报出类似以下的错误：

TS1484: 'ResultOf' 是一个类型，当启用 'verbatimModuleSyntax' 时，必须使用类型专用导入

这些错误出现在 GraphQL Code Generator 自动生成的文件中，特别是 fragment-masking.ts、gql.ts 和 graphql.ts 等文件。问题根源在于生成的代码使用了常规的 import 语句来导入纯类型，而没有使用 import type。

技术分析

verbatimModuleSyntax 是 TypeScript 的一项严格模式特性，它的设计目的是：

1. 明确区分运行时依赖和类型依赖
2. 避免 JavaScript 运行时导入不必要的模块
3. 提高代码的清晰度和可维护性

当启用此选项时，所有类型导入必须显式使用 import type 语法，否则 TypeScript 编译器会报错。

解决方案

GraphQL Code Generator 提供了 useTypeImports 配置选项来解决这个问题。在配置文件中添加以下设置：

{
  "generates": {
    // 其他配置...
    "config": {
      "useTypeImports": true
    }
  }
}

这个配置会指示代码生成器在输出文件中使用 import type 语法来导入纯类型，从而兼容 verbatimModuleSyntax 的严格模式要求。

最佳实践

对于使用 TypeScript 严格模式的项目，建议：

1. 始终启用 useTypeImports 选项
2. 在团队中统一 TypeScript 配置，避免混合使用不同的模块语法
3. 定期检查生成的代码是否符合项目类型检查标准
4. 考虑在 CI/CD 流程中加入对生成代码的类型检查

总结

GraphQL Code Generator 作为强大的 GraphQL 类型安全工具，提供了灵活的配置选项来适应不同的 TypeScript 严格模式要求。通过合理配置 useTypeImports，开发者可以无缝地在严格类型检查环境下使用 client-preset 等预设功能，同时保持代码的类型安全和运行时效率。