Socle de production Node.js

Pour une implémentation modulaire avec NestJS, consulter [[KNOW-PAT-202]]. Ce socle reste indépendant du framework et s'applique aussi aux architectures Express plus légères.

Architecture du code

• Structurer par capacité métier, avec frontières publiques explicites ; éviter un dossier global controllers/services/models qui couple tout.
• Garder HTTP/transport à la périphérie, logique métier testable au centre, accès externes derrière des ports simples.
• Configuration typée, validée au démarrage, hiérarchisée par environnement et sans secret dans le code.
• Verrouiller la version Node LTS et les dépendances ; installation reproductible avec npm ci.

Erreurs

• Valider toute entrée à la frontière et échouer tôt avec une erreur métier explicite.
• Distinguer erreurs opérationnelles attendues et état de processus corrompu.
• Handler central : réponse publique stable, détails internes journalisés, aucune stack exposée au client.
• Toujours await les promesses dont la pile/erreur doit être observée ; écouter error sur streams et EventEmitter.
• Arrêt gracieux : refuser le nouveau trafic, terminer dans un délai borné, fermer serveur, files et connexions, puis sortir.

Event loop et ressources

• Aucun calcul lourd, regex vulnérable, parsing massif ou I/O synchrone dans le chemin de requête.
• Déporter le CPU vers worker thread/processus ou service adapté ; borner concurrence, payloads, files et timeouts.
• Mesurer lag de l'event loop, mémoire/RSS, heap, GC, handles, CPU et saturation des pools.

Sécurité et supply chain

• Processus non-root, permissions minimales, secrets injectés, dépendances auditées et image verrouillée par digest/version.
• Headers, CORS, auth, rate limit et taille de payload définis explicitement.
• Ne jamais construire de commande shell ou chemin à partir d'une entrée non validée.
• SAST/SCA, secret scanning et scan d'image en CI ; revue avant montée de version majeure.

Exploitation

• Logs structurés vers stdout avec request_id/trace, niveau, service, version et contexte sans donnée secrète.
• Endpoints séparés : liveness (processus vivant) et readiness (peut servir correctement).
• Métriques RED : Rate, Errors, Duration ; plus saturation des dépendances et files.
• Déploiement atomique avec healthcheck, migration compatible, rollback et test de restauration.
• Le reverse proxy sert TLS, compression et fichiers statiques ; l'application conserve les règles métier.

Gate CI/CD

format/lint → typecheck → unit → integration/API → security/dependencies
→ build reproductible → smoke test → déploiement progressif → vérification SLO

Un taux de couverture seul n'est pas une preuve : tester succès, erreur attendue, dépendance en panne, timeout/retry et concurrence/idempotence sur le chemin critique.

Ressources

• Node.js Best Practices — checklist structurée : architecture, erreurs, tests, production, sécurité, performance et conteneurs.
• Node.js Diagnostics — outils officiels de mesure et diagnostic.
• Node.js test runner — runner natif lorsque ses capacités suffisent.
• pino — logging structuré rapide.
• Fastify — framework avec schémas, validation et plugins ; choisir sur contraintes, pas sur popularité.
• BullMQ — jobs Redis avec retries et workers ; exige idempotence et supervision.
• [[KNOW-REF-062]] — carte des ressources backend vérifiées