Que sont les filtres d'exceptions ?

Question

Accepted Answer

**Les filtres d'exceptions** vous donnent un contrôle total sur la façon dont les erreurs sont **capturées et transformées en réponses**. Ils se situent à la fin du cycle de vie de la requête, capturant les exceptions levées n'importe où dans la requête et vous permettant de personnaliser le format de la réponse d'erreur, le statut et la journalisation.

## Un filtre d'exception basique

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

Le décorateur `@Catch()` spécifie les types d'exceptions que ce filtre gère, et la méthode `catch()` reçoit l'exception ainsi que le contexte — vous permettant de créer n'importe quelle réponse que vous souhaitez.

## Capturer TOUTES les exceptions (y compris les 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 filtre avec `@Catch()` (sans argument) gère chaque exception — l'endroit où journaliser les erreurs inattendues et s'assurer que même les erreurs non-HTTP retournent une réponse propre et sûre (sans divulguer les traces de pile aux clients).

## Appliquer des filtres

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

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

Les filtres sont généralement appliqués **globalement** pour imposer un format d'erreur cohérent sur toute l'API.

## Pourquoi utiliser les filtres d'exceptions ?

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

## Filtres vs lever des exceptions

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

## Pourquoi c'est important

Les filtres d'exceptions sont une fonctionnalité importante de NestJS pour construire des APIs robustes et professionnelles avec une **gestion des erreurs cohérente et contrôlée**.

Bien que la couche d'exception intégrée de NestJS transforme déjà les exceptions levées en réponses HTTP, les filtres d'exceptions vous donnent un contrôle total pour personnaliser ce comportement — ce qui compte pour plusieurs préoccupations réelles : imposer une **forme de réponse d'erreur cohérente** sur chaque endpoint (afin que les clients reçoivent toujours les erreurs dans le même format), **centraliser la journalisation des erreurs** (capturer chaque erreur en un seul endroit plutôt que dispersée dans des try/catch), gérer en toute sécurité les **erreurs non-HTTP inattendues** (les convertir en 500 propres au lieu de s'arrêter ou de divulguer des détails), et **sécurité** (masquer les traces de pile internes et les détails sensibles des clients tout en les journalisant en interne).

Un filtre « attrape-tout » global combiné à lever des exceptions HTTP spécifiques dans votre code est le modèle standard pour la gestion des erreurs au niveau de la production.

Comprendre quand et comment utiliser les filtres (par rapport à simplement lever des exceptions) et les appliquer globalement pour la cohérence est une caractéristique des applications NestJS bien construites et reflète une pratique mature du back-end autour de la préoccupation souvent négligée mais critique de la gestion des erreurs.