Code-first GraphQL, резолверы и DataLoader

Code-first: схема генерируется из твоих классов

В подходе code-first ты никогда не пишешь SDL руками. Ты навешиваешь на TypeScript-классы @ObjectType() и @Field(), на методы резолвера — @Query() / @Mutation() / @ResolveField(), и Nest генерирует схему из этой информации о типах при старте. autoSchemaFile пишет SDL на диск (или держит в памяти), чтобы тулинг мог её читать, — но источник истины это твой код. Альтернатива schema-first обратна: ты пишешь SDL руками и генерируешь из него TypeScript-типы. Code-first выигрывает, когда команда живёт в TypeScript и хочет, чтобы типы и схема никогда не расходились.

import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { GraphQLModule } from '@nestjs/graphql';
import { Module } from '@nestjs/common';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: 'schema.gql',        // ГЕНЕРИРУЕМ SDL из TS-классов
      playground: false,                    // выключен в проде
      introspection: process.env.NODE_ENV !== 'production', // прячем схему в проде
    }),
  ],
})
export class AppModule {}

Объектные типы — обычные классы; @Field(() => Int) фиксирует GraphQL-скаляр там, где рефлексия TS не может его вывести (числа, массивы, nullability):

import { Field, Int, ObjectType } from '@nestjs/graphql';

@ObjectType()
export class Post {
  @Field(() => Int) id: number;
  @Field() title: string;
}

@ObjectType()
export class Author {
  @Field(() => Int) id: number;
  @Field({ nullable: true }) firstName?: string;
  @Field(() => [Post]) posts: Post[];   // связь -> резолвится лениво field resolver'ом
}

Резолверы и field resolver — где рождается N+1

Класс @Resolver(() => Author) хостит корневые операции (@Query, @Mutation) и, что критично, field resolver’ы (@ResolveField), которые вычисляют поле лениво, на каждый родительский объект. Поле posts у Author не загружается вместе с автором — оно резолвится, только если запрос его попросил, вызовом field resolver по разу на каждого автора в выборке. Это исполнение на родителя и есть N+1: один запрос на N авторов, потом N отдельных запросов на их посты.

import { Resolver, Query, ResolveField, Parent, Args, Int } from '@nestjs/graphql';

@Resolver(() => Author)
export class AuthorsResolver {
  constructor(
    private readonly authors: AuthorsService,
    private readonly posts: PostsService,
  ) {}

  @Query(() => [Author])
  authors() {
    return this.authors.findAll();          // 1 запрос -> N авторов
  }

  @ResolveField(() => [Post])
  async postsFor(@Parent() author: Author) {
    return this.posts.findByAuthorId(author.id); // выполняется ПО РАЗУ НА АВТОРА -> N+1
  }
}

DataLoader: батчим ключи, собранные за один тик

DataLoader сидит между field resolver’ом и базой. Вместо немедленного запроса каждый вызов load(id) ставит ключ в очередь; в конце текущего тика event-loop’а DataLoader отдаёт весь батч ключей в один findByAuthorIds([...]) и раздаёт результат обратно каждому вызывающему. Он также мемоизирует внутри батча, так что два вызова load(5) бьют по БД один раз. Коллапс драматичен: 1 + N запросов превращаются в 1 + 1.

Loader обязан быть на запрос — его кэш держит данные запроса и не должен утекать между пользователями, — поэтому подключаем его как request-scoped provider и резолвим в GraphQL-context:

import * as DataLoader from 'dataloader';
import { Injectable, Scope } from '@nestjs/common';

@Injectable({ scope: Scope.REQUEST })   // свежий loader на каждый запрос -> нет кросс-запросного кэша
export class PostsLoader {
  constructor(private readonly posts: PostsService) {}

  readonly byAuthorId = new DataLoader<number, Post[]>(async (authorIds) => {
    // ОДИН round-trip на все ключи, собранные в этом тике:
    const rows = await this.posts.findByAuthorIds(authorIds as number[]);
    const byId = new Map<number, Post[]>(authorIds.map((id) => [id, []]));
    for (const p of rows) byId.get(p.authorId)!.push(p);
    return authorIds.map((id) => byId.get(id)!); // ОБЯЗАН вернуть результаты в порядке ключей
  });
}

@ResolveField(() => [Post])
postsFor(@Parent() author: Author) {
  return this.loader.byAuthorId.load(author.id); // ставит ключ в очередь; батчится, а не на вызов
}

Контракт batch-функции строгий: она обязана вернуть массив той же длины и в том же порядке, что и входные ключи, отображая отсутствующий ключ в [] (или null), никогда молча не выбрасывая его, — перепутаешь порядок, и авторы получат чужие посты.

Context, guards и закалка для прода

Guards, interceptors и filters по-прежнему работают в GraphQL — но если попробуешь использовать их точно так же, как в HTTP-контроллере, они тихо провалятся: не смогут прочитать args запроса. Форма аргументов резолвера другая (root, args, context, info), так что общий ExecutionContext ты адаптируешь через GqlExecutionContext.create(context), чтобы прочитать args или request:

import { GqlExecutionContext } from '@nestjs/graphql';
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';

@Injectable()
export class GqlAuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const ctx = GqlExecutionContext.create(context);
    const { req } = ctx.getContext();   // request лежит на GraphQL-context
    return Boolean(req?.user);
  }
}

Единственный эндпоинт, принимающий произвольные запросы, — это поверхность для denial-of-service: глубоко вложенный posts { author { posts { author ... } } } может взорваться в миллионы field-резолвов. Продакшен-графы ограничивают это лимитом глубины запроса (query depth) и бюджетом сложности (complexity) — назначь каждому полю стоимость и отклоняй любую операцию выше потолка ещё до выполнения:

import { Plugin } from '@nestjs/apollo';
import { GraphQLSchemaHost } from '@nestjs/graphql';
import { GraphQLError } from 'graphql';
import { fieldExtensionsEstimator, getComplexity, simpleEstimator } from 'graphql-query-complexity';

@Plugin()
export class ComplexityPlugin {
  constructor(private readonly schemaHost: GraphQLSchemaHost) {}
  async requestDidStart() {
    const max = 20, { schema } = this.schemaHost;
    return {
      didResolveOperation: async ({ request, document }) => {
        const complexity = getComplexity({
          schema, query: document, variables: request.variables,
          operationName: request.operationName,
          estimators: [fieldExtensionsEstimator(), simpleEstimator({ defaultComplexity: 1 })],
        });
        if (complexity > max) throw new GraphQLError(`Query too complex: ${complexity} > ${max}`);
      },
    };
  }
}

Добавь persisted queries (клиенты шлют хеш заранее зарегистрированного запроса, а не произвольный текст) и выключи introspection в проде, чтобы атакующий не мог тривиально замапить весь граф.