Почему Nest живёт на старых декораторах

Старую систему декораторов включает один ключ в tsconfig.json — experimentalDecorators. Она намного старше стандарта: TypeScript выпустил её по ранней редакции предложения, которое с тех пор переписали целиком. Общего у двух систем почти ничего: другие подписи, другой состав, другой вывод компилятора. Настройки песочницы поменять нельзя, зато компилятор можно позвать прямо из примера и дать ему любые ключи — тем же способом, каким в главе о своём каркасе печатали вывод для стандартных декораторов.

Ниже контроллер Nest в том виде, в каком его пишут: пометка на классе, зависимость в конструкторе, маршрут на методе и @Param перед параметром. Компилятору отданы оба ключа старой системы. Прогноз: сколько вызовов __metadata окажется в выводе и что достанется декоратору параметра, для которого в стандарте нет места?

declare const ts: any;

const source = `
@Controller("notes")
class NotesController {
  constructor(private readonly notes: NotesService) {}

  @Get(":id")
  byId(@Param("id") id: string) {
    return this.notes.byId(id);
  }
}`;

// те же два ключа, что стоят в tsconfig.json любого проекта на Nest
const { outputText } = ts.transpileModule(source, {
  compilerOptions: { target: ts.ScriptTarget.ES2023, experimentalDecorators: true, emitDecoratorMetadata: true },
});
// помощники компилятор ставит в начало файла — печатаем только класс
console.log(outputText.slice(outputText.indexOf("var _a;")).trim());

Ни статического блока, ни __esDecorate — вместо них одна функция __decorate и два её вызова: для метода и для класса. Порядок прежний, члены раньше класса, а дальше всё ново.

__param(0, Param("id")) — это и есть декоратор параметра. Обернуть параметр не во что, поэтому помощник превращает его в декоратор метода: тот позовёт Param("id") и передаст ему прототип, имя метода и номер параметра. Возвращать такому декоратору нечего, его работа — оставить пометку в таблице, откуда каркас потом возьмёт значение для аргумента.

Записей о типах три, и все у метода: design:type — Function, design:paramtypes — [String], design:returntype — void 0. Компилятор записал в выпущенный код те самые типы, которые только что стёр. У класса запись одна, design:paramtypes с типом параметра конструктора, и вокруг имени стоит охрана: typeof NotesService !== "undefined" && NotesService. В этом примере NotesService нигде не объявлен, и компилятор не уверен, доживёт ли имя до запуска; когда класс объявлен рядом, он пишет имя голым — это будет видно в прогоне, где тот же класс пройдёт через четыре компилятора.

Каждое из отличий старой системы в Nest на что-нибудь да потрачено.

Старая система не «недоделанная новая». Это другая модель: не «замени значение», а «оставь пометку о месте».

Раз метаданные так полезны, напрашивается вопрос: нельзя ли взять из старой системы их одни, а декораторы оставить стандартные? Ответ даёт сам компилятор. Ниже три запуска tsc над одним и тем же файлом, разница только в ключах. Прогноз: в каком из трёх запусков будет напечатан вызов Body(), а в каком не будет ни одной диагностики?

// декоратор параметра — тот самый @Body() из контроллера Nest;
// подпись старая: класс, имя метода, номер параметра
function Body() {
  return function (target: object, method: string | symbol | undefined, index: number) {
    console.log(`Body() пометил параметр ${index} метода ${String(method)}`);
  };
}

class NotesController {
  create(@Body() dto: unknown) {
    return dto;
  }
}

new NotesController();

$ tsc --noEmit --target ES2023 param.ts
  param.ts(10,10): error TS1206: Decorators are not valid here.
  код 2
$ tsc --noEmit --target ES2023 --experimentalDecorators param.ts
  ни одной диагностики
  код 0
$ tsc --noEmit --target ES2023 --emitDecoratorMetadata param.ts
  error TS5052: Option 'emitDecoratorMetadata' cannot be specified without specifying option 'experimentalDecorators'.
  код 2

Строка «Body() пометил параметр» не напечаталась ни разу: tsc файл проверяет, а не выполняет. Первый запуск даёт TS1206 — «Decorators are not valid here», ту самую ошибку, которую вы уже получали в песочнице, и код выхода 2. Второй запуск — тот же файл с --experimentalDecorators — не даёт ни одной диагностики: в старой системе такой код законен целиком.

Третий запуск и есть ответ на вопрос. TS5052: «Option 'emitDecoratorMetadata' cannot be specified without specifying option 'experimentalDecorators'». Заметьте, в диагностике нет ни имени файла, ни строки — это отказ настроек, файл компилятор даже не открыл. Метаданные не отдельная возможность, которую можно прикрутить к стандартным декораторам: это часть старой системы, и включается она только вместе с ней.

Обратный переход стоит столько же. Ключ решает за весь проект: двух систем в одном файле не бывает. «Перевести Nest на стандартные декораторы» значит выбросить разом @Body, @Param, @Query, @Inject и выдуманный компилятором список зависимостей — а на их месте в стандарте пусто: декораторы параметров вынесены в отдельное предложение первой стадии, и метаданных о типах в предложении о метаданных нет вовсе. Менять пришлось бы не Nest, а каждое приложение на нём.

// @nestjs/common 12.0.3, decorators/http/route-params.decorator.d.ts — выдержка
export interface ParameterDecoratorOptions {
  schema?: StandardSchemaV1;
  pipes?: (Type<PipeTransform> | PipeTransform)[];
}

export declare function Body(): ParameterDecorator;
export declare function Body(options: ParameterDecoratorOptions): ParameterDecorator;
export declare function Body(property: string, options: ParameterDecoratorOptions): ParameterDecorator;

Ключ в tsconfig — не настройка вкуса. Это выбор языка, на котором написаны все декораторы проекта.

Главная запись — __metadata("design:paramtypes", [NotesService]). Сама по себе она не делает ничего: помощник __metadata устроен как if (typeof Reflect.metadata === "function") return Reflect.metadata(k, v), а в чистом движке такой функции нет. Компилятор пишет вызов в пустоту и ждёт, что кто-нибудь положит на Reflect хранилище.

Положим сами. Хранилище — WeakMap по классу, как в своём реестре сведений. Прогноз: что окажется в таблице после того, как выполнится выпущенный компилятором код, — имена классов, строки с именами типов или пусто?

declare const ts: any;

const source = `
@Injectable()
class NotesController {
  constructor(private readonly notes: NotesService, private readonly clock: Clock) {}
}`;

const { outputText } = ts.transpileModule(source, {
  compilerOptions: { target: ts.ScriptTarget.ES2023, experimentalDecorators: true, emitDecoratorMetadata: true },
});

// reflect-metadata в три строки: таблица по классу, как в своём реестре
const paramtypes = new WeakMap<Function, Function[]>();
Object.assign(Reflect, {
  metadata: (key: string, value: Function[]) => (target: Function) => {
    if (key === "design:paramtypes") paramtypes.set(target, value);
  },
});

function Injectable() {
  return function () {};
}
class NotesService {}
class Clock {}

const Controller = eval(outputText + "\nNotesController");
console.log("список зависимостей:", paramtypes.get(Controller)?.map((cls) => cls.name).join(", "));
console.log("создаём по списку:", new Controller(new NotesService(), new Clock()) instanceof Controller);

В таблице классы, а не их имена: NotesService и Clock — те самые конструкторы, по которым контейнер и найдёт провайдеров. Список, который у вашего каркаса писался руками в декораторе, здесь достался даром и разойтись с конструктором не может: его источник — сам конструктор. Настоящий reflect-metadata отличается от этих нескольких строк только тем, что таблица одна на всех и висит на глобальном Reflect, — поэтому её и хватает пакетам, которые друг о друге не знают.

Но выручает такая запись не со всяким типом. Прогноз к следующему примеру: у шести параметров разные типы, и у каждого свой ответ — что именно компилятор напишет в design:paramtypes?

declare const ts: any;

const начало = `
type Ref<T> = T;
interface Mail { send(): void }
class MailService { send() {} }
`;

const параметры = [
  "mail: MailService",
  "mail: Mail",
  "mail: Ref<MailService>",
  "mail: MailService | undefined",
  "title: string",
  "id: number",
];

for (const параметр of параметры) {
  const { outputText } = ts.transpileModule(
    `${начало}
@Injectable()
class UsersService {
  constructor(private readonly ${параметр}) {}
}`,
    { compilerOptions: { target: ts.ScriptTarget.ES2023, experimentalDecorators: true, emitDecoratorMetadata: true } },
  );
  const запись = /design:paramtypes",\s*\[([\s\S]*?)\]\)/.exec(outputText);
  console.log(`${параметр} → ${запись ? запись[1].replace(/\s+/g, " ") : "ничего"}`);
}

Компилятор пишет не тип, а класс, который от типа останется после стирания. Класс остаётся собой. Интерфейс не остаётся ничем, и на его месте появляется Object — искать в контейнере по такому ключу нечего, поэтому перед параметром-интерфейсом и ставят внедрение по токену. Примитивам достаются обёртки String и Number.

Две средние строки — ловушки. Ref<MailService> — это псевдоним type Ref<T> = T, то есть буквально тот же MailService, но записать его компилятор уже не может: в записи может стоять только имя класса, а не вычисленный тип. И MailService | undefined — та же история: дописали к типу два слова, объединение перестало быть классом, и контейнер в тот же миг перестал видеть зависимость. Ни ошибки, ни предупреждения при этом не будет — будет Object.

// @nestjs/core 12.0.3, injector/injector.js — выдержка
reflectConstructorParams(type) {
  const paramtypes = [
    ...(Reflect.getMetadata(PARAMTYPES_METADATA, type) || []),
  ];
  const selfParams = this.reflectSelfParams(type);
  selfParams.forEach(({ index, param }) => (paramtypes[index] = param));
  return Array.from(paramtypes);
}

В метаданные попадает не то, что вы написали, а то, что от написанного остаётся в рантайме.

Вызов __decorate стоит в выпущенном файле сразу за классом и выполняется вместе с файлом — задолго до того, как контейнер начнёт кого-то создавать. Значит, имя типа обязано указывать на живое значение уже в этот момент. В обычном проекте разницы не видно: файл сервиса импортирует файл репозитория, тот выполняется первым, класс к моменту записи готов. Разница видна в круге.

Два сервиса ждут друг друга: UsersService просит MailService, MailService — UsersService. В проекте на ES-модулях это кончается ReferenceError ещё до Nest, и статья о «can't resolve» это показывала; падает как раз строка __metadata("design:paramtypes", [UsersService]) — имя в круге ещё не инициализировано. Ниже тот же круг, но в проекте на CommonJS: "type": "commonjs" в package.json, всё остальное слово в слово. Прогноз: дойдёт ли дело до Nest, и если дойдёт, на что он пожалуется?

import 'reflect-metadata';
import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { UsersService } from './users.service.js';
import { MailService } from './mail.service.js';

@Module({ providers: [UsersService, MailService] })
class AppModule {}

async function bootstrap() {
  await NestFactory.createApplicationContext(AppModule);
  console.log('приложение собрано');
}

bootstrap();

[Nest] <pid>  - <дата>     LOG [NestFactory] Starting Nest application...
[Nest] <pid>  - <дата>     LOG [InjectorLogger] Nest encountered an undefined dependency. This may be due to a circular import or a missing dependency declaration.
[Nest] <pid>  - <дата>   ERROR [ExceptionHandler] UndefinedDependencyException [Error]: Nest can't resolve dependencies of the MailService (?). Please make sure that the argument at index [0] is available in the current module.

Potential solutions:
- The dependency at index [0] appears to be undefined at runtime
- This commonly occurs when using 'import type' instead of 'import' for injectable classes
- Check your imports and change:
  ❌ import type { SomeService } from './some.service';
  ✅ import { SomeService } from './some.service';
- Ensure the imported class is decorated with @Injectable() or is a valid provider
- If using dynamic imports, ensure the class is available at runtime, not just for type checking

For more common dependency resolution issues, see: https://docs.nestjs.com/faq/common-errors
    at Injector.resolveSingleParam (file://<пример>/node_modules/@nestjs/core/injector/injector.js:250:19)
    at resolveParam (file://<пример>/node_modules/@nestjs/core/injector/injector.js:150:49)
    at Array.map (<anonymous>)
    at Injector.resolveConstructorParams (file://<пример>/node_modules/@nestjs/core/injector/injector.js:182:58)
    at Injector.loadInstance (file://<пример>/node_modules/@nestjs/core/injector/injector.js:76:24)
    at Injector.loadProvider (file://<пример>/node_modules/@nestjs/core/injector/injector.js:110:20)
    at file://<пример>/node_modules/@nestjs/core/injector/instance-loader.js:58:33
    at Array.map (<anonymous>)
    at InstanceLoader.createInstancesOfProviders (file://<пример>/node_modules/@nestjs/core/injector/instance-loader.js:57:36)
    at file://<пример>/node_modules/@nestjs/core/injector/instance-loader.js:42:24

Дошло. require в круге отдаёт наполовину заполненный объект экспортов — вы собирали это руками, — и компилятор пишет в метаданные не имя, а обращение к нему: __metadata("design:paramtypes", [users_service_js_1.UsersService]). Эта строка достаётся mail.service.js: он выполняется внутри круга, когда users.service.js до своего класса ещё не дошёл. Обращение к недостающему свойству не падает, оно даёт undefined. Так в списке зависимостей одного из двух сервисов и оказывается undefined вместо класса; у второго к его строке круг уже замкнулся, и там лежит настоящий класс.

Отсюда и вид сообщения: MailService (?) — вопрос вместо имени токена. Такой вид дают три причины: тип-интерфейс без @Inject, импорт одного типа вместо значения и круг файлов в проекте на CommonJS — во всех трёх компилятору нечего было записать. А имя исключения отделяет первую причину от двух остальных: от интерфейса в записи остаётся Object, Nest искал по нему и не нашёл — это UnknownDependenciesException; здесь же в записи undefined, искать нечего вовсе — UndefinedDependencyException.

Список зависимостей пишется в тот миг, когда выполняется файл класса. Всё, что к этому мигу не готово, в список не попадёт.

Раз список зависимостей пишет компилятор, вопрос «чем собирать» перестаёт быть вопросом вкуса и скорости. Ниже один и тот же класс проходит через четыре инструмента: tsc, SWC, Oxc и esbuild, а у SWC и Oxc ещё и с ключом метаданных и без него. Прогноз: у скольких из шести строк декоратор окажется применён и у скольких при этом появится запись о типах?

// маленький Nest: пометка на классе и зависимость в конструкторе
function Injectable(): ClassDecorator {
  return () => {};
}

class NotesService {
  byId(id: number) {
    return { id, title: 'купить хлеб' };
  }
}

@Injectable()
export class NotesController {
  constructor(private readonly notes: NotesService) {}
}

tsc, флаги в tsconfig              декоратор: да  design:paramtypes: NotesService
swc, decoratorMetadata: true       декоратор: да  design:paramtypes: typeof NotesService === "undefined" ? Object : NotesService
swc, без ключа                     декоратор: да  design:paramtypes: ничего
oxc, emitDecoratorMetadata: true   декоратор: да  design:paramtypes: typeof NotesService === "undefined" ? Object : NotesService
oxc, без ключа                     декоратор: да  design:paramtypes: ничего
esbuild, флаги в tsconfigRaw       декоратор: да  design:paramtypes: ничего

Декоратор применили все шесть раз — это работа с синтаксисом, её умеет каждый. А запись о типах появилась у трёх: у tsc, которому ключи отданы в настройках, и у SWC с Oxc, когда им отдельно сказали decoratorMetadata и emitDecoratorMetadata. Без ключа оба молчат.

esbuild не пишет метаданные никогда, и ключ в tsconfigRaw ничего не меняет. Это решение, а не недоделка: esbuild разбирает файлы по одному и не знает, чем окажется имя NotesService в рантайме — классом, интерфейсом или псевдонимом. SWC и Oxc отвечают на этот вопрос догадкой: пишут имя под охраной typeof, а если в рантайме его не окажется — Object. tsc охраны не ставит вовсе: он видит, что NotesService объявлен тут же классом, а не стёртым типом, — и пишет имя голым. Важно другое: молчание esbuild тихое. Ни ошибки, ни предупреждения — декоратор в выводе стоит на месте, метаданных нет.

Под esbuild работает tsx, а tsx — самый привычный способ запустить .ts-файл. Прогноз: что будет, если запустить им настоящее приложение Nest — те самые файлы, которые в прошлой статье отвечали 200 и 404? Файлы не тронуты ни в одной букве, включая tsconfig.json с обоими ключами; другая только команда.

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 undefined
GET /notes/1 → 500 {"statusCode":500,"message":"Internal server error"}
GET /notes/99 → 500 {"statusCode":500,"message":"Internal server error"}
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 → 500 {"statusCode":500,"message":"Internal server error"}
заметок у сервиса из контейнера: 1
контроллер тоже лежит в контейнере: true

Первая строка — design:paramtypes undefined, и дальше всё следствия. Приложение стартовало без единой жалобы: Nest не обязан требовать метаданные, класс без зависимостей их и не имеет, а отличить «нет зависимостей» от «список потерян» ему нечем. Контроллер создан, в поле notes лежит undefined, и рушится это на первом же обращении к сервису: 500 на трёх запросах из пяти.

Целы ровно те два ответа, которым сервис не нужен: 400 от ParseIntPipe — трубу в @Param("id", ParseIntPipe) передали явно, метаданные ей ни к чему, — и 404 роутера на DELETE. Строка про заметки добивает: у сервиса из контейнера их одна, а не две, потому что POST тоже упал. Код выхода 0.

Лога в выводе нет по одной причине: пример сам ставит logger: false. С логгером по умолчанию каждый 500 печатает ERROR [ExceptionsHandler] TypeError: Cannot read properties of undefined со стеком, и в скобках стоит метод, до которого не дошли: reading 'byId' у чтения, reading 'add' у создания. Процесс это тоже не роняет. Это самый дорогой вид поломки: сборка зелёная, старт чистый, проверка здоровья отвечает 200, а всё, что трогает базу, отвечает 500.

Тот же вопрос встаёт там, где о сборке обычно не думают, — в тестах: файлы компилирует раннер, своим компилятором и своими настройками. Приложение при этом собирается настоящим контейнером Nest, и если метаданных нет, тест получит ровно то же самое — объект с undefined вместо зависимости и падение в неожиданном месте. Чем это оборачивается на практике, разбирает статья о тестах против настоящей базы; проверка та же — напечатать запись и посмотреть, на месте ли она.

Сборщик, который «просто быстрее», здесь меняет поведение приложения. Молча.

Отсюда весь список рабочих способов. nest build и nest start по умолчанию зовут tsc — в nest-cli.json стартера о сборщике не сказано ни слова, а умолчание самого CLI записано объектом builder: { type: "tsc" }, — и он же проверяет типы. Это тот самый компилятор, о котором говорилось при выборе сборщика: для сервера бандл не обязателен, достаточно файла на файл.

Второй способ — nest build -b swc, заметно быстрее. Ключи метаданных при этом выставлять не нужно, билдер ставит их сам:

// @nestjs/cli 12.0.1, lib/compiler/defaults/swc-defaults.js — выдержка
jsc: {
  target: 'es2021',
  parser: { syntax: 'typescript', decorators: true },
  transform: {
    legacyDecorator: true,
    decoratorMetadata: true,
    useDefineForClassFields: false,
  },
}

Те же два ключа, что в tsconfig.json, только названные по-своему. Цена скорости — SWC типы не проверяет вовсе: проверку CLI запускает отдельным процессом и только по флагу --type-check. Для монорепо в CLI 12 есть третий путь — Rspack: у подприложения билдер по умолчанию так и записан, а внутри у него тот же SWC с теми же двумя ключами. Прежний webpack остался, но при запуске просит перейти на Rspack.

Версия компилятора тоже не свободна. CLI зовёт компилятор как библиотеку, а в typescript 7.0 прежнего программного API у пакета нет: сам tsc остался, но как исполняемый файл. CLI это проверяет и отказывается — «does not expose the programmatic compiler API that the Nest CLI requires», — добавляя, что API ожидается в 7.1, и предлагая поставить TypeScript 6. Её и ставят: шестая версия стоит и в стартере Nest 12, и в носителе прогонов этого учебника.

А запустить .ts напрямую не выйдет дважды. Во-первых, стирание типов декораторов не понимает: node main.ts падает SyntaxError до первой строки вывода — это вы уже видели на стандартном декораторе, и со старым ровно то же самое. Во-вторых, даже если декораторы убрать, останется constructor(private readonly notes: NotesService) — а это параметр-свойство, не аннотация, а код, и Node отвечает ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX. Флаг --experimental-transform-types, который раньше это решал, из Node 26 убран совсем.

Правило, которое из этого следует, короткое: в проекте на Nest инструмент запуска выбирается один раз и меняется только вместе с проверкой, что метаданные на месте. Одной строки console.log(Reflect.getMetadata("design:paramtypes", NotesController)) при старте хватает, чтобы поломка объявила о себе сразу, а не первым запросом в проде.

Свой каркас можно было запускать чем угодно. Чужой каркас приносит с собой свой список инструментов — и это часть цены.