GraphQL Yoga 项目中使用 GraphQL Code Generator 实现类型安全

GraphQL Code Generator 是一个强大的工具，能够根据 GraphQL 模式自动生成 TypeScript 类型定义和解析器文件。本文将详细介绍如何在 GraphQL Yoga 项目中配置和使用 GraphQL Code Generator，以实现类型安全和减少运行时错误。

为什么需要 GraphQL Code Generator

在 GraphQL 开发中，手动维护类型定义和解析器之间的对应关系既繁琐又容易出错。GraphQL Code Generator 可以：

1. 自动生成 TypeScript 类型定义
2. 确保解析器与模式定义严格匹配
3. 提供更好的开发体验和代码提示
4. 减少运行时类型错误

安装必要依赖

首先需要安装两个核心包：

npm install -D --save-exact @graphql-codegen/cli@5.0.3 @eddeee888/gcg-typescript-resolver-files@0.11.0

• @graphql-codegen/cli 是 GraphQL Code Generator 的核心命令行工具
• @eddeee888/gcg-typescript-resolver-files 是专为 GraphQL 服务器设计的预设

项目结构调整

为了保持项目可维护性，建议将模式定义和解析器分离到不同文件中。创建以下目录结构：

src/
  schema/
    base/
      schema.graphql
      schema.mappers.ts

将 GraphQL 模式定义移动到 schema.graphql 文件中，包含所有类型定义。

配置 Code Generator

在项目根目录创建 codegen.ts 配置文件：

import { defineConfig } from '@eddeee888/gcg-typescript-resolver-files'
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'src/schema/**/schema.graphql',
  generates: {
    'src/schema': defineConfig({
      resolverGeneration: 'minimal',
      typesPluginsConfig: {
        contextType: '../context#GraphQLContext'
      }
    })
  }
}

export default config

配置说明：

• schema 指定模式定义文件位置
• generates 定义生成文件的输出目录
• resolverGeneration: 'minimal' 只生成根级解析器
• contextType 指定上下文类型位置

生成代码

运行以下命令生成代码：

npx graphql-codegen

生成的文件包括：

• 根级解析器文件（Query/Mutation）
• 解析器映射文件
• 合并后的模式定义
• 类型定义文件
• 生成的类型文件

迁移现有逻辑

根级解析器迁移

将现有解析器逻辑迁移到生成的解析器文件中。例如 feed 解析器：

export const feed: NonNullable<QueryResolvers['feed']> = async (_parent, args, context) => {
  const where = args.filterNeedle
    ? {
        OR: [
          { description: { contains: args.filterNeedle } },
          { url: { contains: args.filterNeedle } }
        ]
      }
    : {}

  const take = applyTakeConstraints({
    min: 1,
    max: 50,
    value: args.take ?? 30
  })

  return context.prisma.link.findMany({
    where,
    skip: args.skip,
    take
  })
}

使用映射器

映射器(Mappers)允许你指定 GraphQL 类型与底层数据模型之间的对应关系。例如，为 Link 类型创建映射器：

import type { Link } from '@prisma/client'

export type LinkMapper = Link

创建映射器后，Code Generator 会自动：

• 为所有 Link 解析器生成正确的父类型
• 创建 Link 解析器文件
• 执行静态分析确保类型安全

自定义对象类型解析器

要自定义对象类型解析器，只需创建空文件然后运行 Code Generator。例如创建 Comment 解析器：

import type { CommentResolvers } from './../../types.generated'

export const Comment: CommentResolvers = {
  /* 实现 Comment 解析器逻辑 */
}

使用生成的解析器和类型定义

最后，在服务器配置中使用生成的解析器和类型定义：

import { createSchema } from 'graphql-yoga'
import { resolvers } from './schema/resolvers.generated'
import { typeDefs } from './schema/typeDefs.generated'

export const schema = createSchema({
  resolvers: [resolvers],
  typeDefs: [typeDefs]
})

维护生成的文件

建议：

• 不要手动修改 .generated. 文件
• 将这些文件添加到 .gitignore
• 在开发工具中忽略这些文件

总结

通过 GraphQL Code Generator 和 Server Preset，你可以：

1. 自动获得类型安全的解析器
2. 减少手动类型定义工作
3. 提高代码质量和开发效率
4. 更容易扩展和维护大型 GraphQL 服务器

这种设置特别适合中大型项目，能够显著提升开发体验和代码质量。