Co jsou filtry výjimek?

Question

Accepted Answer

**Filtry výjimek** vám dávají plnou kontrolu nad tím, jak jsou chyby **zachyceny a transformovány na odpovědi**. Nacházejí se na konci životního cyklu požadavku, zachycují výjimky vyhodené kdekoli v požadavku a umožňují vám přizpůsobit formát chybové odpovědi, stav a protokolování.

## Základní filtr výjimek

```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,
    });
  }
}
```

Dekorátor `@Catch()` určuje, které typy výjimek tento filtr zpracovává, a metoda `catch()` přijímá výjimku spolu s kontextem — což vám umožňuje vytvořit jakoukoliv odpověď, kterou chcete.

## Zachycení VŠECH výjimek (včetně 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 s `@Catch()` (bez argumentu) zpracovává každou výjimku — ideální místo pro protokolování neočekávaných chyb a zajištění, aby i non-HTTP chyby vrátily čistou, bezpečnou odpověď (bez úniku stackových tras klientům).

## Aplikace filtrů

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

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

Filtry jsou obvykle aplikovány **globálně**, aby se prosadil konzistentní formát chyb v celém API.

## Proč používat filtry výjimek?

```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. vyhodání výjimek

```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.
```

## Proč je to důležité

Filtry výjimek jsou důležitou funkcí NestJS pro vytváření robustních, profesionálních API s **konzistentním, kontrolovaným zpracováním chyb**.

Zatímco vestavěná vrstva výjimek v NestJS již převádí vyhodené výjimky na HTTP odpovědi, filtry výjimek vám dávají plnou kontrolu k přizpůsobení tohoto chování — což je důležité pro několik reálných problémů: vynucení **konzistentního formátu chybové odpovědi** v každém endpointu (aby klienti vždy získali chyby ve stejném formátu), **centralizaci protokolování chyb** (zachycení každé chyby na jednom místě místo rozptýleného try/catch), bezpečné **zpracování neočekávaných non-HTTP chyb** (jejich převod na čisté 500 místo zhroucení nebo úniku detailů), a **bezpečnost** (skrytí interních stackových tras a citlivých detailů před klienty při jejich interním protokolování).

Globální filtr "catch-all" kombinovaný s vyhodáváním specifických HTTP výjimek v kódu je standardní vzor pro zpracování chyb na úrovni produkce.

Porozumění tomu, kdy a jak používat filtry (versus jednoduše vyhodávat výjimky), a jejich globální aplikace pro konzistenci, je charakteristikou dobře navržených aplikací NestJS a odráží zralou praxi vývoje backendu kolem často přehlížené, ale kritické záležitosti zpracování chyb.