6.2Dépannage express
L'essentiel en 30 secondes
- Réflexe : un symptôme = des causes probables = une action ciblée — on diagnostique avant de relancer.
- Boucle : un serveur qui gèle ou plante signale presque toujours l'asynchrone ou les erreurs non gérées.
- Production : tout écart entre local et production se traite par conteneur, variables d'environnement et logs.
Fil Salim — le playbook scotché à côté de l'écran
Salim garde ce playbook à côté de son écran. Verdict après un an : trois lignes l'ont le plus servi — le undefined d'un résultat pas encore prêt, le serveur qui gèle sous plusieurs utilisateurs, et le secret qui a failli partir dans Git. Pour chacune, il a fini par appliquer la séquence (vérifier, corriger la cause, tester) au lieu de relancer au hasard.
Symptôme observé, causes vérifiées, actions dans l'ordre : le réflexe tient en trois temps.
Diagnostiquer avant de relancer
Un problème Node se résout rarement au hasard : chaque symptôme a des causes typiques et une action ciblée. Le tableau ci-dessous regroupe les situations les plus fréquentes, de l'asynchrone au déploiement.
| Symptôme | Causes probables | Actions |
|---|---|---|
| J'obtiens undefined au lieu de mon résultat | code asynchrone mal géré : le résultat n'est pas prêt à la ligne suivante | utiliser await (fonction async) ou .then() ; penser « quand c'est prêt » ; entourer de try/catch (1.2) |
| UnhandledPromiseRejection / le serveur plante | promise rejetée non gérée ; pas de gestion d'erreurs centralisée | entourer await de try/catch ; middleware d'erreurs centralisé (err, req, res, next) ; gérer l'événement 'error' (4.4) |
| Le serveur « gèle » dès plusieurs utilisateurs | opération synchrone (fs.*Sync) ou calcul CPU lourd bloquant la boucle d'événements | passer en asynchrone (fs.promises) ; déléguer le CPU aux worker threads ; ne jamais bloquer la boucle (2.1/5.2) |
| Cannot find module / erreur d'import | mauvais chemin, node_modules absent, confusion CommonJS / ESM | npm install ; vérifier ./ pour le local contre nom pour npm ; cohérence require contre import ('type':'module') (1.3) |
| req.body est undefined dans Express | middleware de parsing manquant ou placé après les routes | ajouter app.use(express.json()) AVANT les routes ; vérifier le Content-Type (3.1) |
| Doublons ou données incohérentes en base | pas de contrainte ni validation ; pas de recherche avant création | schéma validé (required, unique) ; rechercher puis créer/mettre à jour ; relier plutôt que dupliquer (3.3) |
| Faille potentielle : injection / données non fiables | concaténation d'entrées dans une requête ; entrées non validées | requêtes paramétrées ou ORM ; valider les entrées (Zod/Joi) ; ne jamais faire confiance au client (3.4/4.2) |
| Mon API est lente sous charge | requêtes non optimisées (N+1, pas d'index) ; pas de cache ; un seul cœur utilisé | profiler AVANT de toucher ; indexer et optimiser les requêtes ; cache (Redis) ; clustering (PM2) (5.2) |
| « Ça marche chez moi » mais pas en production | environnement différent (version Node, dépendances, configuration) | conteneuriser (Docker) ; config par variables d'environnement ; vérifier les versions (5.3) |
| Un secret a fuité (clé/API dans le code ou Git) | secret en clair dans le code ou versionné | régénérer immédiatement la clé ; déplacer en variable d'environnement (.env ignoré par Git) ; ne jamais versionner .env (1.4/4.2) |
Script prêt à dire — diagnostiquer sans relancer au hasard (30 s)
« Mon symptôme : [undefined / plantage / gel / body vide / lenteur / écart prod]. Je consulte les logs, j'identifie la cause probable du playbook, j'applique l'action ciblée et je vérifie. »
Modèle copier-coller — fiche panne express
// Fiche panne : await + try/catch + middleware d'erreurs
async function chargerTache(id) {
try {
const tache = await trouverTache(id);
return tache;
} catch (erreur) {
throw new Error("Lecture impossible");
}
}
function gestionErreurs(err, req, res, next) {
console.error(err.message);
res.status(500).json({ erreur: "Erreur interne" });
}
module.exports = { chargerTache, gestionErreurs };TPE / petit budget
Pas de tableau formel : un symptôme, la cause probable du playbook, l'action et le responsable noté.
PME Algérie
Intégrer les réalités locales dans le diagnostic : versions installées, postes partagés, pics d'activité connus.
Remote / hybride
Ajouter les logs écrits immédiats aux actions : à distance, un symptôme non consigné ressemble à un système qui marche.
Interculturel
Expliciter les constats par écrit : ce qui semble évident (quelle version, quel environnement) ne l'est pas pour tous.
Défi 48h — appliquez demain
Repérez 1 symptôme actuel (undefined, gel, body vide, lenteur), remplissez la fiche panne express et testez la 1re action (logs + correction ciblée).
- Je sais relier un symptôme à ses causes probables.
- J'ai rempli (ou planifié) une fiche panne express.
- Je connais le renvoi vers le niveau à creuser pour mon cas.
Le serveur de Salim gèle dès que plusieurs utilisateurs se connectent. Quel réflexe applique le playbook ?
Un même symptôme qui revient n'est pas dix pannes : c'est un réflexe manquant à ancrer (await + try/catch, jamais de Sync en serveur, parsing avant les routes, validation, .env).