Kurs NestJS · Moduł 2: Routing i cykl żądania

Własne dekoratory - pieczęcie i insygnia imperium

7 min czytania ·
W tej lekcji6

Senator Cicero przejrzał kontrolery imperium i zmarszczył brwi. W każdej metodzie ta sama linijka const user = req.user, nad każdym endpointem te same cztery dekoratory, a lista ról przepisywana ręcznie w dziesięciu miejscach. Jedna literówka i skarbiec stoi otworem. Rzym rozwiązał ten problem insygniami: pierścień senatora czy toga pretora od razu mówiły, kim jest ich właściciel i co mu wolno. W NestJS tę rolę pełnią custom decorators - własne pieczęcie, które przypinasz do metody, klasy albo parametru.

Pierścień senatora: dekorator parametru

Najczęściej tworzysz dekorator parametru. Wyciąga on dane z żądania i podaje je prosto do argumentu metody. Służy do tego funkcja createParamDecorator, która przyjmuje fabrykę z dwoma argumentami: data, czyli wartością wpisaną w nawias dekoratora, oraz ExecutionContext, znanym Ci już z lekcji o guardach:

// decorators/current-user.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

// Dekorator @CurrentUser() - wyciąga dane użytkownika z requestu
export const CurrentUser = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user; // Ustawiony wcześniej przez AuthGuard

    // Jeśli podano konkretne pole, zwróć tylko je
    return data ? user?.[data] : user;
  },
);

Fabryka uruchamia się przy każdym żądaniu, a jej wynik NestJS wstawia w miejsce parametru. Dekorator niczego nie pobiera z bazy i nie zmienia requestu - tylko odczytuje request.user, które wcześniej ustawił guard uwierzytelniający. Operator ?. chroni przed błędem, gdy użytkownika nie ma.

Tak wygląda użycie w kontrolerze legionu:

// Użycie w kontrolerze
@Controller('legiones')
export class LegionController {
  @Get('profile')
  @UseGuards(JwtAuthGuard)
  getProfile(@CurrentUser() user: any) {
    // user = { id: 1, name: 'Marcus', rank: 'Centurio', legion: 'Legio X' }
    return { message: `Ave, ${user.name}!`, profile: user };
  }

  @Get('rank')
  @UseGuards(JwtAuthGuard)
  getRank(@CurrentUser('rank') rank: string) {
    // rank = 'Centurio' (tylko konkretne pole)
    return { rank };
  }
}

Zapis @CurrentUser('rank') oznacza, że data === 'rank', więc fabryka zwraca samo user.rank. Jedna uwaga praktyczna: ValidationPipe domyślnie nie waliduje parametrów z własnych dekoratorów, dopóki nie ustawisz opcji validateCustomDecorators: true.

Edykt cesarski: SetMetadata

Drugie narzędzie to metadane, czyli etykiety przyczepione do metody lub klasy. Funkcja SetMetadata(klucz, wartość) zapisuje taką etykietę, a my opakowujemy ją we własny dekorator, żeby nie powtarzać klucza w każdym kontrolerze:

// decorators/roles.decorator.ts
import { SetMetadata } from '@nestjs/common';

// Prosty dekorator @Roles() ustawiający metadane
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

Parametr resztowy ...roles zbiera wszystkie podane role w tablicę. Teraz przypinamy edykt do metod:

// Użycie
@Controller('tributa')
export class TributeController {
  @Post()
  @Roles('consul', 'praetor') // Tylko consul i praetor mogą tworzyć
  createTribute(@Body() dto: any) {
    return { message: 'Trybut utworzony!' };
  }

  @Delete(':id')
  @Roles('consul') // Tylko consul może usuwać
  removeTribute(@Param('id') id: string) {
    return { message: `Trybut ${id} usunięty` };
  }
}

Uwaga, bo to najczęstsze nieporozumienie: same metadane niczego nie blokują. To edykt wywieszony na forum - obowiązuje dopiero wtedy, gdy ktoś go przeczyta i wyegzekwuje.

Pretorianin czyta edykt: Reflector w guardzie

Czytelnikiem jest guard. Reflector z pakietu @nestjs/core odczytuje metadane, a context.getHandler() wskazuje metodę, która za chwilę obsłuży żądanie:

// guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    // Odczytaj metadane 'roles' z handlera
    const requiredRoles = this.reflector.get<string[]>(
      'roles',
      context.getHandler(),
    );

    // Brak wymaganych ról (albo pusta lista) = dostęp dla każdego zalogowanego
    if (!requiredRoles?.length) return true;

    const request = context.switchToHttp().getRequest();
    const user = request.user;

    // Sprawdź, czy użytkownik ma przynajmniej jedną wymaganą rolę
    return requiredRoles.some(role => user?.roles?.includes(role));
  }
}

Brak etykiety oznacza brak wymagań, więc guard przepuszcza żądanie. Warunek !requiredRoles?.length obejmuje też pustą listę - bez niego dekorator bez ról zablokowałby wszystkich, bo [].some() zwraca false. Pamiętaj też, że get() czyta metadane tylko z celu, który mu podasz - tu z metody (context.getHandler()). Jeśli @Roles() stawiasz również na klasie, użyj this.reflector.getAllAndOverride('roles', [context.getHandler(), context.getClass()]) - inaczej rola z klasy zostanie po cichu zignorowana.

Dokumentacja NestJS nazywa SetMetadata podejściem niskopoziomowym i pokazuje wariant z typowaniem:

// decorators/roles.decorator.ts - wariant z Reflector.createDecorator
import { Reflector } from '@nestjs/core';

export const Roles = Reflector.createDecorator<string[]>();
// użycie: @Roles(['consul', 'praetor'])
// odczyt: this.reflector.get(Roles, context.getHandler())

Tu kluczem jest sam dekorator, więc literówka w nazwie klucza przestaje być możliwa, a TypeScript pilnuje typu wartości. W nowym kodzie wybieram ten wariant. SetMetadata nadal działa i spotkasz go w wielu projektach.

Znacznik publiczny: @Public()

Nie każdy dekorator musi łączyć kilka innych. Ten ustawia jedną etykietę, a klucz eksportuje jako stałą, żeby guard mógł go odczytać bez przepisywania napisu:

// decorators/public.decorator.ts
import { SetMetadata } from '@nestjs/common';

// Dekorator oznaczający endpoint jako publiczny (bez autoryzacji)
export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

// Użycie
@Controller('forum')
export class ForumController {
  @Get()
  @Public() // Ten endpoint jest publiczny
  getPublicPosts() {
    return { posts: ['Wiadomość z Forum Romanum'] };
  }
}

Sam znacznik niczego nie otwiera. Działa w duecie z globalnym guardem uwierzytelniania, który najpierw sprawdza getAllAndOverride(IS_PUBLIC_KEY, ...) i przy wartości true przepuszcza żądanie bez tokenu.

Pieczęć główna: applyDecorators

Gdy nad endpointami powtarzasz ten sam zestaw dekoratorów, applyDecorators łączy je w jeden:

// decorators/auth.decorator.ts
import { applyDecorators, UseGuards, SetMetadata } from '@nestjs/common';
import { ApiBearerAuth, ApiUnauthorizedResponse } from '@nestjs/swagger';
import { JwtAuthGuard } from '../guards/jwt-auth.guard';
import { RolesGuard } from '../guards/roles.guard';

// Złożony dekorator @Auth() łączący guard, role i dokumentację
export function Auth(...roles: string[]) {
  return applyDecorators(
    SetMetadata('roles', roles),
    UseGuards(JwtAuthGuard, RolesGuard),
    ApiBearerAuth(),
    ApiUnauthorizedResponse({ description: 'Brak autoryzacji' }),
  );
}

W środku są cztery zwykłe dekoratory: metadane ról, dwa guardy oraz opisy dla Swaggera. applyDecorators nie dodaje nowej logiki - nakłada je po prostu wszystkie naraz.

// Użycie - jeden dekorator zamiast czterech!
@Controller('imperium')
export class ImperiumController {
  @Post('decree')
  @Auth('consul', 'praetor') // Autoryzacja + role + Swagger
  issueDecree(@Body() decree: any) {
    return { message: 'Dekret wydany!', decree };
  }

  @Get('treasury')
  @Auth('consul', 'quaestor') // Tylko consul i quaestor
  getTreasury() {
    return { treasury: 'Stan skarbca imperium' };
  }
}

Jedna linijka zastępuje cztery, a guardy działają dokładnie tak samo jak przedtem. Zmiana zestawu w funkcji Auth obejmuje od razu cały projekt.

Praktyczne zastosowania

Na koniec dwa kolejne dekoratory metadanych, które razem z @Auth() i @CurrentUser() opisują rekrutację legionisty:

// decorators/log-action.decorator.ts
import { SetMetadata } from '@nestjs/common';

// Dekorator do logowania akcji w kronikach imperium
export const LOG_ACTION_KEY = 'logAction';
export const LogAction = (actionName: string) =>
  SetMetadata(LOG_ACTION_KEY, actionName);

// decorators/rate-limit.decorator.ts
export const RATE_LIMIT_KEY = 'rateLimit';
export const RateLimit = (maxRequests: number, windowMs: number) =>
  SetMetadata(RATE_LIMIT_KEY, { maxRequests, windowMs });

// Użycie w kontrolerze
@Controller('legiones')
export class LegionController {
  @Post('recruit')
  @Auth('consul')
  @LogAction('RECRUIT_LEGIONARY')
  @RateLimit(10, 60000) // Max 10 rekrutacji na minutę
  recruitLegionary(@Body() data: any, @CurrentUser() user: any) {
    return {
      message: `${user.name} zrekrutował nowego legionistę`,
      legionary: data,
    };
  }
}

Pamiętaj o zasadzie z edyktu: @LogAction() zadziała dopiero z interceptorem, który odczyta klucz i zapisze wpis w kronice, a @RateLimit() - z guardem liczącym żądania. Do limitowania polecam gotowy pakiet @nestjs/throttler i dekorator @Throttle({ default: { limit: 10, ttl: 60000 } }), zamiast budować licznik od zera.

W następnej lekcji zbudujesz trybunały, czyli exception filters, a w module o uwierzytelnianiu @CurrentUser() odbierze użytkownika przygotowanego przez strategię JWT.

Pamiętaj: dekorator parametru wykonuje swoją fabrykę przy każdym żądaniu, a dekorator metadanych jest tylko pieczęcią, która działa dopiero wtedy, gdy guard albo interceptor ją odczyta.

Kod do tej lekcji: src/custom-decorators.ts
// Własne dekoratory - Pieczęcie i Insygnia Imperium
import { createParamDecorator, ExecutionContext, SetMetadata, applyDecorators, UseGuards } from '@nestjs/common';

console.log("Własne dekoratory - tworzymy pieczęcie imperium!");

// ===========================================
// 1. Własny dekorator parametru
// ===========================================

const CurrentUser = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;
    return data ? user?.[data] : user;
  },
);

console.log("@CurrentUser() - wyciąga dane użytkownika z requestu");
console.log("@CurrentUser('rank') - wyciąga konkretne pole");

// ===========================================
// 2. SetMetadata i Roles
// ===========================================

const Roles = (...roles: string[]) => SetMetadata('roles', roles);

console.log("\n@Roles('consul', 'praetor') - ustawia wymagane role");
console.log("Reflector.get('roles', handler) - odczytuje role w guardzie");

// ===========================================
// 3. applyDecorators - łączenie dekoratorów
// ===========================================

function Auth(...roles: string[]) {
  return applyDecorators(
    SetMetadata('roles', roles),
    // UseGuards(JwtAuthGuard, RolesGuard),
  );
}

console.log("\napplyDecorators() - łączy wiele dekoratorów w jeden");
console.log("@Auth('consul') = SetMetadata('roles', ...) (w lekcji także UseGuards i ApiBearerAuth)");

// ===========================================
// 4. Praktyczny przykład
// ===========================================

const IS_PUBLIC_KEY = 'isPublic';
const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

const LOG_ACTION_KEY = 'logAction';
const LogAction = (actionName: string) => SetMetadata(LOG_ACTION_KEY, actionName);

console.log("\n=== PODSUMOWANIE WŁASNYCH DEKORATORÓW ===");
console.log("createParamDecorator - dekorator parametru");
console.log("SetMetadata - przypisanie metadanych");
console.log("Reflector - odczyt metadanych w guardzie/interceptorze");
console.log("applyDecorators - łączenie wielu dekoratorów");

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jakiej funkcji NestJS używamy do tworzenia własnego dekoratora parametru (np. @CurrentUser())?

  2. 2. Co reprezentuje argument 'data' w createParamDecorator((data, ctx) => ...)? Np. przy użyciu @CurrentUser('rank').

  3. 3. Do czego służy funkcja SetMetadata() w NestJS?

  4. 4. Co robi funkcja applyDecorators() w NestJS?

Zadania praktyczne w grze

  • Edytor kodu

    Napisz dekorator @CurrentUser() używając createParamDecorator, który zwraca request.user lub konkretne pole user[data]

  • Klikanie w kolejności

    Ułóż elementy tworzenia własnego dekoratora parametru w prawidłowej kolejności:

  • Edytor kodu

    Napisz dekorator @Roles() używając SetMetadata('roles', roles) oraz RolesGuard z Reflector, który sprawdza role użytkownika

  • Układanie w poziomie

    Ułóż elementy wywołania SetMetadata do ustawienia wymaganych ról:

  • Układanie w pionie

    Uporządkuj linie dekoratora @Auth() z lekcji od góry do dołu:

  1. PytanieTworzenie dekoratora parametru
  2. PytanieArgument data w createParamDecorator
  3. Zadanie z kodemTworzenie dekoratora @CurrentUser()
  4. Kliknij w kolejnościStruktura createParamDecorator
  5. PytanieSetMetadata i Reflector
  6. Zadanie z kodemDekorator @Roles() z SetMetadata i RolesGuard
  7. Ułóż w kolejnościWywołanie SetMetadata
  8. PytanieFunkcja applyDecorators
  9. Ułóż w kolejnościSkładowe złożonego dekoratora @Auth()

Przydatne artykuły