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

Guards - kto przechodzi przez bramę

5 min czytania ·
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 - nie NestMiddleware, nie NestInterceptor, nie PipeTransform,
  • canActivate() zwraca true, żeby zezwolić na dostęp - nie napis 'allowed', nie obiekt z rolami, nie null; false daje 403 i handler się nie wykonuje,
  • kolejność w metodzie: canActivate(context: ExecutionContext) { → const request = context.switchToHttp().getRequest(); → const token = request.headers.authorization; → return !!token;,
  • ExecutionContext udostę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 przez useGlobalGuards albo token APP_GUARD,
  • SetMetadata('roles', roles) zapisuje wymagania przy handlerze, a Reflector je 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. 1. Czym middleware różni się od guarda w NestJS?

  2. 2. Jaki interfejs implementuje guard w NestJS?

  3. 3. Co zwraca metoda canActivate() guarda, aby zezwolić na dostęp do endpointu?

  4. 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

  1. PytaniePodstawy: Middleware vs Guard
  2. Kliknij w kolejnościKonfiguracja middleware w module
  3. Zadanie z kodemRejestracja middleware w module
  4. PytaniePodstawy: Interfejs Guard
  5. PytaniePodstawy: Wartość zwracana przez guard
  6. Zadanie z kodemPodstawy: AuthGuard - straż autoryzacji
  7. Ułóż w kolejnościPodstawy: Dekorator UseGuards
  8. PytaniePodstawy: ExecutionContext w guardzie
  9. Kliknij w kolejnościPodstawy: Implementacja guarda autoryzacji
  10. Zadanie z kodemPodstawy: RolesGuard z metadanymi

Przydatne artykuły