Kurs NestJS · Moduł 2: Routing i cykl żądania
Filtry wyjątków - sądy i trybunały imperium
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); // 418Kod 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:
- Filtr metody (jeśli istnieje) - sprawdzany jako pierwszy
- Filtr kontrolera (jeśli istnieje) - sprawdzany jako drugi
- 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. Jaki kod HTTP generuje rzucenie new NotFoundException() w NestJS?
2. Co oznacza dekorator @Catch(HttpException) na klasie filtru wyjątków?
3. Jak stworzyć filtr wyjątków przechwytujący WSZYSTKIE typy wyjątków (nie tylko HttpException)?
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:
Zadania po tej lekcji
- PytanieWyjątek NotFoundException
- PytanieDekorator @Catch()
- Zadanie z kodemWłasny filtr wyjątków
- Ułóż w kolejnościPoziomy bindowania Exception Filters
- Kliknij w kolejnościStruktura metody catch w filtrze
- PytanieFiltr łapiący wszystkie wyjątki
- Zadanie z kodemFiltr łapiący wszystkie wyjątki
- Ułóż w kolejnościRzucenie wyjątku NotFoundException
- PytanieKolejność wykonania filtrów