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

Cykl życia żądania w NestJS - droga depeszy przez imperium

5 min czytania ·
W tej lekcji5

Architekcie imperium! Architekt Vitruvius, mistrz budowli i systemów, przygotował dla Ciebie najważniejszą lekcję tego modułu. Poznałeś już middleware, guardy, interceptory, pipes, własne dekoratory i filtry wyjątków. Teraz czas zobaczyć, jak to WSZYSTKO łączy się w jedną całość - pełny cykl życia żądania HTTP w NestJS!

Pełna droga depeszy przez imperium

Wyobraź sobie, że depesza (request HTTP) wyrusza z dalekiej prowincji do Cezara. Po drodze przechodzi przez wiele punktów kontrolnych. Oto dokładna kolejność:

Przychodzące żądanie HTTP
        |
        v
  1. MIDDLEWARE (Strażnik bramy)
        |
        v
  2. GUARDS (Kontrola uprawnień)
        |
        v
  3. INTERCEPTORS - before (Kronikarz - początek)
        |
        v
  4. PIPES (Kontrola jakości danych)
        |
        v
  5. ROUTE HANDLER (Cezar podejmuje decyzję)
        |
        v
  6. INTERCEPTORS - after (Kronikarz - koniec)
        |
        v
  7. EXCEPTION FILTERS (Trybunał - w razie błędu)
        |
        v
  Odpowiedź HTTP

Każdy etap w szczegółach

1. Middleware - strażnik bramy

Middleware wykonuje się PIERWSZY, zanim NestJS w ogóle wie, która metoda kontrolera zostanie wywołana. Ma dostęp do surowego obiektu Request i Response:

// Middleware wykonuje się jako PIERWSZY
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log('[1. MIDDLEWARE] Depesza dotarła do bramy');
    console.log('Metoda: ' + req.method + ', Ścieżka: ' + req.originalUrl);
    next(); // Przekaż dalej
  }
}

2. Guards - kontrola uprawnień

Guards wykonują się PO middleware, ale PRZED interceptorami i pipe'ami. Ich jedynym zadaniem jest odpowiedzieć na pytanie: "Czy ten request ma prawo kontynuować?":

// Guard wykonuje się jako DRUGI
@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    console.log('[2. GUARD] Sprawdzam uprawnienia legionisty');
    const request = context.switchToHttp().getRequest();
    return !!request.headers.authorization; // true = wpuść, false = zablokuj
  }
}

3. Interceptors (before) - kronikarz początek

Interceptory mają unikalną właściwość - wykonują się dwukrotnie: raz PRZED handlerem i raz PO nim. Faza "before" to kod przed next.handle():

// Interceptor - faza BEFORE (trzeci krok)
@Injectable()
export class TimingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const start = Date.now();
    console.log('[3. INTERCEPTOR before] Kronikarz rozpoczyna zapis');

    return next.handle().pipe(
      // Ta część to faza AFTER (szósty krok)
      tap(() => {
        const duration = Date.now() - start;
        console.log('[6. INTERCEPTOR after] Czas: ' + duration + 'ms');
      }),
    );
  }
}

4. Pipes - kontrola jakości danych

Pipes wykonują się BEZPOŚREDNIO przed handlerem. Transformują i walidują dane wejściowe:

// Pipe wykonuje się jako CZWARTY
@Injectable()
export class ParseLegionIdPipe implements PipeTransform {
  transform(value: any) {
    console.log('[4. PIPE] Waliduję dane wejściowe: ' + value);
    const id = parseInt(value, 10);
    if (isNaN(id)) {
      throw new BadRequestException('ID musi być liczbą!');
    }
    return id;
  }
}

5. Route Handler - decyzja Cezara

Handler to docelowa metoda kontrolera - tutaj wykonuje się logika biznesowa:

@Controller('legiones')
export class LegionController {
  @Get(':id')
  @UseGuards(AuthGuard)
  @UseInterceptors(TimingInterceptor)
  findLegion(@Param('id', ParseLegionIdPipe) id: number) {
    console.log('[5. HANDLER] Cezar przetwarza zapytanie o legion ' + id);
    return { id, name: 'Legio X Gemina', commander: 'Marcus' };
  }
}

6. Interceptors (after) - kronikarz koniec

Po zakończeniu handlera, sterowanie wraca do interceptora - do kodu wewnątrz pipe(tap(...)). Tu możesz transformować odpowiedź, logować czas, itp.

7. Exception Filters - trybunał

Exception Filters wykonują się TYLKO gdy zostanie rzucony wyjątek - na dowolnym etapie. Jeśli guard rzuci ForbiddenException, filtr to przechwyci. Jeśli pipe rzuci BadRequestException - też:

// Exception Filter - łapie błędy z KAŻDEGO etapu
@Catch(HttpException)
export class ImperiumExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    console.log('[7. EXCEPTION FILTER] Trybunał obsługuje błąd');
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    response.status(exception.getStatus()).json({
      error: exception.message,
      timestamp: new Date().toISOString(),
    });
  }
}

Praktyczne implikacje kolejności

Zrozumienie kolejności jest kluczowe dla debugowania:

// Przykład: Co się stanie, gdy guard odrzuci request?
// 1. Middleware - WYKONA SIĘ (logowanie)
// 2. Guard - ODRZUCI (rzuci ForbiddenException)
// 3. Interceptor before - NIE wykona się
// 4. Pipe - NIE wykona się
// 5. Handler - NIE wykona się
// 6. Interceptor after - NIE wykona się
// 7. Exception Filter - WYKONA SIĘ (obsłuży ForbiddenException)

// Przykład: Co się stanie, gdy pipe odrzuci dane?
// 1. Middleware - WYKONA SIĘ
// 2. Guard - WYKONA SIĘ (przepuści)
// 3. Interceptor before - WYKONA SIĘ
// 4. Pipe - ODRZUCI (rzuci BadRequestException)
// 5. Handler - NIE wykona się
// 6. Interceptor after - tap() i map() NIE wykonają się (brak odpowiedzi), ale błąd przepłynie przez jego strumień (złapie go catchError)
// 7. Exception Filter - WYKONA SIĘ (obsłuży BadRequestException)

Debugowanie pipeline'u

Praktyczna technika debugowania - dodaj logi na każdym etapie:

// middleware
console.log('[MW] ' + req.method + ' ' + req.originalUrl);

// guard
console.log('[GUARD] User: ' + request.user?.name);

// interceptor, faza before
console.log('[INT-B] Handler: ' + context.getHandler().name);

// pipe
console.log('[PIPE] Value: ' + value + ' -> ' + transformed);

// handler
console.log('[HANDLER] Processing...');

// interceptor, faza after
console.log('[INT-A] Duration: ' + duration + 'ms');

// filtr wyjątków
console.log('[FILTER] Error: ' + exception.message);

Gdy zobaczysz logi, możesz dokładnie śledzić drogę requestu przez cały pipeline i szybko znaleźć, na którym etapie występuje problem.

Podsumowanie cyklu życia

Zapamiętaj tę kolejność jak maszerującą kolumnę legionu:

  1. Middleware - pierwszy punkt kontrolny (surowy request)
  2. Guards - kontrola uprawnień (wpuścić/nie wpuścić)
  3. Interceptors before - początek obserwacji
  4. Pipes - walidacja i transformacja danych
  5. Handler - logika biznesowa
  6. Interceptors after - koniec obserwacji, transformacja odpowiedzi
  7. Exception Filters - obsługa błędów (gdy coś poszło nie tak)

Znajomość tego cyklu to fundament każdego zaawansowanego programisty NestJS - jak znajomość strategii bitewnej dla centuriona!

Kod do tej lekcji: src/request-lifecycle.ts
// Cykl życia żądania - Droga Depeszy przez Imperium
console.log("=== PEŁNY CYKL ŻYCIA ŻĄDANIA w NestJS ===\n");

// Kolejność przetwarzania żądania HTTP:
const lifecycle = [
  '1. MIDDLEWARE      - Strażnik bramy (surowy request)',
  '2. GUARDS          - Kontrola uprawnień (wpuścić/nie)',
  '3. INTERCEPTORS    - Kronikarz - początek (before)',
  '4. PIPES           - Walidacja i transformacja danych',
  '5. ROUTE HANDLER   - Cezar podejmuje decyzję',
  '6. INTERCEPTORS    - Kronikarz - koniec (after)',
  '7. EXCEPTION FILTERS - Trybunał (w razie błędu)',
];

lifecycle.forEach(step => console.log(step));

console.log("\n=== SCENARIUSZE ===\n");

console.log("Scenariusz A: Guard odrzuca request");
console.log("  1. Middleware    -> WYKONANY");
console.log("  2. Guard         -> ODRZUCA (ForbiddenException)");
console.log("  3-6.             -> POMINIĘTE");
console.log("  7. Exception Filter -> OBSŁUGUJE błąd\n");

console.log("Scenariusz B: Pipe odrzuca dane");
console.log("  1. Middleware    -> WYKONANY");
console.log("  2. Guard         -> PRZEPUSZCZA");
console.log("  3. Interceptor   -> WYKONANY (before)");
console.log("  4. Pipe          -> ODRZUCA (BadRequestException)");
console.log("  5-6.             -> POMINIĘTE");
console.log("  7. Exception Filter -> OBSŁUGUJE błąd\n");

console.log("Scenariusz C: Wszystko OK");
console.log("  1. Middleware    -> WYKONANY");
console.log("  2. Guard         -> PRZEPUSZCZA");
console.log("  3. Interceptor   -> WYKONANY (before)");
console.log("  4. Pipe          -> WALIDUJE dane");
console.log("  5. Handler       -> PRZETWARZA logikę");
console.log("  6. Interceptor   -> WYKONANY (after)");
console.log("  7. Exception Filter -> niepotrzebny\n");

console.log("=== KLUCZOWE ZASADY ===");
console.log("- Middleware nie zna docelowej metody kontrolera");
console.log("- Guard decyduje o dostępie (true/false)");
console.log("- Interceptor widzi request PRZED i PO handlerze");
console.log("- Pipe waliduje/transformuje BEZPOŚREDNIO przed handlerem");
console.log("- Exception Filter łapie błędy z KAŻDEGO etapu");

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. Który element NestJS wykonuje się jako PIERWSZY w cyklu życia żądania HTTP?

  2. 2. Co wyróżnia Interceptory na tle innych elementów pipeline'u NestJS?

  3. 3. Co się stanie, gdy Guard odrzuci request (zwróci false)? Które elementy pipeline'u się NIE wykonają?

  4. 4. Interceptor loguje czas w tap() po odpowiedzi, a pipe rzuca BadRequestException. Co jeszcze się wykona?

  5. 5. Na którym etapie cyklu życia żądania mogą zadziałać filtry wyjątków?

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj etapy cyklu życia żądania HTTP w NestJS od pierwszego do ostatniego:

  • Edytor kodu

    Napisz LifecycleLoggerMiddleware, który loguje metodę i ścieżkę requestu, a następnie wywołuje next()

  • Klikanie w kolejności

    Ułóż PEŁNĄ kolejność przetwarzania żądania HTTP w NestJS:

  • Edytor kodu

    Napisz LifecycleAuthGuard sprawdzający nagłówek authorization - zwróć true, jeśli istnieje, i false, jeśli nie

  • Układanie w poziomie

    Ułóż elementy pobrania obiektu request w metodzie canActivate guarda:

  • Edytor kodu

    Napisz LifecycleInterceptor, który przed next.handle() zapisuje Date.now(), a w tap(...) po odpowiedzi loguje, ile milisekund trwała obsługa żądania

  • Układanie w pionie

    Uporządkuj, co dzieje się z żądaniem, gdy guard je odrzuca - od pierwszego etapu do ostatniego:

  • Edytor kodu

    Napisz LifecycleValidationPipe, który parsuje wartość na liczbę i rzuca BadRequestException, jeśli to nie liczba

  • Klikanie w kolejności

    Ułóż logi debugowania w kolejności, w jakiej pojawią się w konsoli przy poprawnym requeście:

  1. Ułóż w kolejnościKolejność etapów cyklu życia żądania
  2. PytaniePierwszy etap cyklu życia żądania
  3. PytanieInterceptor - podwójna natura
  4. Zadanie z kodemMiddleware w cyklu życia żądania
  5. Kliknij w kolejnościPełna kolejność cyklu życia żądania
  6. PytanieGuard odrzuca request - co się dzieje?
  7. Zadanie z kodemGuard w cyklu życia żądania
  8. Ułóż w kolejnościPobranie requestu w Guardzie
  9. PytaniePipe odrzuca dane - scenariusz
  10. Zadanie z kodemInterceptor w cyklu życia żądania
  11. Ułóż w kolejnościScenariusz: Guard odrzuca request
  12. Zadanie z kodemPipe w cyklu życia żądania
  13. Kliknij w kolejnościDebugowanie pipeline'u NestJS
  14. PytanieFiltry wyjątków w cyklu życia żądania

Przydatne artykuły