Kurs NestJS · Moduł 6: Obsługa błędów i monitoring
Exception Filters - zarządzanie kryzysami
W tej lekcji7
Legionista pyta o legion, którego nie ma. Zamiast czytelnej odmowy dostaje ścianę tekstu: nazwę klasy błędu, ślad stosu, ścieżki plików z Twojego serwera. Kolejny endpoint zwraca w podobnej sytuacji zupełnie inny kształt odpowiedzi, bo ktoś obsłużył błąd ręcznie. Klient nie wie, czego się spodziewać, a Ty właśnie pokazałeś światu budowę swojego obozu.
Rzym miał na kryzysy osobny urząd. Gdy w prowincji coś zawiodło, meldunek nie szedł do Senatu w postaci, w jakiej przyszedł z pola - urzędnik przepisywał go na jednolity formularz. W NestJS tym urzędnikiem jest Exception Filter.
Czym jest, a czym nie jest
Exception Filter to klasa przechwytująca wyjątki i formatująca odpowiedź błędu. To jedyne jego zadanie i warto je odgraniczyć od sąsiadów, bo wszystkie cztery elementy stoją na drodze żądania:
- Middleware działa najwcześniej, na surowym żądaniu, zanim NestJS wie, dokąd ono trafi.
- Guard decyduje, czy wpuścić - zwraca
truealbofalse. - Pipe waliduje i przekształca dane wejściowe.
- Exception Filter wkracza jako ostatni, dopiero gdy coś poszło nie tak, i decyduje, co zobaczy klient.
Trzy pierwsze pracują na drodze do metody kontrolera. Filtr pracuje na drodze powrotnej, i to tylko wtedy, gdy w tej drodze padł wyjątek.
@Catch - wybór, czym się zajmujemy
Filtr zaczyna się od dekoratora mówiącego, jakie wyjątki obsługuje:
@Catch(HttpException)
export class LegionHttpExceptionFilter 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();
response.status(status).json({
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
message: exception.message,
});
}
}@Catch(HttpException) zawęża filtr do jednego typu wyjątku - ten obsłuży tylko wyjątki HTTP, a wszystko inne przepuści dalej. Sam dekorator bez argumentu, @Catch(), złapałby absolutnie wszystko; to przydaje się dla filtra ostatniej szansy, ale wtedy tracisz informację o typie.
Metoda catch przyjmuje dwa argumenty. Pierwszy to sam wyjątek. Drugi, host typu ArgumentsHost, jest ciekawszy: NestJS obsługuje nie tylko HTTP, ale też WebSockety i mikroserwisy, więc host trzyma kontekst w postaci niezależnej od protokołu. host.switchToHttp() pobiera z niego kontekst HTTP, dając dostęp do obiektów Request i Response. Nie przełącza żadnego protokołu - jedynie mówi "potraktuj ten kontekst jako HTTP".
Pięć kroków obsługi
Powyższy kod wykonuje zawsze tę samą sekwencję i warto ją znać jako całość:
- Przechwycenie wyjątku w metodzie
catch(). - Pobranie kontekstu HTTP przez
switchToHttp(). - Odczytanie statusu i danych wyjątku -
exception.getStatus(). - Sformatowanie odpowiedzi JSON - jednolity kształt dla całej aplikacji.
- Wysłanie odpowiedzi do klienta przez
response.status(...).json(...).
Zwróć uwagę, czego w tej odpowiedzi nie ma: śladu stosu ani nazw plików. To celowe - stos loguj po stronie serwera, klientowi wysyłaj tylko to, co pomoże mu poprawić żądanie. Dodane timestamp i path kosztują nic, a przy zgłoszeniu błędu od użytkownika oszczędzają godzinę szukania.
Kody HTTP - język odmowy
Pole statusCode niesie najważniejszą informację, więc dobierz je świadomie:
- 400 Bad Request - żądanie jest źle zbudowane, klient musi je poprawić.
- 401 Unauthorized - nie wiadomo, kim jesteś; zaloguj się.
- 403 Forbidden - wiadomo, kim jesteś, i nie wolno Ci.
- 404 Not Found - zasobu nie znaleziono.
- 500 Internal Server Error - zawiódł serwer, nie klient.
Granica między 4xx a 5xx jest tu istotna: czwórki mówią „popraw żądanie", piątki mówią „to nasza wina". Zwracanie 500 przy błędnych danych wejściowych wysyła klienta na poszukiwanie usterki, której u niego nie ma.
Zasięg - gdzie postawić urzędnika
Ten sam filtr można umieścić na trzech poziomach, od najwęższego do najszerszego:
// 1. Na metodzie kontrolera - najwęziej
@Get(':id')
@UseFilters(LegionHttpExceptionFilter)
findOne(@Param('id') id: string) { }
// 2. Na klasie kontrolera - wszystkie jego metody
@Controller('legions')
@UseFilters(LegionHttpExceptionFilter)
export class LegionsController { }
// 3. Globalnie - cała aplikacja
app.useGlobalFilters(new LegionHttpExceptionFilter());Reguła jest prosta: im niżej postawisz filtr, tym węższy jego zasięg. Filtr na metodzie obsłuży tylko ją, na klasie - wszystkie metody kontrolera, globalny - całą aplikację.
Zapamiętaj tę kolejność, bo wraca przy guardach, pipe'ach i interceptorach - w NestJS wszystkie cztery stosuje się tak samo. W praktyce jeden filtr globalny nadaje wspólny kształt odpowiedzi, a filtry węższe dokładają obsługę specyficzną dla wycinka aplikacji.
Jeden filtr, kilka typów wyjątków
@Catch przyjmuje wiele typów naraz - przydaje się, gdy pochodzą z jednego źródła i wymagają podobnej obsługi:
@Catch(QueryFailedError, EntityNotFoundError)
export class DatabaseExceptionFilter implements ExceptionFilter {
catch(exception: Error, host: ArgumentsHost) {
const response = host.switchToHttp().getResponse<Response>();
const status =
exception instanceof EntityNotFoundError
? HttpStatus.NOT_FOUND
: HttpStatus.BAD_REQUEST;
response.status(status).json({
statusCode: status,
message:
status === HttpStatus.NOT_FOUND
? 'Nie znaleziono zasobu'
: 'Nieprawidłowe zapytanie do bazy danych',
});
}
}Oba wyjątki pochodzą z TypeORM, ale znaczą co innego, więc wewnątrz catch rozróżniamy je przez instanceof. EntityNotFoundError to 404 - klient poprosił o coś, czego nie ma. QueryFailedError to 400, bo zwykle wynika z danych, które klient przysłał.
I tu widać drugą wartość filtra, poza jednolitym kształtem: tłumaczy wyjątki wewnętrzne na język HTTP. Klient nie musi wiedzieć, że używasz TypeORM - dostaje kod i komunikat, które coś dla niego znaczą. Trzymaj się tej granicy: nazwy klas wyjątków z Twojego kodu nie powinny nigdy wyjść na zewnątrz.
Podsumowanie
Urząd kryzysowy działa, meldunki mają jeden formularz:
- Exception Filter to klasa przechwytująca wyjątki i formatująca odpowiedź błędu - nie Middleware, nie Guard, nie Pipe,
- trzy tamte pracują na drodze do kontrolera, filtr - na powrotnej i tylko po wyjątku,
@Catch(TypWyjatku)zawęża filtr do wskazanego typu;@Catch()bez argumentu łapie wszystko,host.switchToHttp()pobiera kontekst HTTP zArgumentsHost, dając dostęp doRequestiResponse- niczego nie przełącza,- pięć kroków: przechwyć, pobierz kontekst, odczytaj status, sformatuj JSON, wyślij,
- do klienta nie wysyłaj śladu stosu;
timestampipathw odpowiedzi oszczędzą Ci później czasu, - 404 to „nie znaleziono zasobu"; 4xx znaczy „popraw żądanie", 5xx - „to nasza wina",
- zasięg od najwęższego:
@UseFiltersna metodzie,@UseFiltersna klasie,app.useGlobalFilters()globalnie, @Catchprzyjmuje wiele typów; wewnątrz rozróżniasz je przezinstanceofi mapujesz na właściwe kody HTTP,- filtr tłumaczy wyjątki wewnętrzne na język HTTP - nazwy Twoich klas nie powinny wychodzić na zewnątrz.
W następnej lekcji nauczysz się tworzyć własne wyjątki, żeby mieć co przechwytywać - z czytelną hierarchią zamiast garści throw new Error. A na razie zapamiętaj: filtr to urzędnik przepisujący meldunek na jednolity formularz - klient dostaje kod i komunikat, a budowa obozu zostaje w obozie.
Kod do tej lekcji: src/filters/exception-filters.ts
// Exception Filters - Zarzadzanie Kryzysami w Imperium
// Przechwytywanie i formatowanie bledow
import {
ExceptionFilter,
Catch,
ArgumentsHost,
HttpException,
HttpStatus,
Logger,
} from '@nestjs/common';
import { Request, Response } from 'express';
// ===========================================
// 1. Podstawowy HttpException Filter
// ===========================================
@Catch(HttpException)
export class LegionHttpExceptionFilter implements ExceptionFilter {
private logger = new Logger('LegionExceptionFilter');
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const request = ctx.getRequest<Request>();
const status = exception.getStatus();
const exceptionResponse = exception.getResponse();
// Formatowanie odpowiedzi bledow - styl Imperium
const errorResponse = {
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
method: request.method,
message: typeof exceptionResponse === 'string'
? exceptionResponse
: (exceptionResponse as any).message,
error: HttpStatus[status] || 'Unknown Error',
};
this.logger.error(
'Kryzys [' + status + '] ' + request.method + ' ' + request.url
+ ': ' + errorResponse.message
);
response.status(status).json(errorResponse);
}
}
// ===========================================
// 2. Globalny filter - lapie WSZYSTKIE wyjatki
// ===========================================
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
private logger = new Logger('AllExceptions');
catch(exception: unknown, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const request = ctx.getRequest<Request>();
const status = exception instanceof HttpException
? exception.getStatus()
: HttpStatus.INTERNAL_SERVER_ERROR;
const message = exception instanceof Error
? exception.message
: 'Nieznany blad w systemie Imperium';
this.logger.error('KRYTYCZNY BLAD: ' + message);
response.status(status).json({
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
message: message,
});
}
}
// ===========================================
// 3. Rejestracja filtrow
// ===========================================
// Globalnie w main.ts:
// app.useGlobalFilters(new AllExceptionsFilter());
//
// Na kontrolerze:
// @UseFilters(new LegionHttpExceptionFilter())
//
// Na metodzie:
// @UseFilters(LegionHttpExceptionFilter)
console.log('=== Exception Filters ===');
console.log('@Catch(HttpException) - lapie konkretny typ');
console.log('@Catch() - lapie WSZYSTKIE wyjatki');
console.log('host.switchToHttp() - kontekst HTTP');
console.log('Rejestracja: global, controller, method');
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 jest Exception Filter w NestJS?
2. Co robi dekorator @Catch(HttpException) na klasie filtra?
To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Uzupełnij klasę LegionHttpExceptionFilter z @Catch(HttpException), która implementuje ExceptionFilter z metodą catch(exception, host), pobiera response i request z ArgumentsHost i zwraca JSON z statusCode, timestamp, path i message
- Klikanie w kolejności
Ułóż elementy obsługi wyjątku w Exception Filter w poprawnej kolejności
- Układanie w pionie
Uporządkuj poziomy aplikowania Exception Filter od najwęższego do najszerszego zasięgu
- Edytor kodu
Uzupełnij DatabaseExceptionFilter z @Catch(QueryFailedError, EntityNotFoundError), który w catch() rozróżnia typ wyjątku i zwraca odpowiedni kod HTTP (400 dla QueryFailed, 404 dla EntityNotFound)
Zadania po tej lekcji
- PytanieCzym jest Exception Filter?
- PytanieDekorator @Catch w Exception Filter
- Zadanie z kodemPodstawowy HttpExceptionFilter
- PytanieMetoda host.switchToHttp()
- Kliknij w kolejnościElementy odpowiedzi błędu
- Ułóż w kolejnościPoziomy aplikowania Exception Filter
- PytanieKody błędów HTTP
- Zadanie z kodemDatabaseExceptionFilter