Cosa sono i filtri di eccezione?

Question

Accepted Answer

**I filtri di eccezione** ti danno il pieno controllo su come gli errori vengono **catturati e trasformati in risposte**. Si collocano alla fine del ciclo di vita della richiesta, catturando le eccezioni lanciate ovunque nella richiesta e permettendoti di personalizzare il formato della risposta di errore, lo stato e la registrazione.

## Un filtro di eccezione di base

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

Il decoratore `@Catch()` specifica quali tipi di eccezione questo filtro gestisce, e il metodo `catch()` riceve l'eccezione più il contesto — permettendoti di creare qualsiasi risposta desideri.

## Catturare TUTTE le eccezioni (incluse quelle 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 filtro con `@Catch()` (senza argomenti) gestisce ogni eccezione — il posto per registrare gli errori inaspettati e garantire che persino gli errori non-HTTP restituiscano una risposta pulita e sicura (senza esporre stack trace ai client).

## Applicare filtri

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

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

I filtri solitamente vengono applicati **globalmente** per far rispettare un formato di errore coerente su tutta l'API.

## Perché usare i filtri di eccezione?

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

## Filtri vs lancio di eccezioni

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

## Perché è importante

I filtri di eccezione sono una caratteristica importante di NestJS per costruire API robuste e professionali con **una gestione degli errori coerente e controllata**.

Sebbene lo strato di eccezione integrato di NestJS trasformi già le eccezioni lanciate in risposte HTTP, i filtri di eccezione ti danno il pieno controllo per personalizzare quel comportamento — cosa che importa per diverse preoccupazioni concrete: far rispettare una **forma di risposta di errore coerente** su ogni endpoint (così i client ricevano sempre gli errori nello stesso formato), **centralizzare la registrazione degli errori** (catturando ogni errore in un unico posto piuttosto che sparso in try/catch), gestire in sicurezza **errori non-HTTP inaspettati** (convertendoli in 500 puliti anziché causare crash o esporre dettagli), e **sicurezza** (nascondendo gli stack trace interni e i dettagli sensibili dai client mentre li registri internamente).

Un filtro "catch-all" globale combinato con il lancio di eccezioni HTTP specifiche nel tuo codice è il pattern standard per la gestione degli errori di livello produzione.

Comprendere quando e come usare i filtri (versus semplicemente lanciare eccezioni), e applicarli globalmente per coerenza, è un marchio distintivo delle applicazioni NestJS ben costruite e riflette una pratica back-end matura intorno alla preoccupazione spesso trascurata ma critica della gestione degli errori.