查询根类型命名不一致时，如何搭配使用graphql-codegen与Hasura？

Hasura默认输出的GraphQL Schema会将所有查询操作归集在query_root类型下，而graphql-codegen默认要求查询根类型命名为Query，二者命名规则不匹配会直接导致代码生成流程失败，可通过以下三类成熟方案完成适配衔接：

• 方案1：在graphql-codegen配置中显式指定自定义根类型名称
  这是最轻量化的适配方式，无需修改原始Schema内容，只需在codegen的配置文件中告知工具需要识别的根类型实际名称，即可绕过默认的硬编码名称匹配逻辑。针对Hasura的内置命名规则，可直接配置映射关系，示例配置片段：

  generates:
    ./src/generated/graphql.ts:
      plugins:
        - typescript
        - typescript-operations
      config:
        # 匹配Hasura的三类根类型默认命名
        customQueryRootType: "query_root"
        customMutationRootType: "mutation_root"
        customSubscriptionRootType: "subscription_root"
  

• 方案2：使用graphql-codegen内置的类型重命名转换能力
  新版graphql-codegen提供了Schema加载阶段的内置转换器，可在拉取Hasura Schema的过程中自动完成类型名映射，将query_root重命名为工具默认识别的Query类型，无需编写额外的预处理脚本。示例配置片段：

  schema:
    - http://<your-hasura-service-endpoint>/v1/graphql:
        headers:
          x-hasura-admin-secret: "<your-project-admin-secret>"
  generates:
    ./src/generated/graphql.ts:
      plugins:
        - typescript
      transforms:
        - rename:
            - from: "query_root"
              to: "Query"
            - from: "mutation_root"
              to: "Mutation"
            - from: "subscription_root"
              to: "Subscription"
  

• 方案3：对拉取的Schema做轻量预处理改写
  适用于使用旧版graphql-codegen、不支持上述自定义配置或内置转换能力的场景，可在代码生成流程启动前，通过简单的文本替换或AST解析，将Hasura输出Schema里的type query_root定义重命名为type Query，同步调整Schema定义块的根操作映射关系，让最终加载给graphql-codegen的Schema完全符合默认命名规则。这种方式兼容性最强，可适配所有版本的代码生成工具。

注意：不建议通过修改Hasura服务端的元数据配置，强制将query_root重命名为Query，这类修改在Hasura版本升级、元数据重置后很容易丢失，反而增加维护成本；所有在代码生成客户端侧做的适配，都不会改动服务端实际运行的Schema逻辑，仅影响本地代码生成流程，稳定性更强。

内容的提问来源于stack exchange，提问作者Carl Patenaude Poulin