Kurs NestJS · Moduł 2: Routing i cykl żądania
Guards - kto przechodzi przez bramę
W tej lekcji6
Wartownik przy rogatce liczy wszystkich wchodzących i zapisuje godzinę. Robi to samo dla kupca, posłańca i legionisty - bo na rogatce jeszcze nie wiadomo, dokąd który z nich idzie. Dopiero przy drzwiach skarbca stoi ktoś, kto wie, do której komnaty puka przybysz, i dlatego może powiedzieć „ty nie".
To jest cała różnica między middleware a guardem, i w tej lekcji zamkniemy ją do końca.
W poprzedniej lekcji middleware podpięliśmy w module przez configure(consumer) i .forRoutes('tributes'). Zwróć uwagę na argument 'tributes': middleware dostaje wzorzec ścieżki, nie nazwę kontrolera ani metody - i to jest pierwszy trop do tego, czego mu brakuje.
Czego middleware nie wie
Middleware wykonuje się przed guardem i nie zna trasy docelowej. Nie jest to niedopatrzenie autorów frameworka, tylko konsekwencja momentu: middleware działa na poziomie Express, zanim NestJS rozstrzygnie, który kontroler i która metoda obsłużą żądanie. Dostaje req, res i next - trzy obiekty HTTP i nic ponadto.
Dlatego middleware świetnie nadaje się do rzeczy niezależnych od celu: logowania, nagłówków CORS, parsowania ciasteczek. Nie nadaje się do decyzji w rodzaju „ten endpoint wymaga roli administratora", bo w chwili jego działania nie istnieje jeszcze pojęcie „tego endpointu".
CanActivate - interfejs strażnika
Guard to klasa implementująca interfejs CanActivate. Nie NestMiddleware - ten należy do middleware z poprzedniej lekcji; nie NestInterceptor - to interceptory, które poznasz za chwilę; nie PipeTransform - to pipes, jeszcze dalej. Każdy z czterech mechanizmów cyklu żądania ma własny interfejs i własną jedną metodę:
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
const token = request.headers.authorization;
return !!token;
}
}Ciało metody czyta się w czterech krokach, zawsze w tej kolejności: canActivate(context: ExecutionContext) { przyjmuje kontekst, const request = context.switchToHttp().getRequest(); wydobywa z niego obiekt żądania, const token = request.headers.authorization; sięga po nagłówek, a return !!token; zamienia go na decyzję.
Ta decyzja to wartość logiczna true, gdy dostęp ma być przyznany - nie napis 'allowed', nie obiekt z rolami, nie null. Podwójny wykrzyknik w !!token robi dokładnie to: zamienia „nagłówek jest albo go nie ma" na true albo false. Gdy padnie false, NestJS odrzuca żądanie z kodem 403 Forbidden, a metoda kontrolera nie uruchamia się wcale.
ExecutionContext - to, czego brakowało
Argument context jest powodem, dla którego guard potrafi więcej niż middleware. ExecutionContext udostępnia informacje o docelowym kontrolerze i metodzie (handlerze) - nie dostęp do bazy danych, nie dostęp do systemu plików, nie konfigurację serwera. Te rzeczy zdobywa się inaczej: bazę przez wstrzyknięcie repozytorium, konfigurację przez ConfigService.
Dwie metody wystarczą na początek. context.switchToHttp().getRequest() schodzi do warstwy HTTP po znajomy obiekt żądania - „switch", bo NestJS obsługuje też WebSockety i mikroserwisy, a kontekst jest wspólny dla wszystkich. context.getHandler() zwraca samą metodę kontrolera, która ma obsłużyć żądanie, a context.getClass() - klasę kontrolera.
I właśnie tego middleware nie ma. Guard, mając w ręku handler, może zapytać: „czego ta konkretna metoda wymaga?".
Podpięcie guarda
Guard podpina się dekoratorem @UseGuards - na pojedynczej metodzie albo na całym kontrolerze:
@Controller('treasury')
@UseGuards(AuthGuard)
export class TreasuryController {
@Get()
findAll() {
return this.treasuryService.findAll();
}
}Zapis składa się z trzech części: @UseGuards( otwiera dekorator, AuthGuard nazywa klasę strażnika - klasę, nie jej instancję, bo tworzenie zostawiamy wstrzykiwaniu zależności - a ) domyka. Guardów można podać kilka po przecinku; sprawdzane są po kolei i wystarczy jeden false, żeby żądanie przepadło.
Gdy strażnik ma pilnować całej aplikacji, rejestrujesz go globalnie: app.useGlobalGuards(new AuthGuard()) w main.ts albo jako provider z tokenem APP_GUARD. Druga droga jest lepsza, gdy guard sam czegoś potrzebuje - provider przechodzi przez wstrzykiwanie zależności, new nie.
Reflector - guard, który czyta wymagania
Skoro guard zna handler, może odczytać wymagania zapisane przy nim. Wymagania dopina się przez SetMetadata, a odczytuje klasą Reflector:
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const requiredRoles = this.reflector.get<string[]>(
'roles',
context.getHandler(),
);
if (!requiredRoles) {
return true;
}
const request = context.switchToHttp().getRequest();
return requiredRoles.includes(request.user?.role);
}
}SetMetadata('roles', roles) przykleja do metody etykietę pod kluczem 'roles'. this.reflector.get<string[]>('roles', context.getHandler()) czyta ją z powrotem - pierwszy argument to klucz, drugi to miejsce, przy którym szukać, czyli nasz handler. Brak etykiety oznacza endpoint bez wymagań, więc zwracamy true i przepuszczamy.
Jeden guard obsługuje w ten sposób całą aplikację: @Roles('senator') nad jedną metodą, @Roles('centurion', 'tribune') nad inną, a logika porównania zapisana raz. To ten sam SetMetadata, do którego wrócimy przy własnych dekoratorach - tam zobaczysz, jak zwinąć @Roles i @UseGuards w jedną pieczęć.
Podsumowanie
Rogatka liczy wchodzących, strażnik skarbca decyduje:
- middleware rejestrujesz w module implementującym
NestModule:configure(consumer: MiddlewareConsumer) {→consumer.apply(LoggerMiddleware)→.forRoutes('tributes')→}, - middleware wykonuje się przed guardem i nie zna trasy docelowej - działa, zanim NestJS rozstrzygnie, który handler obsłuży żądanie,
- guard implementuje interfejs
CanActivate- nieNestMiddleware, nieNestInterceptor, niePipeTransform, canActivate()zwracatrue, żeby zezwolić na dostęp - nie napis'allowed', nie obiekt z rolami, nienull;falsedaje403i handler się nie wykonuje,- kolejność w metodzie:
canActivate(context: ExecutionContext) {→const request = context.switchToHttp().getRequest();→const token = request.headers.authorization;→return !!token;, ExecutionContextudostępnia informacje o docelowym kontrolerze i metodzie (handlerze) - nie bazę danych, nie system plików, nie konfigurację serwera,context.getHandler()zwraca metodę,context.getClass()- kontroler,switchToHttp().getRequest()- obiekt żądania,- podpięcie:
@UseGuards(→AuthGuard→), globalnie przezuseGlobalGuardsalbo tokenAPP_GUARD, SetMetadata('roles', roles)zapisuje wymagania przy handlerze, aReflectorje odczytuje:this.reflector.get<string[]>('roles', context.getHandler()).
W następnej lekcji poznasz interceptory - trzeci mechanizm cyklu, który jako pierwszy dotyka odpowiedzi, a nie tylko żądania. A na razie zapamiętaj różnicę: middleware pyta „co przyszło", guard pyta „dokąd to idzie i czy wolno".
Kod do tej lekcji: src/guards.ts
// Guards w NestJS - Elitarni Strażnicy Skarbca
import {
Injectable, CanActivate, ExecutionContext,
SetMetadata, UnauthorizedException, ForbiddenException,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
console.log("Guards - elitarni strażnicy decydujący o dostępie!");
// ===========================================
// 1. Prosty AuthGuard
// ===========================================
@Injectable()
export class RomanAuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
const authHeader = request.headers['authorization'];
if (!authHeader || !authHeader.startsWith('Bearer ')) {
throw new UnauthorizedException('Brak tokenu autoryzacji!');
}
const token = authHeader.split(' ')[1];
// W prawdziwej aplikacji: weryfikacja JWT
if (token !== 'roman-secret-token') {
throw new UnauthorizedException('Nieprawidłowy token!');
}
// Dodaj dane użytkownika do requestu
request.user = { id: 1, name: 'Marcus', roles: ['Centurio'] };
return true;
}
}
// ===========================================
// 2. RolesGuard z metadanymi
// ===========================================
export const ROLES_KEY = 'roles';
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const requiredRoles = this.reflector.get<string[]>(
ROLES_KEY,
context.getHandler(),
);
// Brak wymaganych ról - wpuść
if (!requiredRoles || requiredRoles.length === 0) {
return true;
}
const request = context.switchToHttp().getRequest();
const user = request.user;
if (!user) {
throw new ForbiddenException('Użytkownik niezalogowany!');
}
const hasRole = requiredRoles.some(role => user.roles?.includes(role));
if (!hasRole) {
throw new ForbiddenException('Brak wymaganej rangi: ' + requiredRoles.join(', '));
}
return true;
}
}
// ===========================================
// 3. Użycie w kontrolerze
// ===========================================
// @Controller('senate')
// @UseGuards(RomanAuthGuard, RolesGuard)
// export class SenateController {
// @Roles('Senator', 'Consul')
// @Get('secret-decrees')
// getSecretDecrees() {
// return { decrees: ['Tajny dekret...'] };
// }
// }
console.log("\n=== PODSUMOWANIE GUARDS ===");
console.log("CanActivate - interfejs guardów");
console.log("canActivate() zwraca true/false");
console.log("@SetMetadata - ustawianie metadanych (np. role)");
console.log("Reflector - odczytywanie metadanych");
console.log("@UseGuards() - stosowanie guarda na kontrolerze/metodzie");
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. Czym middleware różni się od guarda w NestJS?
2. Jaki interfejs implementuje guard w NestJS?
3. Co zwraca metoda canActivate() guarda, aby zezwolić na dostęp do endpointu?
4. Co udostępnia ExecutionContext w guardzie, czego nie ma w middleware?
Zadania praktyczne w grze
- Klikanie w kolejności
Ułóż elementy konfiguracji middleware w prawidłowej kolejności:
- Edytor kodu
Zaimplementuj NestModule w AppModule z metodą configure(), która rejestruje LoggerMiddleware dla tras 'tributes'
- Edytor kodu
Napisz AuthGuard implementujący CanActivate, który sprawdza obecność tokenu w nagłówku authorization żądania
- Układanie w poziomie
Ułóż elementy użycia dekoratora @UseGuards na kontrolerze:
- Klikanie w kolejności
Ułóż elementy implementacji guarda autoryzacji w prawidłowej kolejności:
- Edytor kodu
Napisz RolesGuard, który używa Reflector do odczytania ról z SetMetadata i porównania z rolą użytkownika
Zadania po tej lekcji
- PytaniePodstawy: Middleware vs Guard
- Kliknij w kolejnościKonfiguracja middleware w module
- Zadanie z kodemRejestracja middleware w module
- PytaniePodstawy: Interfejs Guard
- PytaniePodstawy: Wartość zwracana przez guard
- Zadanie z kodemPodstawy: AuthGuard - straż autoryzacji
- Ułóż w kolejnościPodstawy: Dekorator UseGuards
- PytaniePodstawy: ExecutionContext w guardzie
- Kliknij w kolejnościPodstawy: Implementacja guarda autoryzacji
- Zadanie z kodemPodstawy: RolesGuard z metadanymi