Czym są filtry wyjątków?

Question

Accepted Answer

**Filtry wyjątków** dają Ci pełną kontrolę nad tym, jak błędy są **wychwytywane i transformowane w odpowiedzi**. Znajdują się na końcu cyklu życia żądania, wychwytując wyjątki rzucane gdziekolwiek w żądaniu i pozwalając Ci dostosować format odpowiedzi błędu, status i logowanie.

## Podstawowy filtr wyjątków

```ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";

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

// build a CUSTOM error response shape
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

Dekorator `@Catch()` określa, które typy wyjątków ten filtr obsługuje, a metoda `catch()` otrzymuje wyjątek wraz z kontekstem — pozwalając Ci stworzyć dowolną odpowiedź.

## Wychwytywanie WSZYSTKICH wyjątków (w tym non-HTTP)

```ts
@Catch()                                 // no argument = catch EVERYTHING
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // unknown errors → 500
    // log the full error internally, return a safe message to the client
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

Filtr z `@Catch()` (bez argumentu) obsługuje każdy wyjątek — miejsce do logowania nieoczekiwanych błędów i zapewnienia, że nawet błędy non-HTTP zwracają czystą, bezpieczną odpowiedź (bez ujawniania śladów stosu klientom).

## Stosowanie filtrów

```ts
@UseFilters(HttpExceptionFilter)         // method or controller level
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // GLOBAL — app-wide, most common
```

Filtry są zwykle stosowane **globalnie** w celu wymuszenia spójnego formatu błędu na całym API.

## Dlaczego używać filtrów wyjątków?

```text
✓ Consistent error response format across ALL endpoints (a standard shape)
✓ Centralized error LOGGING (log every error in one place)
✓ Handle non-HTTP errors safely (turn unexpected errors into clean 500s)
✓ Hide internal details from clients (no leaked stack traces — security)
✓ Add context (request path, timestamp, correlation IDs) to error responses
```

## Filtry vs rzucanie wyjątków

```text
Throwing exceptions (NotFoundException, etc.) → SIGNALS an error with a status
Exception filters → control HOW those errors are FORMATTED/logged into responses
→ You throw exceptions in your code; filters customize the resulting response globally.
```

## Dlaczego to ważne

Filtry wyjątków są ważną funkcją NestJS do budowania niezawodnych, profesjonalnych API z **spójnym, kontrolowanym obsługiwaniem błędów**.

Chociaż wbudowana warstwa wyjątków NestJS już zamienia rzucane wyjątki w odpowiedzi HTTP, filtry wyjątków dają Ci pełną kontrolę do dostosowania tego zachowania — co ma znaczenie dla kilku rzeczywistych problemów: wymuszania **spójnego kształtu odpowiedzi błędu** na każdym endpoincie (aby klienci zawsze otrzymywali błędy w tym samym formacie), **centralizacji logowania błędów** (przechwytywania każdego błędu w jednym miejscu zamiast rozrzuconego try/catch), bezpiecznego **obsługiwania nieoczekiwanych błędów non-HTTP** (konwertowania ich na czyste 500 zamiast awarii lub ujawniania szczegółów), i **bezpieczeństwa** (ukrywania wewnętrznych śladów stosu i wrażliwych szczegółów przed klientami przy jednoczesnym logowaniu ich wewnętrznie).

Globalny filtr "catch-all" w połączeniu z rzucaniem określonych wyjątków HTTP w kodzie jest standardowym wzorcem dla obsługi błędów na poziomie produkcji.

Rozumienie kiedy i jak używać filtrów (w stosunku do po prostu rzucania wyjątków) i ich stosowanie globalnie dla spójności jest cechą dobrze zbudowanych aplikacji NestJS i odzwierciedla dojrzałą praktykę back-end wokół często pomijanego, ale krytycznego problemu obsługi błędów.