Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Créer un filtre d'exception personnalisé (@Catch)

Cette leçon apprend à écrire des filtres d'exception pour contrôler le format des réponses d'erreur. Trois filtres exécutés sont comparés : un filtre @Catch(HttpException) qui uniformise les erreurs H...

0 chapitres 0 QCM Accès gratuit
Créer un filtre d'exception personnalisé (@Catch)

À propos de ce cours

Cette leçon apprend à écrire des filtres d'exception pour contrôler le format des réponses d'erreur. Trois filtres exécutés sont comparés : un filtre @Catch(HttpException) qui uniformise les erreurs HTTP mais laisse les autres au filtre par défaut, un filtre @Catch() qui attrape tout, journalise les erreurs imprévues et masque leur détail, et un filtre limité à une classe d'erreur métier qui la traduit en statut 422. La leçon explique ArgumentsHost, les portées (méthode, contrôleur, global), APP_FILTER, l'ordre de sélection des filtres et les bonnes pratiques. Activités corrigées.

Objectifs de la leçon

  • Écrire un filtre d'exception avec ExceptionFilter et @Catch.
  • Utiliser ArgumentsHost pour accéder à la requête et à la réponse.
  • Choisir entre @Catch(HttpException), @Catch() et une classe précise.
  • Appliquer un filtre à une méthode, un contrôleur ou toute l'application.
  • Séparer les erreurs métier du protocole HTTP.
Pourquoi un filtre personnalisé ?

La leçon précédente l'a montré : selon la façon de lever l'exception, le corps change (avec ou sans error, message chaîne ou tableau, objet libre). Le client doit gérer plusieurs formats, et les erreurs 500 ne sont journalisées nulle part de façon utile. Un filtre d'exception reprend la main : il reçoit l'exception et construit lui-même la réponse.

Rôle des filtres d'exception

Le premier filtre dont @Catch correspond produit la réponse.

Structure d'un filtre
nest g filter common/filters/http-erreur --no-spec
@Catch(TypeDException)                     // quelles exceptions ce filtre traite
export class MonFilter implements ExceptionFilter {
  catch(exception: TypeDException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();      // contexte HTTP (il existe aussi WebSocket, microservices)
    const req = ctx.getRequest<Request>();
    const res = ctx.getResponse<Response>();
    res.status(…).json({ … });            // le filtre DOIT envoyer la réponse
  }
}

ArgumentsHost est une abstraction : NestJS fonctionne aussi avec les WebSockets et les microservices (chapitre 16). switchToHttp() donne accès aux objets d'Express.

Trois filtres

📄 src/common/filters/http-erreur.filter.ts

import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)                                    // n'attrape que les HttpException
export class HttpErreurFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const req = ctx.getRequest<Request>();
    const res = ctx.getResponse<Response>();
    const statut = exception.getStatus();
    const corps = exception.getResponse();               // chaîne ou objet passé à l'exception

    const message = typeof corps === 'string' ? corps : (corps as { message?: string | string[] }).message;

    res.status(statut).json({
      succes: false,
      statut,
      erreur: exception.name,
      message,
      chemin: req.originalUrl,
      methode: req.method,
      horodatage: new Date().toISOString(),
    });
  }
}

📄 src/common/filters/toutes-erreurs.filter.ts

import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus, Logger } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch()                                                 // sans argument : attrape TOUT
export class ToutesErreursFilter implements ExceptionFilter {
  private readonly logger = new Logger('Erreurs');

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const req = ctx.getRequest<Request>();
    const res = ctx.getResponse<Response>();

    const estHttp = exception instanceof HttpException;
    const statut = estHttp ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
    const corps = estHttp ? exception.getResponse() : null;
    const message = !estHttp
      ? 'Erreur interne du serveur'                      // ✓ on ne révèle jamais le détail au client
      : typeof corps === 'string' ? corps : (corps as { message?: string | string[] }).message;

    if (!estHttp) {
      // le détail complet va dans le journal du serveur
      console.log(`[Erreurs] ${req.method} ${req.originalUrl} → ${(exception as Error).message}`);
    }

    res.status(statut).json({ succes: false, statut, message, chemin: req.originalUrl, horodatage: new Date().toISOString() });
  }
}

📄 src/common/errors/regle-metier.error.ts

// Erreur MÉTIER indépendante de HTTP : le service ne connaît pas les codes de statut
export class RegleMetierError extends Error {
  constructor(public readonly code: string, message: string) {
    super(message);
    this.name = 'RegleMetierError';
  }
}

📄 src/common/filters/regle-metier.filter.ts

import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
import { Response } from 'express';
import { RegleMetierError } from './regle-metier.error';

@Catch(RegleMetierError)                                 // une classe d'erreur précise
export class RegleMetierFilter implements ExceptionFilter {
  catch(exception: RegleMetierError, host: ArgumentsHost) {
    host.switchToHttp().getResponse<Response>().status(HttpStatus.UNPROCESSABLE_ENTITY).json({
      succes: false,
      statut: 422,
      code: exception.code,
      message: exception.message,
    });
  }
}

📄 src/groupes.controller.ts

import {
  Controller, Get, NotFoundException, Param, ParseIntPipe, Post, UseFilters,
} from '@nestjs/common';
import { RegleMetierError } from './regle-metier.error';
import { RegleMetierFilter } from './regle-metier.filter';

@Controller('groupes')
export class GroupesController {
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    if (id !== 1) throw new NotFoundException(`Groupe ${id} introuvable`);
    return { id, code: 'DEV101' };
  }

  @Post(':id/inscriptions')
  @UseFilters(RegleMetierFilter)                         // filtre limité à cette route
  inscrire(@Param('id', ParseIntPipe) id: number) {
    throw new RegleMetierError('GROUPE_COMPLET', `Le groupe ${id} a atteint sa capacité maximale`);
  }

  @Get(':id/bug')
  bug() {
    throw new Error('ECONNREFUSED 127.0.0.1:3306');
  }
}
await appel('GET', '/api/groupes/1');
  await appel('GET', '/api/groupes/5');
  await appel('GET', '/api/groupes/abc');
  await appel('POST', '/api/groupes/1/inscriptions');
  await appel('GET', '/api/groupes/1/bug');
  await appel('GET', '/api/route-inconnue');
Avec le filtre global @Catch(HttpException)
app.useGlobalFilters(new HttpErreurFilter());   // main.ts

Résultat réellement obtenu :

GET /api/groupes/1 → 200 {"id":1,"code":"DEV101"}
GET /api/groupes/5 → 404 {"succes":false,"statut":404,"erreur":"NotFoundException","message":"Groupe 5 introuvable","chemin":"/api/groupes/5","methode":"GET","horodatage":"2026-11-15T07:12:27.297Z"}
GET /api/groupes/abc → 400 {"succes":false,"statut":400,"erreur":"BadRequestException","message":"Validation failed (numeric string is expected)","chemin":"/api/groupes/abc","methode":"GET","horodatage":"2026-11-15T07:12:27.299Z"}
POST /api/groupes/1/inscriptions → 422 {"succes":false,"statut":422,"code":"GROUPE_COMPLET","message":"Le groupe 1 a atteint sa capacité maximale"}
GET /api/groupes/1/bug → 500 {"statusCode":500,"message":"Internal server error"}
GET /api/route-inconnue → 404 {"succes":false,"statut":404,"erreur":"NotFoundException","message":"Cannot GET /api/route-inconnue","chemin":"/api/route-inconnue","methode":"GET","horodatage":"2026-11-15T07:12:27.305Z"}
  • Les erreurs HTTP (404 du service, 400 du pipe, 404 d'une route inconnue) ont toutes le nouveau format.
  • L'inscription renvoie 422 avec le format du RegleMetierFilter: le filtre de méthode passe avant le filtre global.
  • L'erreur technique (ECONNREFUSED) n'est pas une HttpException: HttpErreurFilter ne l'attrape pas, et c'est le filtre par défaut qui répond, avec l'ancien format. Le client reçoit donc deux formats d'erreur différents.
Avec le filtre global @Catch()
app.useGlobalFilters(new ToutesErreursFilter());   // main.ts

Résultat réellement obtenu :

GET /api/groupes/1 → 200 {"id":1,"code":"DEV101"}
GET /api/groupes/5 → 404 {"succes":false,"statut":404,"message":"Groupe 5 introuvable","chemin":"/api/groupes/5","horodatage":"2026-11-15T07:12:29.378Z"}
GET /api/groupes/abc → 400 {"succes":false,"statut":400,"message":"Validation failed (numeric string is expected)","chemin":"/api/groupes/abc","horodatage":"2026-11-15T07:12:29.381Z"}
POST /api/groupes/1/inscriptions → 422 {"succes":false,"statut":422,"code":"GROUPE_COMPLET","message":"Le groupe 1 a atteint sa capacité maximale"}
[Erreurs] GET /api/groupes/1/bug → ECONNREFUSED 127.0.0.1:3306
GET /api/groupes/1/bug → 500 {"succes":false,"statut":500,"message":"Erreur interne du serveur","chemin":"/api/groupes/1/bug","horodatage":"2026-11-15T07:12:29.386Z"}
GET /api/route-inconnue → 404 {"succes":false,"statut":404,"message":"Cannot GET /api/route-inconnue","chemin":"/api/route-inconnue","horodatage":"2026-11-15T07:12:29.388Z"}

Cette fois, toutes les erreurs ont le même format. L'erreur technique est journalisée côté serveur avec son vrai message ([Erreurs] … ECONNREFUSED 127.0.0.1:3306) et le client reçoit seulement « Erreur interne du serveur ». C'est la configuration recommandée pour un filtre global.

Les erreurs métier hors de HTTP

RegleMetierError hérite de Error, pas de HttpException: le service qui la lève ne connaît pas les codes de statut. C'est le filtre, à la frontière HTTP, qui la traduit en 422. Le même service pourrait être appelé depuis une tâche planifiée ou un microservice, où les statuts HTTP n'ont aucun sens. Cette séparation est appréciée dans les applications importantes ; dans une petite API, lever directement des HttpException depuis le service reste acceptable.

Portée et ordre des filtres
PortéeSyntaxe
Méthode@UseFilters(RegleMetierFilter) sur le handler
Contrôleur@UseFilters(RegleMetierFilter) sur la classe
Global, sans injectionapp.useGlobalFilters(new ToutesErreursFilter())
Global, avec injection{ provide: APP_FILTER, useClass: ToutesErreursFilter } dans les providers d'un module

Pour une exception, NestJS cherche d'abord parmi les filtres de la méthode, puis du contrôleur, puis les filtres globaux, et utilise le premier dont le @Catch() correspond. Un seul filtre traite donc une exception. Préférez passer la classe à @UseFilters() plutôt qu'une instance : NestJS réutilise alors la même instance et peut injecter ses dépendances.

Ce que les filtres n'attrapent pas: les exceptions levées dans un res.on('finish') ou dans un setTimeout (hors du traitement de la requête). Et un filtre ne doit jamais lever lui-même d'exception : il est la dernière étape.

Activités

Activité 1 Ajouter le statut textuel

Modifiez ToutesErreursFilter pour ajouter le champ erreur avec le nom du statut (Not Found, Bad Request…). Indice : http.STATUS_CODES de Node.js.

Voir le corrigé
import { STATUS_CODES } from 'node:http';

res.status(statut).json({
  succes: false,
  statut,
  erreur: STATUS_CODES[statut] ?? 'Erreur',
  message,
  chemin: req.originalUrl,
  horodatage: new Date().toISOString(),
});

Activité 2 Un filtre global avec injection

Enregistrez ToutesErreursFilter avec APP_FILTER au lieu de useGlobalFilters. Quel avantage, si le filtre doit envoyer une alerte par un AlertesService lors d'une erreur 500 ?

Voir le corrigé
@Module({
  providers: [
    AlertesService,
    { provide: APP_FILTER, useClass: ToutesErreursFilter },
  ],
})
export class AppModule {}

@Catch()
export class ToutesErreursFilter implements ExceptionFilter {
  constructor(private readonly alertes: AlertesService) {}
  // … this.alertes.signaler(exception) pour les erreurs non HTTP
}

Avec APP_FILTER, le filtre est créé par le conteneur : AlertesService est injecté. Avec useGlobalFilters(new …), il faudrait construire soi-même le service.

Activité 3 Traduire plusieurs erreurs métier

Vous avez RessourceIntrouvableError, RegleMetierError et DoublonError, trois classes métier. Écrivez un seul filtre qui les traduit respectivement en 404, 422 et 409.

Voir le corrigé
const STATUTS = new Map<Function, number>([
  [RessourceIntrouvableError, 404],
  [RegleMetierError, 422],
  [DoublonError, 409],
]);

@Catch(RessourceIntrouvableError, RegleMetierError, DoublonError)   // plusieurs classes
export class ErreursMetierFilter implements ExceptionFilter {
  catch(exception: Error, host: ArgumentsHost) {
    const statut = STATUTS.get(exception.constructor) ?? 500;
    host.switchToHttp().getResponse<Response>().status(statut).json({ succes: false, statut, message: exception.message });
  }
}

Activité 4 Ordre des filtres

Un contrôleur porte @UseFilters(HttpErreurFilter) et l'application a un filtre global ToutesErreursFilter. Quel filtre répond pour (a) une NotFoundException; (b) une TypeError?

Voir le corrigé

(a) HttpErreurFilter, celui du contrôleur, plus proche que le filtre global, et dont le @Catch(HttpException) correspond. (b) ToutesErreursFilter: le filtre du contrôleur ne correspond pas (une TypeError n'est pas une HttpException), NestJS passe donc au filtre global.

À retenir

  • Un filtre implémente ExceptionFilter.catch(exception, host) et envoie lui-même la réponse.
  • @Catch(HttpException) : erreurs HTTP seulement ; @Catch() : tout ; @Catch(A, B) : classes précises.
  • Un filtre global @Catch() garantit un format unique et journalise les erreurs imprévues sans les révéler.
  • Portées : méthode, contrôleur, global (useGlobalFilters ou APP_FILTER avec injection).
  • Le filtre le plus proche dont @Catch correspond traite l'exception, et lui seul.

Cet article vous a-t-il aidé ?