À propos de ce cours
Objectifs de la leçon
- Expliquer le rôle d'un middleware et sa place dans le traitement d'une requête.
- Écrire un middleware de classe et un middleware fonctionnel.
- Enregistrer des middlewares avec MiddlewareConsumer (forRoutes, exclude).
- Éviter les pièges : next() oublié, syntaxe des routes de NestJS 11.
- Savoir quand préférer un guard ou un intercepteur.
Les « couches » d'une requête NestJS
Ce chapitre présente les outils qui s'intercalent entre la requête et votre handler : middlewares, guards, intercepteurs, pipes (chapitre 08) et filtres d'exception. Chacun a un rôle précis. Le premier à agir est le middleware.
Un middleware est une fonction appelée avant le routage, avec l'objet requête (req), l'objet réponse (res) et une fonction next() qui passe la main au suivant. C'est exactement la notion de middleware d'Express (chapitre 02), que NestJS reprend.
Chaque middleware fait son travail puis appelle next().
1. Un middleware de classe : la journalisation
nest g middleware common/middlewares/journal --no-spec
📄 src/common/middlewares/journal.middleware.ts
import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
import { NextFunction, Request, Response } from 'express';
@Injectable()
export class JournalMiddleware implements NestMiddleware {
private readonly logger = new Logger('HTTP');
use(req: Request, res: Response, next: NextFunction) {
const debut = Date.now();
const { method, originalUrl } = req;
res.on('finish', () => { // quand la réponse est envoyée
const duree = Date.now() - debut;
console.log(`[HTTP] ${method} ${originalUrl} ${res.statusCode} - ${duree} ms`);
});
next(); // ✓ indispensable : passer à la suite
}
}
- La classe implémente
NestMiddlewareet sa méthodeuse(req, res, next). - Elle est
@Injectable(): elle peut recevoir des dépendances (un service de configuration, par exemple). - Pour connaître le statut et la durée, on attend l'événement
finishde la réponse, émis quand elle a été envoyée.
2. Un middleware fonctionnel : l'identifiant de corrélation
Quand un middleware n'a besoin d'aucune dépendance, une simple fonction suffit. Celui-ci attribue à chaque requête un identifiant unique (ou reprend celui envoyé par le client), qui permettra de retrouver toutes les lignes de journal d'une même requête :
📄 src/common/middlewares/correlation.middleware.ts
import { NextFunction, Request, Response } from 'express';
import { randomUUID } from 'node:crypto';
// Middleware FONCTIONNEL : une simple fonction, sans classe ni dépendance
export function correlation(req: Request, res: Response, next: NextFunction) {
const recu = req.header('x-correlation-id');
const id = recu && recu.length <= 64 ? recu : randomUUID();
req.headers['x-correlation-id'] = id; // disponible pour la suite du traitement
res.setHeader('X-Correlation-Id', id); // renvoyé au client
next();
}
3. Un middleware qui bloque : la maintenance
📄 src/common/middlewares/maintenance.middleware.ts
import { Injectable, NestMiddleware, ServiceUnavailableException } from '@nestjs/common';
import { NextFunction, Request, Response } from 'express';
@Injectable()
export class MaintenanceMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
if (process.env.MAINTENANCE === '1') {
throw new ServiceUnavailableException('API en maintenance, réessayez dans quelques minutes');
}
next();
}
}
Un middleware peut terminer la requête lui-même : ici en levant une exception HTTP, que NestJS transforme en réponse 503.
Enregistrer les middlewares
Les middlewares ne se déclarent pas dans @Module(): le module implémente NestModule et sa méthode configure() reçoit un MiddlewareConsumer.
📄 src/app.module.ts
import { MiddlewareConsumer, Module, NestModule, RequestMethod } from '@nestjs/common';
import { correlation } from './correlation.middleware';
import { JournalMiddleware } from './journal.middleware';
import { MaintenanceMiddleware } from './maintenance.middleware';
import { SanteController, StagiairesController } from './stagiaires.controller';
@Module({ controllers: [StagiairesController, SanteController] })
export class AppModule implements NestModule {
configure(consumer: MiddlewareConsumer) {
consumer
.apply(correlation, JournalMiddleware) // dans cet ordre
.forRoutes('{*splat}'); // toutes les routes (syntaxe NestJS 11)
consumer
.apply(MaintenanceMiddleware)
.exclude({ path: 'sante', method: RequestMethod.GET }) // sauf la route de santé
.forRoutes('{*splat}');
}
}
📄 src/stagiaires.controller.ts
import { Controller, Get, Headers, Param, ParseIntPipe, Post } from '@nestjs/common';
@Controller('stagiaires')
export class StagiairesController {
@Get()
findAll(@Headers('x-correlation-id') correlation: string) {
return { correlation, stagiaires: ['Ben Ali', 'Trabelsi'] };
}
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
return { id };
}
@Post()
creer() {
return { cree: true };
}
}
@Controller('sante')
export class SanteController {
@Get()
sante() {
return { statut: 'ok' };
}
}
await appel('GET', '/api/stagiaires', { entetes: { 'x-correlation-id': 'req-42' }, voir: ['x-correlation-id'] });
await appel('GET', '/api/stagiaires/7', { voir: ['x-correlation-id'] });
await appel('GET', '/api/stagiaires/abc');
await appel('GET', '/api/inconnue');
process.env.MAINTENANCE = '1';
console.log('--- MAINTENANCE=1');
await appel('POST', '/api/stagiaires');
await appel('GET', '/api/stagiaires');
await appel('GET', '/api/sante');
Résultat réellement obtenu :
[HTTP] GET /api/stagiaires 200 - 5 ms
GET /api/stagiaires → 200 {"correlation":"req-42","stagiaires":["Ben Ali","Trabelsi"]} [x-correlation-id: req-42]
[HTTP] GET /api/stagiaires/7 200 - 1 ms
GET /api/stagiaires/7 → 200 {"id":7} [x-correlation-id: 5465a8f5-637c-4973-bbb2-83c903f6b6a6]
[HTTP] GET /api/stagiaires/abc 400 - 1 ms
GET /api/stagiaires/abc → 400 {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
[HTTP] GET /api/inconnue 404 - 0 ms
GET /api/inconnue → 404 {"message":"Cannot GET /api/inconnue","error":"Not Found","statusCode":404}
--- MAINTENANCE=1
[HTTP] POST /api/stagiaires 503 - 0 ms
POST /api/stagiaires → 503 {"message":"API en maintenance, réessayez dans quelques minutes","error":"Service Unavailable","statusCode":503}
[HTTP] GET /api/stagiaires 503 - 1 ms
GET /api/stagiaires → 503 {"message":"API en maintenance, réessayez dans quelques minutes","error":"Service Unavailable","statusCode":503}
[HTTP] GET /api/sante 200 - 0 ms
GET /api/sante → 200 {"statut":"ok"}
Ce qu'il faut observer
- Le client qui envoie
x-correlation-id: req-42retrouve cet identifiant dans la réponse et le handler le lit dans les en-têtes ; sans en-tête, un UUID est généré. - Le journal enregistre toutes les requêtes, y compris les erreurs 400 (pipe) et 404 (route inexistante) : les middlewares s'exécutent avant le routage.
- En maintenance, toutes les routes répondent 503, sauf
GET /api/sante, exclue avecexclude().
Les options de MiddlewareConsumer
| Écriture | Effet |
|---|---|
.apply(A, B, C) | plusieurs middlewares, exécutés dans cet ordre |
.forRoutes('{*splat}') | toutes les routes (syntaxe NestJS 11) |
.forRoutes('stagiaires') | un chemin (sans le préfixe global) |
.forRoutes({ path: 'stagiaires', method: RequestMethod.POST }) | un chemin et une méthode HTTP |
.forRoutes(StagiairesController) | toutes les routes d'un contrôleur |
.exclude({ path: 'sante', method: RequestMethod.GET }) | sauf ces routes |
app.use(maFonction) dans main.ts | middleware global (fonctionnel uniquement, pas d'injection) |
NestJS 11 : n'écrivez plus forRoutes('*'). NestJS 11 utilise Express 5 et une nouvelle version de path-to-regexp, où l'étoile seule n'est plus valide. Le code fonctionne encore, mais affiche cet avertissement au démarrage :
WARN [LegacyRouteConverter] Unsupported route path: "/api/*". In previous versions, the symbols ?, *, and + were used to denote optional or repeating path parameters. The latest version of "path-to-regexp" now requires the use of named parameters. For example, instead of using a route like /users/* to capture all routes starting with "/users", you should use /users/*path. For more details, refer to the migration guide. Attempting to auto-convert to "/api/{*path}"...
Écrivez forRoutes('{*splat}') (le nom splat est libre) : c'est le joker nommé et facultatif, qui correspond aussi à la racine. Beaucoup de tutoriels plus anciens utilisent encore '*'.
Le piège du next() oublié
import { Injectable, NestMiddleware } from '@nestjs/common';
import { NextFunction, Request, Response } from 'express';
@Injectable()
export class OubliMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
console.log('middleware exécuté… mais next() oublié');
// next();
}
}
Résultat réellement obtenu :
middleware exécuté… mais next() oublié
aucune réponse après 2 s : la requête est bloquée
Sans next() (et sans réponse envoyée), la requête reste suspendue: le client attend jusqu'à l'expiration de son délai. Aucun message d'erreur n'apparaît côté serveur, ce qui rend ce bug difficile à trouver. Tout chemin d'un middleware doit se terminer par next(), par une exception, ou par l'envoi d'une réponse.
Middleware ou autre chose ?
Le middleware ne sait pas quel handler va traiter la requête, ne lit pas les métadonnées (@Roles) et ne voit pas la valeur renvoyée. Il convient pour ce qui concerne toutes les requêtes de façon uniforme : journal, identifiant de corrélation, CORS, compression, en-têtes de sécurité (helmet, chapitre 19), limitation de débit simple. Pour décider si l'utilisateur a le droit d'exécuter une route, on utilise un guard (leçon 9.4) ; pour transformer la réponse, un intercepteur (leçon 9.5).
Activités
Activité 1 Un journal plus complet
Modifiez JournalMiddleware pour afficher aussi l'adresse IP du client (req.ip), la taille de la réponse (en-tête content-length) et l'agent utilisateur. Utilisez Logger avec le niveau warn pour les statuts 4xx et error pour les 5xx.
Voir le corrigé
res.on('finish', () => {
const ligne = `${method} ${originalUrl} ${res.statusCode} ${res.get('content-length') ?? 0}o - ${Date.now() - debut} ms - ${req.ip} - ${req.get('user-agent') ?? ''}`;
if (res.statusCode >= 500) this.logger.error(ligne);
else if (res.statusCode >= 400) this.logger.warn(ligne);
else this.logger.log(ligne);
});
Activité 2 Restreindre un middleware
Écrivez un middleware LectureSeuleMiddleware qui répond 405 (MethodNotAllowedException) à toute requête qui n'est pas un GET quand la variable d'environnement LECTURE_SEULE=1. Appliquez-le à StagiairesController et NotesController seulement.
Voir le corrigé
@Injectable()
export class LectureSeuleMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
if (process.env.LECTURE_SEULE === '1' && req.method !== 'GET') {
throw new MethodNotAllowedException('API en lecture seule');
}
next();
}
}
// configure()
consumer.apply(LectureSeuleMiddleware).forRoutes(StagiairesController, NotesController);
Activité 3 Trouver le bug
Ce middleware fonctionne pour les requêtes avec en-tête, mais les autres restent bloquées. Pourquoi ?
use(req: Request, res: Response, next: NextFunction) {
const langue = req.header('accept-language');
if (langue) {
req.headers['x-langue'] = langue.slice(0, 2);
next();
}
}
Voir le corrigé
next() n'est appelé que dans le if. Sans en-tête Accept-Language, la fonction se termine sans réponse ni next(): la requête reste suspendue. Il faut placer next() après le if.
Activité 4 Middleware global
Activez le middleware fonctionnel correlation pour toute l'application avec app.use(correlation) dans main.ts. Pourquoi ne peut-on pas faire de même avec JournalMiddleware s'il injecte un service ?
Voir le corrigé
app.use() reçoit une fonction et l'enregistre directement auprès d'Express, hors du conteneur de NestJS. On pourrait écrire app.use(new JournalMiddleware().use), mais NestJS ne pourrait pas injecter ses dépendances (et this serait perdu). Pour un middleware avec dépendances, on utilise configure() et forRoutes('{*splat}').
À retenir
- Un middleware s'exécute avant le routage, avec req, res et next().
- Classe (NestMiddleware, injection possible) ou simple fonction.
- Enregistrement dans configure(consumer) : apply(…).exclude(…).forRoutes(…).
- NestJS 11 : forRoutes('{*splat}') au lieu de '*'.
- Toujours appeler next(), lever une exception ou répondre : sinon la requête reste bloquée.
- Usages : journal, corrélation, maintenance, en-têtes ; pas pour les droits (guards) ni les réponses (intercepteurs).
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !