Accueil › Node.js › La gestion d'erreur centralisée
La gestion d'erreur centralisée
Express — les basesdebutant
Un gestionnaire d'erreur se reconnaît à ses quatre paramètres, et se déclare en dernier.
app.use((err, req, res, next) => {
const statut = err.statut ?? 500;
if (statut >= 500) {
console.error({ correlation: req.correlation, err }); // journal complet
}
res.status(statut).json({
erreur: statut >= 500 ? "erreur interne" : err.message,
correlation: req.correlation,
});
});
Quatre paramètres, pas trois
Express lit fn.length. Une fonction (err, req, res) est inscrite comme
intergiciel ordinaire : elle recevra des requêtes normales, avec la requête
dans err. Le next inutilisé est obligatoire.
Deux familles d'erreurs
| Erreur attendue | Erreur inattendue | |
|---|---|---|
| Exemple | ressource absente, corps invalide | base injoignable, bogue |
| Code | 400, 403, 404, 409 | 500 |
| Message au client | celui de l'erreur | générique, toujours |
| Journal | niveau information | niveau erreur, avec la trace |
Ce qui ne sort jamais du serveur
La trace d'appel et les messages de base de données. Ils nomment les chemins du serveur, le moteur, le schéma — de la reconnaissance offerte à un attaquant, et inutile au client.
Ce qui sort toujours
Un identifiant de corrélation, renvoyé dans la réponse et écrit dans le journal. Le client le cite, l'équipe retrouve la trace complète. C'est ce qui remplace le message interne sans rien perdre d'exploitable.
app.use((req, res, next) => {
req.correlation = crypto.randomUUID();
res.set("X-Correlation-Id", req.correlation);
next();
});
En Express 5, le rejet d'un gestionnaire async arrive ici tout seul.
Les termes à connaître
- Gestionnaire d'erreur
Un intergiciel à quatre paramètres
(err, req, res, next). Express le reconnaît àfn.length, pas à son nom ni à sa position. Il se déclare en dernier, après toutes les routes.- `next(err)`
Le saut vers le gestionnaire d'erreur. Tous les intergiciels et routes ordinaires restants sont ignorés : seuls les gestionnaires à quatre paramètres sont encore essayés.
- Erreur attendue
Une faute du client ou une règle métier non respectée : ressource absente, corps invalide, droits insuffisants. Elle porte son code de statut et son message est destiné au client.
- Erreur inattendue
Tout le reste : une base injoignable, une propriété lue sur
undefined, un bogue. Elle vaut 500, et son message ne doit jamais sortir du serveur.- Identifiant de corrélation
Un identifiant unique par requête, renvoyé au client et écrit dans le journal. Le client cite cet identifiant, l'équipe retrouve la trace complète — sans jamais avoir exposé la moindre information interne.
- Trace d'appel
La pile de la fonction qui a levé. Elle expose les chemins du serveur, les noms des modules et parfois des fragments de requête. Elle appartient au journal, jamais à la réponse HTTP.
- Fuite d'information
Renvoyer au client un message interne — trace d'appel, erreur de base de données, chemin de fichier. C'est une faille de reconnaissance : elle renseigne un attaquant sur la technologie, le schéma et la structure du serveur.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.