Ce sunt filtrele de excepție?

Question

Accepted Answer

**Filtrele de excepție** îți dau control deplin asupra modului în care erorile sunt **capturate și transformate în răspunsuri**. Ele se află la sfârșitul ciclului de viață al cererii, capturând excepții aruncate oriunde în cerere și permițând personalizarea formatului răspunsului de eroare, stării și jurnalizării.

## Un filtru de excepție de bază

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

Decoratorul `@Catch()` specifică ce tipuri de excepții gestionează acest filtru, iar metoda `catch()` primește excepția plus contextul — permițând să creezi orice răspuns dorești.

## Capturarea TUTUROR excepțiilor (inclusiv 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: "..." });
  }
}
```

Un filtru cu `@Catch()` (fără argument) gestionează orice excepție — locul pentru a înregistra erorile neașteptate și a asigura că chiar și erorile non-HTTP returnează un răspuns curat și sigur (fără a dezv include stack traces către clienți).

## Aplicarea filtrelor

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

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

Filtrele sunt de obicei aplicate **global** pentru a impune un format de eroare consistent pe toată API-ul.

## De ce să folosești filtrele de excepție?

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

## Filtre vs aruncarea excepțiilor

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

## De ce contează

Filtrele de excepție sunt o caracteristică importantă a NestJS pentru construirea de API-uri robuste și profesionale cu **gestionarea erorilor consecventă și controlată**.

Deși stratul de excepție încorporat al NestJS transformează deja excepțiile aruncate în răspunsuri HTTP, filtrele de excepție îți dau control deplin pentru a personaliza acel comportament — ceea ce contează pentru mai multe preocupări reale: impunerea unei **forme de răspuns de eroare consecvente** pe fiecare endpoint (astfel încât clienții primesc întotdeauna erorile în același format), **centralizarea jurnalizării erorilor** (capturând orice eroare într-un singur loc în loc de a fi împrăștiate în try/catch), gestionarea sigură a **erorilor neașteptate non-HTTP** (convertindu-le în 500-uri curate în loc să se prăbușească sau să dezvăluie detalii), și **securitate** (ascundând stack traces interne și detalii sensibile de la clienți în timp ce le înregistrezi intern).

Un filtru global "catch-all" combinat cu aruncarea excepțiilor HTTP specifice în codul tău este modelul standard pentru gestionarea erorilor la nivel de producție.

Înțelegerea când și cum să folosești filtrele (versus a arunca pur și simplu excepții), și aplicarea lor global pentru consecvență, este o caracteristică a aplicațiilor NestJS bine construite și reflectă practica matură de back-end în jurul preocupării adesea neglijate dar critice a gestionării erorilor.