Первый Nest: где в нём ваш контейнер, ваш роутер и ваш конвейер

Настоящий Nest начинается не с кода, а с команды: npx @nestjs/cli@12 new notes-api. Она разложит проект и предложит поставить пакеты. Прогон ниже делает ровно это — тем же CLI 12.0.1, но с пропущенной установкой: сейчас интересен не npm install, а то, что окажется в папке и что о проекте решили за вас.

import { spawnSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';

// У читателя это одна команда: npx @nestjs/cli@12 new notes-api. Здесь CLI берётся
// из носителя пакетов прогона, а установку пропускаем — интересен сам проект
const cli = createRequire(import.meta.url).resolve('@nestjs/cli/bin/nest.js');
const { stdout } = spawnSync(
  process.execPath,
  [cli, 'new', 'notes-api', '--skip-install', '--skip-git', '--package-manager', 'npm'],
  { encoding: 'utf8' },
);
// из вывода оставляем только список созданного: дальше идёт просьба о пожертвовании
for (const line of stdout.split('\n')) if (line.startsWith('CREATE')) console.log(line);

const pkg = JSON.parse(readFileSync('notes-api/package.json', 'utf8'));
console.log(`type: ${pkg.type}`);
console.log(`start: ${pkg.scripts.start} | test: ${pkg.scripts.test} | lint: ${pkg.scripts.lint}`);
console.log(`dependencies: ${Object.keys(pkg.dependencies).join(', ')}`);

const tsconfig = JSON.parse(readFileSync('notes-api/tsconfig.json', 'utf8')).compilerOptions;
const flags = ['module', 'target', 'experimentalDecorators', 'emitDecoratorMetadata'];
console.log(`tsconfig: ${flags.map((flag) => `${flag}: ${tsconfig[flag]}`).join(', ')}`);

CREATE notes-api/.oxlintrc.json (206 bytes)
CREATE notes-api/.prettierrc (52 bytes)
CREATE notes-api/README.md (6551 bytes)
CREATE notes-api/nest-cli.json (171 bytes)
CREATE notes-api/package.json (1428 bytes)
CREATE notes-api/tsconfig.build.json (170 bytes)
CREATE notes-api/tsconfig.json (601 bytes)
CREATE notes-api/vitest.config.e2e.ts (245 bytes)
CREATE notes-api/vitest.config.ts (350 bytes)
CREATE notes-api/src/app.controller.ts (277 bytes)
CREATE notes-api/src/app.module.ts (255 bytes)
CREATE notes-api/src/app.service.ts (142 bytes)
CREATE notes-api/src/main.ts (237 bytes)
CREATE notes-api/src/app.controller.spec.ts (623 bytes)
CREATE notes-api/test/app.e2e-spec.ts (728 bytes)
type: module
start: nest start | test: vitest run | lint: oxlint --type-aware src/ test/
dependencies: @nestjs/common, @nestjs/core, @nestjs/platform-express, reflect-metadata, rxjs
tsconfig: module: nodenext, target: ES2023, experimentalDecorators: true, emitDecoratorMetadata: true

Пятнадцать файлов, и приложения среди них четыре: модуль, контроллер, сервис и точка входа. Остальное — инструменты: vitest.config.ts вместо конфигурации jest, .oxlintrc.json вместо eslint, tsconfig.build.json для выпуска. Стартер Nest 12 сменил и то и другое: test зовёт vitest run, lint — oxlint --type-aware. К тому, как устроен такой раннер изнутри, вы вернётесь, когда будете писать свой.

Три строки вывода важнее остальных. type: module — пакеты Nest 12 сами собраны как ES-модули, и стартер поэтому тоже ES-модуль: это то самое поле type из разговора о package.json, а импорты внутри проекта из-за него пишутся с расширением .js. В зависимостях стоит @nestjs/platform-express — платформа по умолчанию; в прогоне следующего раздела вместо неё Fastify, и что такое «платформа» у Nest, разбирает отдельная статья про адаптер. А в tsconfig — experimentalDecorators: true и emitDecoratorMetadata: true: Nest 12 остался на той системе декораторов, от которой вы отказались в пользу стандартной, и почему он не может её сменить — сюжет целой статьи.

// notes-api/src/main.ts — как его написал nest new 12.0.1, дословно
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

Вот и вся точка входа. NestFactory.create(AppModule) — это ваш createApp(AppModule): обойти модули, создать контроллеры через контейнер, записать маршруты. app.listen — то, чем у вас заканчивался прогон на настоящем сокете. Команда nest start из scripts сначала собирает проект тем же tsc, что и nest build, — с проверкой типов и выпуском метаданных, — а потом запускает выпуск.

Сборка стартера не прячет компилятор: nest start — это tsc, а потом node dist. Всё, что вы знаете про tsc, здесь работает.

Положим в проект тот самый контроллер заметок, с которым вы работали всю главу: сервис хранит заметки, контроллер отдаёт одну по номеру и заводит новую. Запросы пойдут не через сокет, а через app.inject — у адаптера Fastify это вызов обработчика «как будто по сети», без порта и без ожидания. Вашему каркасу вы писали такой же inject сами.

Прежде чем разворачивать вывод, ответьте на пять вопросов. Что придёт на /notes/99, которой в хранилище нет? Что на /notes/abc? Что на DELETE /notes/1, если метод DELETE в контроллере не объявлен вовсе? Каким кодом ответит POST? И что напечатает первая строка — список зависимостей контроллера, которого в коде нет?

import 'reflect-metadata';
import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
import { NotesController } from './notes.controller.js';
import { NotesService } from './notes.service.js';

@Module({ controllers: [NotesController], providers: [NotesService] })
class AppModule {}

// список зависимостей контроллера, который вы писали руками, здесь уже готов
console.log('design:paramtypes', Reflect.getMetadata('design:paramtypes', NotesController));

// то же, что ваш createApp: контейнер, обход модулей, маршруты — в роутер платформы
const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter(), { logger: false });
await app.init();

for (const request of [
  { method: 'GET', url: '/notes/1' },
  { method: 'GET', url: '/notes/99' },
  { method: 'GET', url: '/notes/abc' },
  { method: 'DELETE', url: '/notes/1' },
] as const) {
  const response = await app.inject(request);
  console.log(`${request.method} ${request.url} → ${response.statusCode} ${response.body}`);
}

const created = await app.inject({ method: 'POST', url: '/notes', payload: { title: 'молоко' } });
console.log(`POST /notes → ${created.statusCode} ${created.body}`);
// заметку добавил контроллер, а спрашиваем мы сервис, взятый из приложения: объект один
console.log('заметок у сервиса из контейнера:', app.get(NotesService).count());
console.log('контроллер тоже лежит в контейнере:', app.get(NotesController) instanceof NotesController);
await app.close();

design:paramtypes [ [class NotesService] ]
GET /notes/1 → 200 {"id":1,"title":"купить хлеб"}
GET /notes/99 → 404 {"message":"заметки 99 нет","error":"Not Found","statusCode":404,"errorCode":"NOT_FOUND"}
GET /notes/abc → 400 {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
DELETE /notes/1 → 404 {"message":"Cannot DELETE /notes/1","error":"Not Found","statusCode":404}
POST /notes → 201 {"id":2,"title":"молоко"}
заметок у сервиса из контейнера: 2
контроллер тоже лежит в контейнере: true

Первая строка — главная. design:paramtypes у NotesController — это [ [class NotesService] ]: список зависимостей, который у вас писался руками в @Controller("/notes", { deps: [NotesService] }), здесь уже лежит в метаданных, и написал его компилятор. Больше ничего нового в контроллере нет: @Controller, @Get, конструктор с зависимостью — ваши декораторы, только путь принято писать без ведущей косой черты.

Дальше ответы. 200 на заметку, которая есть. 404 на ту, которой нет, — и в теле рядом с message и statusCode стоит errorCode: "NOT_FOUND": в 12-й версии у исключений появилось поле под доменный код, и он доезжает до клиента без всякого своего фильтра. 400 на /notes/abc — это ParseIntPipe, отказавший до обработчика: ровно то, что делала ваша труба.

А вот два ответа, которых ваш каркас не даёт. DELETE /notes/1 — 404 Cannot DELETE /notes/1, а не 405 со списком разрешённых методов: маршрут не нашёлся, и Nest не различает «нет адреса» и «не тот способ». И POST /notes — 201, а не 200: код успеха выбирает не обработчик, а сам фреймворк, и для создания он по умолчанию 201.

Последние две строки — про контейнер. Заметку добавил контроллер, а спросили мы app.get(NotesService) — и заметок у него две: контроллеру достался тот же объект, что лежит в контейнере. Сам контроллер тоже в контейнере лежит, и это первое расхождение в устройстве: у вас контроллер в контейнере не хранится вовсе — сборка создаёт его и забывает.

app.inject — это не тест-утилита, а вход в приложение мимо сети. Запрос доходит до тех же звеньев, что и настоящий.

Теперь те же пять запросов — вашему каркасу. Контроллер приходится переписать в четырёх местах: префикс с ведущей косой чертой, список зависимостей в декораторе, труба над методом вместо параметра и разбор тела руками. Всё остальное переносится буквой в букву.

// Каркас главы 6 — в подложке, здесь только его типы
type Class = new (...args: any[]) => object;
type Req = { method: string; target: string; headers?: Record<string, string>; body?: string };
type Res = { status: number; body: string };
type Call = { params: Record<string, string>; query: URLSearchParams; body: string };
type Ctx = { request: Req; params: Record<string, string>; query: URLSearchParams; controller: string; handler: string };
type Pipe = (call: Call, ctx: Ctx) => Call | Promise<Call>;
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare class HttpError extends Error {
  constructor(status: number, message: string);
  readonly status: number;
}
declare function fail(code: "NOT_FOUND", detail?: string): never;
declare function Injectable(options?: { deps?: Class[] }): Deco;
declare function Module(options: { providers?: Class[]; controllers?: Class[] }): Deco;
declare function Controller(prefix: string, options?: { deps?: Class[] }): Deco;
declare function Get(path?: string): MethodDeco;
declare function Post(path?: string): MethodDeco;
declare function UsePipes(...pipes: Pipe[]): Deco & MethodDeco;
declare function createApp(root: Class): { inject(request: Req): Promise<Res> };

// Труба, которая у настоящего Nest называется ParseIntPipe
const numericId: Pipe = (call) => {
  if (!/^\d+$/.test(call.params.id)) throw new HttpError(400, "id — число");
  return call;
};

@Injectable()
class NotesService {
  #notes = new Map([[1, "купить хлеб"]]);

  byId(id: number) {
    const title = this.#notes.get(id);
    if (title === undefined) fail("NOT_FOUND", `заметки ${id} нет`);
    return { id, title };
  }

  add(title: string) {
    const id = this.#notes.size + 1;
    this.#notes.set(id, title);
    return { id, title };
  }
}

@Controller("/notes", { deps: [NotesService] })
class NotesController {
  constructor(private readonly notes: NotesService) {}

  @UsePipes(numericId)
  @Get("/:id")
  byId(call: Call) {
    return this.notes.byId(Number(call.params.id));
  }

  @Post()
  create(call: Call) {
    const { title } = JSON.parse(call.body) as { title: string };
    return this.notes.add(title);
  }
}

@Module({ controllers: [NotesController], providers: [NotesService] })
class AppModule {}

const app = createApp(AppModule);

async function main() {
  for (const request of [
    { method: "GET", target: "/notes/1" },
    { method: "GET", target: "/notes/99" },
    { method: "GET", target: "/notes/abc" },
    { method: "DELETE", target: "/notes/1" },
    { method: "POST", target: "/notes", body: '{"title":"молоко"}' },
  ]) {
    const response = await app.inject(request);
    console.log(`${request.method} ${request.target} → ${response.status} ${response.body}`);
  }
}

main();

Совпало главное: тот же контроллер, тот же сервис из контейнера, та же труба до обработчика и тот же перевод отказа в ответ одним местом. Разошлись четыре ответа из пяти — и каждое расхождение объяснимо.

Ваш 405 — не ошибка каркаса, а решение, принятое тогда, когда вы писали маршрутизатор: адрес существует, и молчать об этом нечестно. Nest отдаёт маршруты роутеру платформы, а тот отвечает одним 404 на всё, чего не нашёл. Форма тела у вас строже: наружу едет код, а не текст. А тело запроса в вашем обработчике до сих пор разбирает JSON.parse руками — у Nest это делает @Body(), и следующий раздел как раз о том, откуда он берёт значение.

Четыре расхождения из пяти — это подробности, а не устройство. Устройство совпало полностью.

Контейнер Nest — это ваш App из статьи про разрешение вглубь, с теми же правилами: один экземпляр на модуль, поиск по границам модулей, создание снизу вверх. Разница одна, и она в источнике списка зависимостей. Посмотрите, чего стоит эта разница вашему каркасу.

// Каркас главы 6 — в подложке, здесь только его типы
type Class = new (...args: any[]) => object;
type Req = { method: string; target: string; headers?: Record<string, string>; body?: string };
type Res = { status: number; body: string };
type Call = { params: Record<string, string>; query: URLSearchParams; body: string };
type Deco = (value: Class, context: ClassDecoratorContext) => void;
type MethodDeco = (handler: Function, context: ClassMethodDecoratorContext) => void;
declare const depsOf: WeakMap<Function, Class[]>;
declare function Injectable(options?: { deps?: Class[] }): Deco;
declare function Module(options: { providers?: Class[]; controllers?: Class[] }): Deco;
declare function Controller(prefix: string, options?: { deps?: Class[] }): Deco;
declare function Get(path?: string): MethodDeco;
declare function createApp(root: Class): { inject(request: Req): Promise<Res> };

@Injectable()
class NotesService {
  byId(id: string) {
    return { id, title: "купить хлеб" };
  }
}

@Controller("/notes", { deps: [NotesService] })
class NotesController {
  constructor(private readonly notes: NotesService) {}

  @Get("/:id")
  byId(call: Call) {
    return this.notes.byId(call.params.id);
  }
}

// Тот же конструктор, но список зависимостей забыли обновить
@Controller("/broken", { deps: [] })
class BrokenController {
  constructor(private readonly notes: NotesService) {}

  @Get("/:id")
  byId(call: Call) {
    // сборка звала конструктор по списку из декоратора, а другого источника у неё нет
    console.log("что досталось конструктору:", this.notes);
    return { asked: call.params.id };
  }
}

@Module({ controllers: [NotesController, BrokenController], providers: [NotesService] })
class AppModule {}

const app = createApp(AppModule);

async function main() {
  for (const cls of [NotesController, BrokenController]) {
    console.log(`${cls.name}: в декораторе ${depsOf.get(cls)?.map((dep) => dep.name).join(", ") || "пусто"}`);
  }
  for (const target of ["/notes/1", "/broken/1"]) {
    const response = await app.inject({ method: "GET", target });
    console.log(`GET ${target} → ${response.status} ${response.body}`);
  }
}

main();

Список в декораторе и параметры конструктора — две записи одного и того же, и связи между ними нет. Забыли обновить список — сборка молча позвала конструктор без аргументов, зависимость оказалась undefined, и узнать об этом можно только на том запросе, который её тронет. Позвал бы BrokenController метод у своего сервиса — получил бы TypeError и 500 на каждый запрос, и ни одна проверка при старте про это не сказала бы.

У Nest такого списка в коде нет вовсе — и забыть его поэтому невозможно. Компилятор с emitDecoratorMetadata записывает типы параметров конструктора сам, а контейнер их читает: это и есть та первая строка прогона. Цена — привязка к старым декораторам и к tsc: следующая статья главы показывает, как то же приложение под tsx молча отвечает 500 на каждый запрос, которому нужен сервис, потому что метаданные никто не выпустил.

Две записи одного факта рано или поздно разъедутся. Весь смысл emitDecoratorMetadata — оставить одну.

Обработчик вашего каркаса получает один аргумент — call с параметрами пути, строкой запроса и телом. Обработчик Nest получает столько аргументов, сколько написал автор, и каждый со своим происхождением: @Param("id"), @Query("draft"), @Body("title"). Механизм под этим — таблица: у каждого параметра метода записано, откуда брать значение и через что его пропустить.

// HttpError — из подложки: та же ошибка, которую каркас переводит в ответ
type Call = { params: Record<string, string>; query: URLSearchParams; body: string };
declare class HttpError extends Error {
  constructor(status: number, message: string);
  readonly status: number;
}

// Добыча одного параметра: откуда брать и через что пропустить
type Take = (call: Call) => unknown;

const Param = (name: string, pipe: (raw: string) => unknown = String): Take => (call) => pipe(call.params[name]);
const Query = (name: string, pipe: (raw: string) => unknown = String): Take => (call) => pipe(call.query.get(name) ?? "");
const Body = (field: string): Take => (call) => (JSON.parse(call.body) as Record<string, unknown>)[field];

// Труба у параметра — обычная функция «строка → значение»: это и есть ParseIntPipe
const int = (raw: string) => {
  if (!/^\d+$/.test(raw)) throw new HttpError(400, `ожидается число, а пришло «${raw}»`);
  return Number(raw);
};

// Обработчик, у которого параметры названы по-человечески, а не «call»
function update(id: number, draft: boolean, title: string) {
  return `заметка ${id}: «${title}», черновик — ${draft}`;
}

// Список стоит рядом с обработчиком: приписать его к параметрам нечем
const table: Take[] = [Param("id", int), Query("draft", (raw) => raw === "1"), Body("title")];

const callFor = (id: string): Call => ({
  params: { id },
  query: new URLSearchParams("draft=1"),
  body: '{"title":"молоко"}',
});

for (const id of ["7", "abc"]) {
  try {
    console.log(update(...(table.map((one) => one(callFor(id))) as [number, boolean, string])));
  } catch (error) {
    console.log(`${(error as HttpError).status} ${(error as Error).message}`);
  }
}

Таблица из трёх функций — это весь механизм. Второй аргумент Param — труба у параметра: @Param("id", ParseIntPipe) в настоящем Nest работает ровно так же, поэтому в прогоне обработчик получил число, а на abc отказ случился до него. У вас труба ставится над методом и получает call целиком: проверить она может всё, а превратить строку в число для одного параметра — некуда.

Почему список лежит рядом с обработчиком, а не над параметрами? Потому что приписать что-нибудь к параметру нечем: в стандартных декораторах декораторов параметра нет, и @Body() в сигнатуре метода даёт TS1206. Nest стоит именно на них — @Param, @Body, @Query, @Req все до одного декораторы параметров, — и в этом, а не в привычке, причина, по которой он остаётся на старой системе.

Та же таблица кормит не только обработчик. По ней же Nest собирает описание маршрута для OpenAPI: что параметр пути, что тело, какой у них тип — всё это уже записано, и документация выходит из той же таблицы метаданных, которую вы завели на WeakMap.

Один call вместо названных параметров — не упрощение миниатюры, а следствие: приписывать что-либо к параметру стандартным декораторам нечем.

Звенья вы разбирали дважды: страж и труба в одной статье, перехватчик и фильтр в другой, и там же названы их настоящие имена. Здесь остаётся последнее — где они объявляются. В вашем каркасе мест два: аргументы createApp и декораторы над классом или методом. В Nest мест три.

Разница в третьем столбце — не в устройстве, а в полноте. Общий уровень у вас достался только перехватчику и фильтру, а стражу и трубе его никто не дописал: строчка в сборке та же самая, её просто нет. И второй способ объявить общий уровень — провайдером APP_GUARD вместо вызова app.useGlobalGuards — нужен затем, чтобы страж сам пришёл из контейнера со своими зависимостями: объект, созданный руками в main.ts, внедрить в себя ничего не может.

Порядок, в котором звенья выполняются, вы уже собрали своими руками, и в Nest он тот же — вплоть до неочевидного места, где трубы лежат внутри матрёшки перехватчиков. Отдельная статья измеряет этот порядок на настоящем Nest журналом, а не берёт из документации.

Пять видов звеньев — это не пять абстракций ради красоты. У каждого своё место в порядке, и это место вы выбирали сами.

Проверка на понимание — чужой боевой файл. Вот контроллер загрузки фотографий из API самого учебника: он работает на сервере, принимает настоящие файлы и написан задолго до этой главы — ещё для Nest 11, в котором всё перечисленное ниже устроено так же, как в 12.

// apps/api/src/upload/upload.controller.ts боевого API учебника:
// класс целиком, импорты опущены, комментарии исходные
@Controller('upload')
@UseGuards(JwtAuthGuard)
export class UploadController {
  constructor(@Inject(FILE_STORAGE) private readonly storage: FileStorage) {}

  // POST /api/upload/photo (multipart, поле file) → { url }
  // Загрузка живёт в REST, а не в tRPC: multipart тот не умеет, а гонять
  // картинку через base64 в JSON — плюс треть веса на ровном месте.
  @Post('photo')
  @HttpCode(200)
  async uploadPhoto(@Req() request: FastifyRequest): Promise<StoredFile> {
    let file: Awaited<ReturnType<FastifyRequest['file']>> | undefined;
    try {
      file = request.isMultipart() ? await request.file() : undefined;
    } catch {
      file = undefined;
    }
    if (!file) throw new BadRequestException('NO_FILE');
    if (!isAllowedImageMime(file.mimetype)) throw new BadRequestException('BAD_MIME');

    let buffer: Buffer;
    try {
      buffer = await file.toBuffer();
    } catch {
      // единственный способ узнать о превышении лимита @fastify/multipart
      // (5 МБ, main.ts): он обрывает поток именно здесь
      throw new PayloadTooLargeException('FILE_TOO_LARGE');
    }
    return this.storage.save(buffer, file.mimetype);
  }
}

Читается он теперь целиком. @Controller("upload") — префикс, как у вас. @UseGuards(JwtAuthGuard) над классом — страж на всех методах разом, тот самый уровень класса. @Post("photo") — маршрут над методом. @HttpCode(200) — отмена того самого 201, который Nest ставит созданию по умолчанию; теперь понятно, зачем эта строка вообще нужна. @Req() — параметр, которому досталась сырая заявка Fastify: таблица параметров умеет и так.

Дальше конструктор: @Inject(FILE_STORAGE) — внедрение по токену, а не по классу, потому что FileStorage — интерфейс, а интерфейс ключом контейнера быть не может: в рантайме его нет. Компилятор про этот параметр ничего полезного не напишет, и список приходится задать руками — единственное место, где Nest ведёт себя как ваш каркас. А BadRequestException и PayloadTooLargeException — готовые наследники HttpException, ваш HttpError со статусом внутри. Что здесь происходит с самим файлом — поток, лимит и чужое имя — разбирает статья о загрузке файлов.

Если из статьи нужно унести одну вещь, пусть это будет таблица «что я писал — где это здесь». Она отвечает на вопрос, с которым обычно открывают чужой фреймворк: куда смотреть.

Чего в вашем каркасе нет вовсе — список короткий и честный. Областей: провайдер живёт один на приложение, и «по объекту на запрос» вы не писали. Адаптера: ваш каркас умеет ровно один транспорт, а Nest подставляет под себя Express или Fastify, не трогая контроллеры. Хуков жизненного цикла: onModuleInit и onApplicationShutdown нужны, когда у приложения есть что открывать и закрывать, — и про падение на старте, и про мягкую остановку речь впереди. И тестового модуля, который подменяет провайдера заглушкой: подмена держится на том же контейнере, и это отдельная статья.

Дальше по главе — по одной подробности из этой статьи каждая. Модули и области продолжают ваши границы, процедуры tRPC ставят рядом с контроллером другой транспорт, у которого клиент выводится из типа роутера, а схема на границе в 12-й версии принимается прямо в @Body({ schema }) — правда, с ловушкой, о которой вы уже знаете.

Чужой фреймворк перестаёт быть чужим не тогда, когда выучены имена, а тогда, когда видно, что под ними.