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

Question

Accepted Answer

NestJS позволяет создавать **пользовательские декораторы** для инкапсуляции переиспользуемой логики — наиболее часто **параметр-декораторы** (для извлечения данных из запроса) и **метаданные-декораторы** (для присоединения данных, читаемых гардами/интерцепторами). Они сохраняют код DRY и выразительным.

## Пользовательский параметр-декоратор — извлечение данных из запроса

```ts
import { createParamDecorator, ExecutionContext } from "@nestjs/common";

// extract the authenticated user (attached to the request by an auth guard)
export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;        // return whatever you want injected
  },
);

// usage — clean and readable
@Get("profile")
getProfile(@CurrentUser() user: User) {     // instead of @Req() req and req.user
  return user;
}
```

`createParamDecorator` создаёт параметр-декоратор: его функция получает `ExecutionContext`, извлекает данные и возвращает значение для инъекции. Это заменяет повторяющееся `@Req() req` + `req.user` доступ на чистый, переиспользуемый `@CurrentUser()`.

## Параметр-декоратор с аргументами

```ts
// extract a specific property: @CurrentUser("email")
export const CurrentUser = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const user = ctx.switchToHttp().getRequest().user;
    return data ? user?.[data] : user;   // `data` is the argument passed to the decorator
  },
);
// @CurrentUser("email") email: string  → injects just user.email
```

## Пользовательский метаданные-декоратор (для чтения гардами/интерцепторами)

```ts
import { SetMetadata } from "@nestjs/common";

// a @Roles() decorator that ATTACHES metadata to a route
export const Roles = (...roles: string[]) => SetMetadata("roles", roles);

// usage
@Roles("admin", "editor")
@Get("users")
listUsers() {}
```

```ts
// a guard reads the metadata via Reflector
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}
  canActivate(ctx: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>("roles", ctx.getHandler());   // read it
    const { user } = ctx.switchToHttp().getRequest();
    return !roles || roles.some(r => user.roles?.includes(r));
  }
}
```

Комбинация `@Roles()` + `RolesGuard` — метаданные-декоратор, который гард читает через `Reflector` — это канонический паттерн для авторизации на основе ролей.

## Композиция декораторов

```ts
import { applyDecorators } from "@nestjs/common";
// bundle multiple decorators into one reusable decorator
export function Auth(...roles: string[]) {
  return applyDecorators(SetMetadata("roles", roles), UseGuards(AuthGuard, RolesGuard));
}
// usage: @Auth("admin")  — applies metadata + guards in one decorator
```

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

Создание пользовательских декораторов — это важный метод NestJS для сохранения кода DRY, выразительным и maintainable. **Пользовательские параметр-декораторы** (`createParamDecorator`) позволяют инкапсулировать частое извлечение данных из запроса (как `@CurrentUser()`) в чистые, переиспользуемые аннотации — намного лучше, чем повторение `@Req() req` и копание в объекте запроса в каждом обработчике. **Пользовательские метаданные-декораторы** (`SetMetadata`) — это фундамент паттернов авторизации NestJS: стандартный подход `@Roles()` + `RolesGuard` (читаемый через `Reflector`) для управления доступом на основе ролей полностью зависит от понимания метаданные-декораторов.

И **композиция декораторов** (`applyDecorators`) позволяет объединить связанные декораторы (например `@Auth()`, который применяет гарды и метаданные вместе) для лаконичного, последовательного применения.

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

Это поднимает вас от просто использования встроенных декораторов к расширению декларативного стиля фреймворка для нужд вашего приложения — ценный, часто используемый навык в реальных NestJS проектах.