你如何使用 NestJS 构建 GraphQL API？

Question

Accepted Answer

NestJS 通过 `@nestjs/graphql` 对 **GraphQL** 提供了一流的支持（基于 Apollo Server）。它提供了 **code-first** 方法（用 TypeScript 类和装饰器定义 schema，schema 自动生成）— 这是 NestJS 的惯用方式 — 完美适配框架的装饰器/DI 模型。

## 设置 GraphQL（code-first）

```ts
@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: "schema.gql",   // code-first: auto-generate the schema from classes
      playground: true,                // interactive query explorer in dev
    }),
  ],
})
export class AppModule {}
```

## 对象类型（用装饰器定义的 schema）

```ts
@ObjectType()                        // a GraphQL type
export class User {
  @Field(() => ID) id: string;
  @Field() name: string;
  @Field() email: string;
  @Field(() => [Post]) posts: Post[];   // related type
}
```

在 code-first 中，带装饰器的类（`@ObjectType`、`@Field`）定义 schema — TypeScript 类型会自动生成 GraphQL schema，保持两者同步。

## 解析器（查询和变更）

```ts
@Resolver(() => User)
export class UsersResolver {
  constructor(private usersService: UsersService) {}   // DI works as usual

@Query(() => [User])               // a query: returns a list of users
  users() {
    return this.usersService.findAll();
  }

@Query(() => User)
  user(@Args("id") id: string) {     // query with an argument
    return this.usersService.findOne(id);
  }

@Mutation(() => User)              // a mutation: creates a user
  createUser(@Args("input") input: CreateUserInput) {
    return this.usersService.create(input);
  }
}
```

解析器（类似控制器，但用于 GraphQL）定义 `@Query` 和 `@Mutation` 处理程序，通过 DI 委派给服务 — 与 REST 控制器的模式相同。

## 解析关联字段（避免 N+1 问题）

```ts
@ResolveField(() => [Post])         // resolve User.posts on demand
posts(@Parent() user: User) {
  return this.postsService.findByUser(user.id);
}
// ⚠️ for lists, this can cause N+1 queries → use DataLoader to BATCH them
```

`@ResolveField` 可以延迟解析关联/嵌套字段 — 但对于列表，这存在 **N+1 查询问题** 的风险，可以用 DataLoader 批处理解决。

## GraphQL 与 REST 权衡

```text
GraphQL: clients request EXACTLY the fields they need (no over/under-fetching),
         one endpoint, strongly typed, great for complex/nested data & varied clients
REST:    simpler, better HTTP caching, well-understood — fine for straightforward APIs
→ Choose based on needs, not hype. NestJS supports both equally well.
```

## 为什么这很重要

NestJS 的一流 GraphQL 支持之所以有价值，是因为它将 GraphQL 的优势带入 — 客户端仅获取他们需要的数据（消除过度和不足提取）、单个强类型的端点，以及对复杂/嵌套数据的卓越处理 — NestJS 熟悉的、结构化的模型中。

理解这一点对于构建现代 API 非常重要，特别是 idiomatic 的 **code-first 方法**（用 TypeScript 类和 `@ObjectType`/`@Field`/`@Resolver` 装饰器定义 schema，schema 自动生成并保持同步），它与 NestJS 的装饰器/DI 架构自然契合 — 解析器的工作方式就像控制器一样，委派给注入的服务。

知道如何定义类型、查询、变更和已解析的字段，以及了解 **N+1 查询问题**（以及 DataLoader 作为解决方案）对于嵌套数据，是高级级别知识的关键。

同样重要的是理解 **GraphQL 与 REST 权衡**，以便为给定项目选择正确的方法（GraphQL 用于灵活、复杂、多客户端的数据需求；REST 用于具有强 HTTP 缓存的更简单的 API）。

GraphQL 是一个主要的 API 范式，NestJS 的干净集成使其成为构建灵活、高效后端的一项重要且频繁相关的能力。