Как NestJS использует декораторы?

Question

Accepted Answer

NestJS построен вокруг **декораторов TypeScript** — специальных аннотаций с префиксом `@`, которые прикрепляют **метаданные** к классам, методам и параметрам. NestJS читает эти метаданные (через отражение) для декларативной настройки маршрутизации, внедрения зависимостей, валидации и многого другого. Декораторы везде в Nest.

## Декораторы класса — определите роль класса

```ts
@Controller("users")     // this class is a CONTROLLER, prefix /users
export class UsersController {}

@Injectable()            // this class is a PROVIDER (injectable)
export class UsersService {}

@Module({ ... })         // this class is a MODULE
export class UsersModule {}
```

Декораторы класса объявляют, что такое класс в архитектуре NestJS (контроллер, провайдер, модуль) и настраивают его.

## Декораторы метода — сопоставьте маршруты и примените поведение

```ts
@Get()                   // GET request handler
@Post()                  // POST handler
@Get(":id")              // GET /users/:id
@HttpCode(204)           // set the response status code
@UseGuards(AuthGuard)    // apply a guard to this route
@UseInterceptors(LoggingInterceptor)
findAll() {}
```

## Декораторы параметра — извлеките данные запроса

```ts
findOne(
  @Param("id") id: string,       // route parameter
  @Query("sort") sort: string,   // query string
  @Body() dto: CreateUserDto,    // request body
  @Headers("auth") auth: string, // header
) {}
```

Декораторы параметра декларативно извлекают ровно те данные, которые вам нужны из запроса — без ручного разбора `req`.

## Декораторы свойства/валидации (на DTO)

```ts
export class CreateUserDto {
  @IsEmail()                     // validation rules (class-validator)
  email: string;

@IsString()
  @MinLength(8)
  password: string;
}
```

## Почему декораторы? Декларативные метаданные

```text
Decorators attach METADATA that NestJS reads at runtime (via reflection) to:
  ✓ Register routes (@Get, @Controller)
  ✓ Wire dependency injection (@Injectable, @Inject)
  ✓ Apply guards/interceptors/pipes (@UseGuards, etc.)
  ✓ Validate input (@IsEmail, @IsString)
→ Behavior is declared WHERE it applies, concisely and readably.
```

## Пользовательские декораторы

```ts
// you can create your own — e.g. extract the current user from the request
export const CurrentUser = createParamDecorator((data, ctx) =>
  ctx.switchToHttp().getRequest().user
);
// usage: findProfile(@CurrentUser() user: User) {}
```

## Почему это важно

Декораторы — это определяющая синтаксическая особенность NestJS — весь фреймворк организован вокруг них, поэтому понимание того, как они работают, необходимо для чтения и написания любого кода NestJS.

Они обеспечивают **декларативный**, управляемый метаданными подход: вместо императивной конфигурации вы аннотируете классы, методы и параметры, чтобы объявить маршрутизацию (`@Controller`, `@Get`), внедрение зависимостей (`@Injectable`), сквозное поведение (`@UseGuards`, `@UseInterceptors`) и валидацию (`@IsEmail`) прямо там, где они применяются — лаконично и читаемо.

Этот механизм метаданных через отражение (та же идея, лежащая в основе аннотаций Angular и Java/Spring) позволяет использовать чистый, структурированный стиль NestJS.

Познание категорий (декораторы класса, метода, параметра, свойства), знание распространенных и возможность создания пользовательских декораторов — это основная компетентность NestJS — декораторы — это способ выражения почти всех функций, что делает их одной из первых и самых важных вещей, которые нужно понять в фреймворке.