在现代 Web 开发中，GraphQL 以其强大的数据查询能力和灵活的数据结构定义，日益受到开发者的青睐。GraphQL 强大的类型系统是其核心优势之一，它保证了数据的一致性和可靠性。然而，当项目规模增大，GraphQL Schema 变得复杂时，手动维护类型定义会变得非常繁琐且容易出错。幸运的是，我们可以借助 GraphQL 代码生成器来自动化这个过程，极大地提升开发效率。 本文将深入探讨 GraphQL 代码生成器的概念、优势和使用方法，并以 @graphql-codegen/cli 为例，详细介绍如何配置和使用代码生成器，以及如何将其集成到现有的 TypeScript 项目中，让你告别手动维护类型的烦恼，专注于业务逻辑的开发。通过本文，你将掌握一种更高效、更可靠的 GraphQL 开发方式，显著提升开发效率和代码质量。
核心要点
GraphQL 的类型系统是其核心优势，但手动维护类型定义非常繁琐。
GraphQL 代码生成器可以自动化生成类型定义，提高开发效率。
@graphql-codegen/cli 是一个常用的 GraphQL 代码生成器。
通过配置 CodegenConfig，可以指定 Schema 路径、Document 路径和使用的插件。
Code generation 还可以生成与 GraphQL Request 兼容的类型
Code generation 可以配合watch命令进行实时更新。
Code generation 可以避免 API 变更导致的类型不一致问题。
GraphQL 代码生成器可以与多种前端框架和后端语言集成。
GraphQL 代码生成器：自动化类型生成的利器
什么是 GraphQL 代码生成器？
graphql 代码生成器是一种自动化工具，它可以根据 graphql schema 和 query/mutation 文档，自动生成各种类型的代码，包括 typescript 类型定义、react hooks、angular service 等。通过代码生成器，开发者可以避免手动编写大量重复的代码，减少出错的可能性，并保持代码的一致性和可维护性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
GraphQL 的类型系统是 GraphQL 的一大亮点，它通过 Schema 定义了数据的结构和类型，保证了客户端和服务端之间数据交互的准确性和一致性。然而，手动维护这些类型定义是一项繁琐的任务，尤其是在大型项目中，Schema 经常变化，手动更新类型定义很容易出错。
代码生成器的作用在于，它可以根据 Schema 自动生成类型定义，从而避免了手动维护的麻烦。当 Schema 发生变化时，只需要重新运行代码生成器，就可以自动更新类型定义，保证了类型定义与 Schema 的同步。这大大提高了开发效率，并减少了出错的可能性。
为什么需要 GraphQL 代码生成器？
GraphQL 代码生成器能够有效解决以下问题：
- 告别手动类型定义： 减少手动编写类型定义的工作量，避免出错。
- 保持类型同步： 自动同步 Schema 和类型定义，减少维护成本。
- 提高开发效率： 将更多精力集中在业务逻辑的开发上，提升开发效率。
- 保障代码质量： 生成高质量、一致性的代码，减少 Bug 产生的可能性。
-
类型安全：提供类型安全，使得在编译阶段就能发现错误，减少运行时错误。
想象一下，你正在开发一个大型电商网站，网站的数据来源是 GraphQL API。API 的 Schema 非常复杂，包含了大量的类型定义。如果没有代码生成器，你就需要手动编写这些类型定义，这是一项非常繁琐的任务。而且，API 的 Schema 经常会发生变化，比如添加新的字段、修改字段的类型等。每次 Schema 发生变化，你都需要手动更新类型定义，否则就会导致类型不匹配的错误。有了 GraphQL 代码生成器，你就可以避免这些麻烦。你只需要配置好代码生成器，让它自动根据 Schema 生成类型定义。当 Schema 发生变化时，你只需要重新运行代码生成器，就可以自动更新类型定义，保证了类型定义与 Schema 的同步。
使用 @graphql-codegen/cli 自动化生成类型定义
安装 @graphql-codegen/cli
首先，我们需要安装 @graphql-codegen/cli，它可以帮助我们方便地运行代码生成器。
你可以使用 npm 或 yarn 来安装：
npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/client-preset
或者：
yarn add -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/client-preset
除了 @graphql-codegen/cli，我们还安装了 @graphql-codegen/typescript 和 @graphql-codegen/client-preset。@graphql-codegen/typescript 是一个用于生成 TypeScript 类型定义的插件，而 @graphql-codegen/client-preset 是一个预设的配置，可以方便地生成适用于客户端的代码。
创建 codegen.ts 配置文件
接下来，我们需要在项目根目录下创建一个 codegen.ts 文件，用于配置代码生成器的行为。
以下是一个简单的 codegen.ts 配置文件示例：
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
schema: 'https://api.cartql.com',
documents: ['./main.ts'],
ignoreNoDocuments: true, // for better experience with the watcher
generates: {
'./gql/': {
preset: 'client'
}
}
};
export default config;在这个配置文件中，我们指定了以下选项：
-
schema：GraphQL Schema 的 URL。 -
documents：包含 GraphQL Query 和 Mutation 的文件路径。 -
ignoreNoDocuments：忽略没有 Query 和 Mutation 的文件。 -
generates：配置代码生成器的输出。
-
'./gql/'：生成的代码输出到./gql/目录下。 -
preset: 'client'：使用client预设，生成适用于客户端的代码。
-
配置 package.json 脚本
为了方便运行代码生成器，我们可以在 package.json 文件中添加一个脚本：
{
"scripts": {
"codegen": "graphql-codegen",
"codegen-watch": "graphql-codegen --watch"
}
}现在，我们可以使用以下命令来运行代码生成器：
npm run codegen
或者：
yarn codegen
使用以下命令来监听文件变化并自动运行代码生成器：
npm run codegen-watch
或者：
yarn codegen-watch
在 TypeScript 代码中使用生成的类型定义
运行代码生成器后，会在 ./gql/ 目录下生成一系列文件，其中包含了 GraphQL Schema 的类型定义。
现在，我们可以在 TypeScript 代码中导入这些类型定义，并使用它们来增强类型安全性：
import { request, gql } from 'graphql-request';
import { GetCartByIdQuery, GetCartByIdQueryVariables } from './gql/graphql';
const getCartById = gql`
query GetCartById($id: ID!) {
cart(id: $id) {
id
totalItems
items {
name
quantity
lineTotal {
formatted
}
}
subTotal {
formatted
}
}
}
`;
async function fetchCart(id: string) {
const variables: GetCartByIdQueryVariables = { id };
const data: GetCartByIdQuery = await request(
'https://api.cartql.com',
getCartById,
variables
);
console.log(data.cart?.id);
}在这个示例中，我们导入了 GetCartByIdQuery 和 GetCartByIdQueryVariables 类型，它们是根据 GetCartById Query 自动生成的。通过使用这些类型，我们可以确保 variables 对象和 data 对象的类型与 GraphQL Schema 一致，从而避免了类型不匹配的错误。
使用 GraphQL 代码生成器，让类型管理更轻松
步骤 1：配置 GraphQL 代码生成器
首先，需要创建一个配置文件 codegen.ts，并指定 Schema 路径、Document 路径和使用的插件。
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
schema: 'http://localhost:4000/graphql',
documents: ['src/**/*.tsx', 'src/**/*.ts'],
generates: {
'./src/generated/graphql.ts': {
plugins: ['typescript']
}
}
};
export default config;步骤 2：运行 GraphQL 代码生成器
在 package.json 文件中添加一个脚本，用于运行 GraphQL 代码生成器。
{
"scripts": {
"generate": "graphql-codegen"
}
}然后，运行以下命令：
npm run generate
步骤 3：在代码中使用生成的类型
在代码中导入生成的类型，并使用它们来增强类型安全性。
import { useQuery, gql } from '@apollo/client';
import { GetTodosQuery } from './generated/graphql';
const GET_TODOS = gql`
query GetTodos {
todos {
id
text
completed
}
}
`;
function Todos() {
const { loading, error, data } = useQuery<gettodosquery>(GET_TODOS);
if (loading) return <p>Loading...</p>;
if (error) return <p>Error : {error.message}</p>;
return (
<ul>
{data?.todos.map(todo => (
<li key="{todo.id}">{todo.text}</li>
))}
</ul>
);
}</gettodosquery>GraphQL 代码生成器：免费提升效率的工具
免费使用，高效开发
GraphQL 代码生成器通常是免费的开源工具，这意味着你可以零成本地使用它来提升开发效率。例如，@graphql-codegen/cli 及其相关插件都是开源的，你可以自由地使用和定制它们，而无需支付任何费用。
这种免费的特性使得 GraphQL 代码生成器成为各种规模项目的理想选择，无论你是个人开发者还是大型团队，都可以从中受益。通过自动化类型生成，你可以节省大量的时间和精力，将更多的资源投入到业务逻辑的开发中，从而更快地交付高质量的软件。
GraphQL 代码生成器的优势与劣势
? Pros
减少手动编写类型定义的工作量，避免出错。
自动同步 Schema 和类型定义，减少维护成本。
提高开发效率，将更多精力集中在业务逻辑的开发上。
保障代码质量，生成高质量、一致性的代码，减少 Bug 产生的可能性。
GraphQL 代码生成器可以自动生成文档，方便开发人员理解 API。
配合watch命令进行实时更新，同步GraphQL API改动。
类型安全，在编译阶段就能发现错误
? Cons
需要学习代码生成器的配置和使用方法。
生成的代码可能不符合项目的代码风格，需要进行调整。
依赖于 GraphQL Schema 的准确性，如果 Schema 错误，生成的代码也会出错。
如果 GraphQL Schema 非常复杂，生成的代码可能会比较庞大。
可能需要一些额外的设置才能和现有的code base兼容
GraphQL 代码生成器：核心功能一览
自动化类型生成，告别手动维护
GraphQL 代码生成器的核心功能是根据 GraphQL Schema 自动生成各种类型的代码，包括 TypeScript 类型定义、React Hooks、Angular Service 等。这意味着你可以告别手动维护类型定义的繁琐工作，让代码生成器帮你完成一切。
这种自动化类型生成的功能可以极大地提高开发效率，减少出错的可能性，并保持代码的一致性和可维护性。当 Schema 发生变化时，只需要重新运行代码生成器，就可以自动更新类型定义，保证了类型定义与 Schema 的同步。
支持多种插件，满足不同需求
GraphQL 代码生成器通常支持多种插件，可以满足不同的代码生成需求。例如，@graphql-codegen/cli 支持以下常用插件：
-
@graphql-codegen/typescript：生成 TypeScript 类型定义。 -
@graphql-codegen/typescript-resolvers：生成 TypeScript Resolvers 的类型定义。 -
@graphql-codegen/typescript-react-apollo：生成 React Apollo Hooks。 -
@graphql-codegen/typescript-graphql-files：从 GraphQL 文件生成 TypeScript 类型定义。
通过选择合适的插件，你可以根据项目的具体需求，生成最合适的代码。
灵活的配置选项，定制生成行为
GraphQL 代码生成器通常提供灵活的配置选项，可以让你定制代码生成的行为。例如，你可以指定 Schema 路径、Document 路径、输出目录、使用的插件、生成的代码风格等。
这种灵活的配置选项可以让你根据项目的具体需求，定制代码生成器的行为，从而生成最符合项目要求的代码。
与多种前端框架和后端语言集成
GraphQL 代码生成器可以与多种前端框架和后端语言集成，例如 React、Angular、Vue、Node.js、Java、Python 等。这意味着你可以在各种不同的项目中使用 GraphQL 代码生成器，从而提高开发效率和代码质量。
无论你使用哪种前端框架或后端语言，都可以找到相应的 GraphQL 代码生成器插件，从而方便地集成到项目中。
GraphQL 代码生成器：适用场景广泛
大型项目：告别手动维护，提高效率
在大型项目中，GraphQL Schema 通常非常复杂，包含了大量的类型定义。手动维护这些类型定义是一项非常繁琐的任务，而且容易出错。GraphQL 代码生成器可以自动化这个过程，极大地提高开发效率和代码质量。通过自动生成类型定义，你可以节省大量的时间和精力，将更多的资源投入到业务逻辑的开发中，从而更快地交付高质量的软件。
此外，大型项目通常会有多个团队协作开发，GraphQL 代码生成器可以保证团队成员使用一致的类型定义，从而减少协作成本和沟通成本。
Schema 频繁变化：自动同步，减少出错
在快速迭代的项目中，GraphQL Schema 经常会发生变化，比如添加新的字段、修改字段的类型等。手动更新类型定义很容易出错，而且容易遗漏。GraphQL 代码生成器可以自动同步 Schema 和类型定义，减少出错的可能性。当 Schema 发生变化时，只需要重新运行代码生成器，就可以自动更新类型定义，保证了类型定义与 Schema 的同步。
这种自动同步的功能可以极大地提高开发效率，并减少了出错的可能性，让你专注于业务逻辑的开发。
多种前端框架和后端语言：灵活集成，提高复用
GraphQL 代码生成器可以与多种前端框架和后端语言集成，例如 React、Angular、Vue、Node.js、Java、Python 等。这意味着你可以在各种不同的项目中使用 GraphQL 代码生成器，从而提高开发效率和代码质量。无论你使用哪种前端框架或后端语言，都可以找到相应的 GraphQL 代码生成器插件，从而方便地集成到项目中。
这种灵活的集成特性可以让你在不同的项目之间复用代码生成器的配置，从而减少重复劳动，提高开发效率。
常见问题解答
GraphQL 代码生成器是否会影响代码性能？
GraphQL 代码生成器通常不会影响代码性能。它只是在编译时生成类型定义等代码，不会在运行时执行任何额外的操作。因此，使用 GraphQL 代码生成器不会对代码性能产生负面影响。相反，它可以提高代码的可维护性和可读性，从而间接提高代码性能。
GraphQL 代码生成器是否难以学习？
GraphQL 代码生成器并不难学习。它通常提供清晰的文档和示例，可以帮助你快速上手。此外，GraphQL 代码生成器通常提供灵活的配置选项，可以让你根据项目的具体需求，定制代码生成器的行为。这意味着你可以从简单的配置开始，逐步学习更高级的用法。
GraphQL 代码生成器是否适用于所有项目？
GraphQL 代码生成器适用于大多数 GraphQL 项目，尤其是大型项目和 Schema 频繁变化的项目。然而，对于小型项目和简单的 Schema，使用 GraphQL 代码生成器的收益可能并不明显。在这种情况下，你可以根据项目的具体情况，权衡是否使用 GraphQL 代码生成器。
相关问题
如何选择合适的 GraphQL 代码生成器？
选择合适的 GraphQL 代码生成器需要考虑以下因素： 支持的语言和框架： 确保代码生成器支持你使用的语言和框架。 插件生态系统： 检查代码生成器是否提供丰富的插件，以满足你的具体需求。 配置选项： 评估代码生成器是否提供灵活的配置选项，以定制生成行为。 社区支持： 了解代码生成器是否有活跃的社区，以便获取帮助和支持。 一些常用的 GraphQL 代码生成器包括： @graphql-codegen/cli：一个功能强大的代码生成器，支持多种插件和配置选项。 apollo-tooling：由 Apollo 提供的代码生成工具，与 Apollo Client 集成良好。 graphql-ruby：一个 Ruby 语言的 GraphQL 代码生成器。 你可以根据项目的具体需求，选择最合适的代码生成器。 使用代码生成器，代码生成器可以自动生成与 GraphQL Request 兼容的类型
