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

Filtry wyjątków - sądy i trybunały imperium

6 min czytania ·
W tej lekcji6

Prowincjał pyta o trybut, którego nie ma w rejestrze, a serwer odpowiada kodem 500 i komunikatem „Internal server error". Klient nie wie, czy popełnił błąd, czy padła baza, a Ty nie wiesz, co mu właściwie wysłałeś. Pretor Augustus, najwyższy sędzia Rzymu, powtarza, że każda sprawa musi trafić przed właściwy trybunał i zakończyć się czytelnym wyrokiem. W NestJS tymi trybunałami są exception filters - klasy, które przechwytują wyjątki i zamieniają je w odpowiedzi HTTP.

Czym są Exception Filters?

W imperium rzymskim każdy rodzaj sprawy miał swój trybunał:

  • Trybunał pretorski - sprawy cywilne (404 Not Found)
  • Sąd cenzorski - kontrola dostępu (403 Forbidden)
  • Trybunał wojskowy - poważne naruszenia (500 Internal Error)

NestJS ma wbudowaną warstwę wyjątków, która działa jak domyślny trybunał: przechwytuje każdy nieobsłużony wyjątek. Własny filtr piszesz wtedy, gdy chcesz zmienić treść wyroku.

Wbudowane wyjątki NestJS

Zanim napiszesz własny sąd, poznaj gotowe wyroki. Wszystkie poniższe klasy dziedziczą po HttpException i same ustawiają właściwy kod statusu:

import {
  BadRequestException,      // 400
  UnauthorizedException,     // 401
  ForbiddenException,        // 403
  NotFoundException,         // 404
  ConflictException,         // 409
  InternalServerErrorException, // 500
  HttpException,             // bazowy wyjątek HTTP
} from '@nestjs/common';

Komentarze przy importach podają kod, który trafi do klienta. Teraz rzucamy te wyjątki w kontrolerze trybutów:

@Controller('tributa')
export class TributeController {
  private tributes = [
    { id: 1, name: 'Aurum Galliae', amount: 50000 },
    { id: 2, name: 'Argentum Hispaniae', amount: 30000 },
  ];

  @Get(':id')
  findTribute(@Param('id', ParseIntPipe) id: number) {
    const tribute = this.tributes.find(t => t.id === id);
    if (!tribute) {
      // Rzuć wyjątek 404
      throw new NotFoundException(
        `Tributum ${id} non inventum! (Trybut nie znaleziony)`
      );
    }
    return tribute;
  }

  @Post()
  @UseGuards(RolesGuard)
  createTribute(@Body() dto: any) {
    if (!dto.name || !dto.amount) {
      // Rzuć wyjątek 400
      throw new BadRequestException(
        'Trybut musi zawierać nazwę i kwotę!'
      );
    }

    const exists = this.tributes.find(t => t.name === dto.name);
    if (exists) {
      // Rzuć wyjątek 409
      throw new ConflictException(
        `Trybut o nazwie "${dto.name}" już istnieje!`
      );
    }

    const newTribute = { id: this.tributes.length + 1, ...dto };
    this.tributes.push(newTribute);
    return newTribute;
  }
}

Słowo throw przerywa metodę, a warstwa wyjątków NestJS wysyła odpowiedź za Ciebie. Dla brakującego trybutu klient dostanie taki JSON:

{
  "message": "Tributum 3 non inventum! (Trybut nie znaleziony)",
  "error": "Not Found",
  "statusCode": 404
}

Twój tekst trafia do pola message, a error i statusCode wynikają z klasy wyjątku. Gdy potrzebujesz kodu bez własnej klasy, sięgnij po bazowe HttpException z wartością z enuma HttpStatus:

throw new HttpException('Wiadomość błędu', HttpStatus.I_AM_A_TEAPOT); // 418

Kod 418 istnieje naprawdę, choć urodził się jako żart. Uwaga na zwykły throw new Error(): taki wyjątek nie jest HttpException, więc klient zobaczy tylko { "statusCode": 500, "message": "Internal server error" }. Szczegóły błędu zostają na serwerze - i dobrze.

Tworzenie własnych filtrów wyjątków

Własny format wyroku zapewnia klasa implementująca interfejs ExceptionFilter. Dekorator @Catch(HttpException) mówi, jakie sprawy trafiają do tego sądu, a metoda catch() dostaje wyjątek oraz ArgumentsHost - obiekt, z którego wyciągasz request i response:

// filters/roman-exception.filter.ts
import {
  ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus,
} from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class RomanExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();

    // Własny format odpowiedzi błędu w stylu imperium
    response.status(status).json({
      statusCode: status,
      imperium: 'Roma Aeterna',
      error: exception.message,
      path: request.url,
      method: request.method,
      timestamp: new Date().toISOString(),
    });
  }
}

Najpierw host.switchToHttp(), potem z kontekstu response i request, a na końcu wysłanie odpowiedzi. Status możesz odczytać z wyjątku (exception.getStatus()) w dowolnym miejscu przed wysłaniem. Ten filtr zmienia tylko kształt odpowiedzi - kod statusu przepisuje bez zmian z wyjątku. Jedna pułapka: przy błędach walidacji exception.message to ogólne „Bad Request Exception", a lista błędów pól leży w exception.getResponse().

Bindowanie filtrów - poziomy trybunału

Filtr podpinasz dekoratorem @UseFilters() do metody lub kontrolera albo globalnie dla całej aplikacji:

// 1. Poziom metody - tylko ta metoda
@Controller('tributa')
export class TributeController {
  @Get(':id')
  @UseFilters(new RomanExceptionFilter()) // Tylko dla tej metody
  findTribute(@Param('id') id: string) {
    throw new NotFoundException('Trybut nie znaleziony!');
  }
}

// 2. Poziom kontrolera - cały kontroler
@Controller('legiones')
@UseFilters(RomanExceptionFilter) // Cały kontroler
export class LegionController {
  @Get(':id')
  findLegion(@Param('id') id: string) {
    throw new NotFoundException('Legion nie znaleziony!');
  }
}

// 3. Poziom globalny - cała aplikacja (w main.ts)
// app.useGlobalFilters(new RomanExceptionFilter());

Możesz przekazać instancję (new RomanExceptionFilter()) albo samą klasę. Dokumentacja NestJS zaleca klasę, bo framework może wtedy używać jednej instancji w całym module i wstrzykiwać jej zależności. app.useGlobalFilters() ma dwa ograniczenia: filtr powstaje poza systemem modułów, więc nie dostanie zależności przez konstruktor, i nie obejmuje gatewayów WebSocket. Dlatego globalny filtr wolę rejestrować jako provider:

// app.module.ts - filtr globalny zarejestrowany jako provider
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { RomanExceptionFilter } from './filters/roman-exception.filter';

@Module({
  providers: [{ provide: APP_FILTER, useClass: RomanExceptionFilter }],
})
export class AppModule {}

Działa tak samo jak useGlobalFilters, ale filtr może teraz wstrzyknąć na przykład logger. To polecam.

Filtr łapiący wszystko - najwyższy trybunał

Filtr z pustym @Catch() przechwytuje wszystko, także błędy, które nie są HttpException, na przykład zerwane połączenie z bazą:

// filters/all-exceptions.filter.ts
import {
  ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus,
} from '@nestjs/common';

@Catch() // Bez argumentu = łapie WSZYSTKO
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();

    const status = exception instanceof HttpException
      ? exception.getStatus()
      : HttpStatus.INTERNAL_SERVER_ERROR;

    const message = exception instanceof HttpException
      ? exception.message
      : 'Błąd wewnętrzny serwera imperium!';

    response.status(status).json({
      statusCode: status,
      error: message,
      path: request.url,
      timestamp: new Date().toISOString(),
    });
  }
}

Operator instanceof rozdziela dwie ścieżki: wyjątki HTTP zachowują swój status i komunikat, a cała reszta dostaje 500 i ogólny tekst. Nie odsyłaj klientowi exception.message z nieznanego błędu - mógłby zdradzić szczegóły bazy. Taki błąd zapisz w logach. Jeden filtr może też obsłużyć kilka typów naraz: @Catch(HttpException, TypeError).

Kolejność wykonania filtrów

Filtry są jedynym elementem cyklu żądania, który nie zaczyna od poziomu globalnego:

  1. Filtr metody (jeśli istnieje) - sprawdzany jako pierwszy
  2. Filtr kontrolera (jeśli istnieje) - sprawdzany jako drugi
  3. Filtr globalny (jeśli istnieje) - sprawdzany jako ostatni

Wyjątek obsługuje tylko jeden filtr. Jeśli filtr metody go przejmie, filtr kontrolera i globalny nie zostaną wywołane. Gdy jednak @Catch() filtra metody wskazuje inny typ wyjątku, sprawa idzie wyżej, do kontrolera. Na tym samym poziomie filtr łapiący wszystko deklaruj przed bardziej szczegółowym, żeby ten drugi mógł obsłużyć swój typ.

W następnej lekcji zobaczysz, w którym miejscu cyklu życia żądania pracują filtry, a cały moduł 6 poświęcimy obsłudze błędów.

Pamiętaj: wyjątek to oskarżenie, a filtr to trybunał, który zamienia je w czytelny wyrok dla klienta.

Kod do tej lekcji: src/exception-filters.ts
// Filtry wyjątków - Sądy i Trybunały Imperium
import {
  ExceptionFilter, Catch, ArgumentsHost,
  HttpException, HttpStatus, NotFoundException,
  BadRequestException, ForbiddenException,
} from '@nestjs/common';

console.log("Filtry wyjątków - system sądów imperium!");

// ===========================================
// 1. Wbudowane wyjątki NestJS
// ===========================================

function demonstrateExceptions() {
  // 404 Not Found
  // throw new NotFoundException('Tributum non inventum!');

  // 400 Bad Request
  // throw new BadRequestException('Brak wymaganych danych!');

  // 403 Forbidden
  // throw new ForbiddenException('Brak uprawnień!');

  // Dowolny kod HTTP
  // throw new HttpException('Wiadomość', HttpStatus.I_AM_A_TEAPOT);

  console.log("Wbudowane wyjątki: NotFoundException, BadRequestException...");
  console.log("Każdy generuje odpowiedni kod HTTP automatycznie");
}

demonstrateExceptions();

// ===========================================
// 2. Własny filtr wyjątków
// ===========================================

@Catch(HttpException)
class RomanExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();

    response.status(status).json({
      statusCode: status,
      imperium: 'Roma Aeterna',
      error: exception.message,
      path: request.url,
      timestamp: new Date().toISOString(),
    });
  }
}

console.log("\n@Catch(HttpException) - przechwytuje wyjątki HTTP");
console.log("@Catch() - przechwytuje WSZYSTKIE wyjątki");

// ===========================================
// 3. Bindowanie filtrów
// ===========================================

console.log("\nPoziomy bindowania:");
console.log("@UseFilters(filter) na metodzie - tylko ta metoda");
console.log("@UseFilters(filter) na kontrolerze - cały kontroler");
console.log("app.useGlobalFilters(filter) - cała aplikacja");

console.log("\n=== PODSUMOWANIE FILTRÓW WYJĄTKÓW ===");
console.log("HttpException - bazowy wyjątek HTTP");
console.log("@Catch(Type) - dekorator filtra wyjątków");
console.log("ExceptionFilter - interfejs do implementacji");
console.log("@UseFilters() - bindowanie na metodę/kontroler");
console.log("Kolejność: metoda > kontroler > globalny");

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. Jaki kod HTTP generuje rzucenie new NotFoundException() w NestJS?

  2. 2. Co oznacza dekorator @Catch(HttpException) na klasie filtru wyjątków?

  3. 3. Jak stworzyć filtr wyjątków przechwytujący WSZYSTKIE typy wyjątków (nie tylko HttpException)?

  4. 4. Jeśli zdefiniowano filtr na poziomie metody i kontrolera, który zostanie wykonany jako pierwszy?

Zadania praktyczne w grze

  • Edytor kodu

    Napisz RomanExceptionFilter z @Catch(HttpException), który zwraca JSON z polami: statusCode, imperium, error, path, timestamp

  • Układanie w pionie

    Uporządkuj poziomy bindowania Exception Filters od najwęższego do najszerszego zasięgu:

  • Klikanie w kolejności

    Ułóż elementy metody catch() filtra wyjątków w prawidłowej kolejności:

  • Edytor kodu

    Napisz AllExceptionsFilter z @Catch() (bez argumentów), który obsługuje zarówno HttpException, jak i inne błędy

  • Układanie w poziomie

    Ułóż elementy rzucenia wyjątku 404 w NestJS:

  1. PytanieWyjątek NotFoundException
  2. PytanieDekorator @Catch()
  3. Zadanie z kodemWłasny filtr wyjątków
  4. Ułóż w kolejnościPoziomy bindowania Exception Filters
  5. Kliknij w kolejnościStruktura metody catch w filtrze
  6. PytanieFiltr łapiący wszystkie wyjątki
  7. Zadanie z kodemFiltr łapiący wszystkie wyjątki
  8. Ułóż w kolejnościRzucenie wyjątku NotFoundException
  9. PytanieKolejność wykonania filtrów

Przydatne artykuły