Kurs NestJS · Moduł 2: Routing i cykl żądania
Własne dekoratory - pieczęcie i insygnia imperium
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. Jakiej funkcji NestJS używamy do tworzenia własnego dekoratora parametru (np. @CurrentUser())?
2. Co reprezentuje argument 'data' w createParamDecorator((data, ctx) => ...)? Np. przy użyciu @CurrentUser('rank').
3. Do czego służy funkcja SetMetadata() w NestJS?
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:
Zadania po tej lekcji
- PytanieTworzenie dekoratora parametru
- PytanieArgument data w createParamDecorator
- Zadanie z kodemTworzenie dekoratora @CurrentUser()
- Kliknij w kolejnościStruktura createParamDecorator
- PytanieSetMetadata i Reflector
- Zadanie z kodemDekorator @Roles() z SetMetadata i RolesGuard
- Ułóż w kolejnościWywołanie SetMetadata
- PytanieFunkcja applyDecorators
- Ułóż w kolejnościSkładowe złożonego dekoratora @Auth()