GraphQL Code Generator 中模块导入路径问题的解决方案

在 TypeScript 项目中，当使用 GraphQL Code Generator 生成代码时，开发者可能会遇到一个常见但容易被忽视的问题：生成的代码中模块导入语句缺少文件扩展名。这个问题看似简单，却可能导致 Node.js 模块系统无法正确解析路径。

问题现象

当配置 GraphQL Code Generator 生成 TypeScript 类型定义和解析器时，生成的代码中会出现类似以下的导入语句：

import { GraphQLContext } from '../context/GraphQLContext';

这种写法在 Node.js 的 ESM 模块系统中是不规范的，因为 Node.js 要求显式指定文件扩展名（如 .ts 或 .js）。缺少扩展名会导致模块加载失败。

问题根源

这个问题源于 GraphQL Code Generator 的默认行为，它在生成导入路径时不会自动添加文件扩展名。这与 TypeScript 编译器的行为不同，TypeScript 在编译阶段可以处理无扩展名的导入，但运行时需要明确的扩展名。

解决方案

解决这个问题的方法很简单：在配置文件中显式指定完整的文件路径，包括扩展名。具体来说，在 contextType 配置中：

修改前：

typesPluginsConfig: {
  contextType: "../context/GraphQLContext#GraphQLContext",
},

修改后：

typesPluginsConfig: {
  contextType: "../context/GraphQLContext.ts#GraphQLContext",
},

技术背景

1. Node.js 模块解析规则：Node.js 对于 ESM 模块要求显式文件扩展名，这是与 CommonJS 模块系统的一个重要区别。

2. TypeScript 编译行为：TypeScript 编译器在编译阶段会处理无扩展名的导入，但生成的 JavaScript 代码需要符合目标运行时的模块解析规则。

3. 代码生成器设计：GraphQL Code Generator 作为通用工具，默认不添加特定扩展名以保持灵活性，但这也意味着开发者需要根据项目需求进行适当配置。

最佳实践

1. 统一文件扩展名：在项目中统一使用 .ts 或 .js 扩展名，避免混用。

2. 配置检查：在使用代码生成工具时，仔细检查生成的导入语句是否符合项目配置。

3. 构建工具适配：如果项目使用 webpack 等构建工具，可能需要额外配置以支持无扩展名导入。

总结

虽然这个问题看似简单，但它体现了 TypeScript 开发中模块系统配置的重要性。通过显式指定文件扩展名，可以确保生成的代码在各种环境下都能正确运行。这也提醒我们，在使用代码生成工具时，需要了解其默认行为并根据项目需求进行适当调整。