TypeScript Academy · 课时

从 GraphQL 模式生成 TypeScript 类型

Q: 「从 GraphQL 模式生成 TypeScript 类型」这节课中我会学到什么？

使用代码生成器从 .graphql 文件生成类型 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用代码生成器从 .graphql 文件生成类型

从 GraphQL 模式生成 TypeScript 类型 是 CoddyKit 上的免费 TypeScript Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。

问题：模式与类型发生偏离

在 GraphQL 项目中，如果没有自动化机制，服务器模式和客户端 TypeScript 类型很容易不同步。代码生成通过直接从模式派生类型来解决这一问题。

# Without codegen: manual types that drift from schema
interface User { id: string; name: string; } // may not match schema

GraphQL 代码生成器

@graphql-codegen/cli 会读取您的 GraphQL 模式，并自动生成 TypeScript 类型。

npm install --save-dev @graphql-codegen/cli @graphql-codegen/typescript

codegen.yml 配置

在 codegen.yml 中配置模式来源和输出位置。

# codegen.yml
schema: "./api/schema.graphql"
generates:
  src/generated/types.ts:
    plugins:
      - typescript

运行生成器

运行 graphql-codegen，根据您的模式生成 TypeScript 类型。

npx graphql-codegen
# Generates src/generated/types.ts with all schema types

生成的输出示例

生成的文件包含与您模式中的每个 GraphQL 类型相匹配的 TypeScript 接口。

// src/generated/types.ts (generated)
export type User = {
  __typename?: "User";
  id: string;
  name: string;
  email: string;
};

export type Query = {
  __typename?: "Query";
  user?: Maybe<User>;
};

来自远程端点的模式

代码生成器还可以通过内省从正在运行的 GraphQL 端点获取模式。

# codegen.yml with remote schema
schema:
  - https://api.example.com/graphql:
      headers:
        Authorization: "Bearer ${AUTH_TOKEN}"

标量类型映射

在代码生成配置中，将自定义 GraphQL 标量映射到 TypeScript 类型。

# codegen.yml
config:
  scalars:
    DateTime: string
    JSON: Record<string, unknown>
    Upload: File

枚举处理

根据代码生成配置，GraphQL 枚举会被映射为 TypeScript 字符串枚举或联合类型。

# Generated from GraphQL enum Role { ADMIN USER GUEST }
export enum Role {
  Admin = "ADMIN",
  User = "USER",
  Guest = "GUEST",
}

非空与 Maybe

GraphQL 中可为空的字段会在生成的类型中变为 Maybe（即 T | null | undefined），以反映模式的可空性。

// GraphQL: name: String (nullable)
// Generated: name?: Maybe<string>

// GraphQL: id: ID! (non-null)
// Generated: id: string

CI 集成

在 CI 中运行代码生成器，以验证生成的类型是否为最新版本。如果模式发生更改却未重新生成类型，则让构建失败。

# CI: check no drift
npx graphql-codegen --check
# Exits 1 if generated files are out of date

回顾：从模式到类型

GraphQL 代码生成器会读取您的模式，并自动生成 TypeScript 类型。使用 codegen.yml 进行配置，运行 graphql-codegen，并将其集成到 CI 中，以防止模式发生偏离。

快速检查

GraphQL 代码生成器的主要用途是什么？

您学到了什么

GraphQL 代码生成器通过从模式生成 TypeScript，消除了模式与类型之间的偏离。使用 codegen.yml 配置它，映射自定义标量，并将其集成到 CI 中，以确保生成内容保持最新。

常见问题解答

「从 GraphQL 模式生成 TypeScript 类型」课时是免费的吗？

是的 — 「从 GraphQL 模式生成 TypeScript 类型」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。

「从 GraphQL 模式生成 TypeScript 类型」这节课中我会学到什么？

使用代码生成器从 .graphql 文件生成类型你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「从 GraphQL 模式生成 TypeScript 类型」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 TypeScript Academy