GraphQL Code Generator 中处理顶层 await 的解决方案

问题背景

在 Node.js 开发中，GraphQL Code Generator 是一个强大的工具，用于自动生成 TypeScript 类型定义和客户端代码。然而，当开发者尝试在配置文件中使用顶层 await 时，可能会遇到语法错误。

错误现象

当在 GraphQL Code Generator 的配置文件中直接使用顶层 await 时，系统会抛出错误：

SyntaxError: await is only valid in async functions and the top level bodies of modules

技术分析

这个问题的根源在于 Node.js 对顶层 await 的支持方式。虽然现代 Node.js 版本（v14.8.0+）支持顶层 await，但需要满足以下条件之一：

1. 文件必须是 ES 模块（使用 .mjs 扩展名或在 package.json 中设置 "type": "module"）
2. 或者将 await 包装在 async 函数中

解决方案

方案一：使用异步自执行函数

将代码包装在异步自执行函数中是最直接的解决方案：

(async () => {
  const config = {
    // 配置项
  };
  
  await generate(config);
})();

方案二：使用现代工具链（推荐）

对于使用 Node.js 20+ 的项目，可以采用更现代的解决方案：

1. 创建独立的 codegen.ts 文件：

import { printSchema } from 'graphql';
import type { CodegenConfig } from '@graphql-codegen/cli';
import { generate } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  // 配置项
};

await generate(config);
process.exit(0);

2. 在 package.json 中配置脚本：

{
  "scripts": {
    "codegen": "tsx --env-file=.env src/schema/codegen.ts"
  }
}

技术要点

1. tsx 工具：这是一个 TypeScript 执行器，支持顶层 await 和 ES 模块语法
2. 环境变量处理：Node.js 20+ 原生支持 .env 文件，无需额外依赖
3. 模块系统：确保项目配置支持 ES 模块语法

最佳实践建议

1. 对于新项目，推荐使用 Node.js 20+ 和方案二
2. 对于现有项目，如果升级 Node.js 版本困难，可采用方案一
3. 始终在 CI/CD 流程中验证代码生成是否成功
4. 考虑将生成的代码纳入版本控制，避免因环境问题导致构建失败

总结

处理 GraphQL Code Generator 中的顶层 await 问题，关键在于理解 Node.js 的模块系统和异步处理机制。通过选择合适的工具链和编码方式，可以优雅地解决这一问题，同时保持代码的清晰和可维护性。