Liste de contrôle des opérations en production pour API Express avec exemples pratiques

Faire tourner une API Express en production ne se limite pas à démarrer un serveur. Il faut des valeurs par défaut sécurisées, des déploiements fiables, une visibilité approfondie, des sauvegardes testées et un plan pour les mises à jour et les incidents. Cette liste de contrôle pratique fournit des exemples copier-coller et des critères de sortie concrets pour que votre équipe puisse opérer en toute confiance.

Vue d'ensemble du flux de travail

Adoptez un flux explicite et par étapes afin que chaque étape ait des responsables clairs et des critères de sortie :

Planifier

Définir les SLO (Service Level Objectives) : disponibilité (par exemple 99,9 %), latence p95 < 200 ms, budget d'erreur de 0,1 %.
Choisir l'environnement d'exécution : Node LTS, version d'Express, gestionnaire de processus.
Décider de la pile d'observabilité : logs, métriques, traces et cibles d'alerte.

Durcir

Verrouiller la configuration d'environnement et les secrets.
Ajouter les middlewares de sécurité, les timeouts et l'arrêt gracieux.

Observer

Émettre des logs JSON avec identifiants de requête.
Exposer /healthz, /readyz et /metrics.

Vérifier

Tests de charge jusqu'aux SLO.
Bases du chaos : terminer un processus ; vérifier qu'aucune requête n'est perdue.
Exécuter un exercice de sauvegarde et restauration.

Déployer

Déploiement sans temps d'arrêt (drain, swap ou rolling).
Surveiller pendant 30 minutes ; guetter les régressions.

Opérer

Runbooks d'astreinte pour latence élevée, pics d'erreurs, pression disque et défaillances de dépendances.

Une liste de contrôle concise et revue réduit le retravail et augmente la cohérence entre les versions.

Configuration et durcissement

Appliquez ces valeurs par défaut avant votre première requête en production.

Node et Express
Utilisez Node LTS et épinglez-le via engines dans package.json.
Définissez NODE_ENV=production.
Évitez le travail CPU synchrone et lourd dans les chemins de requête.

Middlewares de sécurité et limites
helmet() pour les en-têtes courants.
compression() seulement si l'amont ne compresse pas déjà.
express.json/urlencoded avec limites de taille strictes (ex. 1 Mo).
express-rate-limit ou limitation de débit au niveau de la passerelle.
Désactiver x-powered-by et valider CORS avec une liste d'autorisation.

Trust proxy
Si derrière un reverse proxy ou un load balancer, définissez app.set('trust proxy', true) ou un sous-réseau pour que req.ip et le protocole soient corrects.

Timeouts et en-têtes
Les timeouts keep-alive et d'en-têtes préviennent les sockets bloqués et le slowloris.
Définissez toujours un timeout de requête côté serveur (ex. 30 secondes).

Erreurs et 404
Gestionnaire d'erreurs centralisé avec forme JSON cohérente et pas de stack traces vers les clients.

Arrêt gracieux
Gérer SIGTERM et SIGINT pour drainer, puis fermer le serveur. Refuser le trafic en basculant la readiness avant l'arrêt.

Serveur de démarrage pratique (à adapter selon vos besoins) :

// server.js
const express = require('express');
const helmet = require('helmet');
const compression = require('compression');
const rateLimit = require('express-rate-limit');
const pino = require('pino');
const pinoHttp = require('pino-http');
const crypto = require('crypto');

const app = express();
app.set('env', process.env.NODE_ENV || 'production');
app.disable('x-powered-by');
app.set('trust proxy', true); // si derrière un proxy

app.use(helmet());
app.use(compression());
app.use(express.json({ limit: '1mb', strict: true }));
app.use(express.urlencoded({ extended: false, limit: '1mb' }));

// Identifiant de requête
app.use((req, res, next) => {
  const rid = req.headers['x-request-id'] || crypto.randomUUID();
  res.setHeader('x-request-id', rid);
  req.id = rid;
  next();
});

const logger = pino({ level: process.env.LOG_LEVEL || 'info' });
app.use(pinoHttp({ logger, genReqId: req => req.id }));

// Limitation de débit (ajuster par endpoint)
app.use(rateLimit({ windowMs: 60_000, max: 300, standardHeaders: true, legacyHeaders: false }));

// Middleware de timeout de requête (exemple : 30s)
app.use((req, res, next) => {
  const timeout = 30_000;
  const timer = setTimeout(() => {
    if (!res.headersSent) {
      res.status(504).json({ error: 'Gateway Timeout' });
    }
  }, timeout);
  res.on('finish', () => clearTimeout(timer));
  res.on('close', () => clearTimeout(timer));
  next();
});

// Santé et disponibilité
let isReady = false;
app.get('/healthz', (req, res) => res.status(200).json({ ok: true }));
app.get('/readyz', (req, res) => isReady ? res.json({ ready: true }) : res.status(503).json({ ready: false }));

// Route d'exemple
app.get('/v1/ping', (req, res) => res.json({ pong: true }));

// 404 et gestionnaire d'erreurs
app.use((req, res) => res.status(404).json({ error: 'Not Found' }));
app.use((err, req, res, next) => { // eslint-disable-line no-unused-vars
  req.log.error({ err }, 'Erreur non gérée');
  res.status(500).json({ error: 'Internal Server Error' });
});

const server = app.listen(process.env.PORT || 3000, () => {
  logger.info({ port: server.address().port }, 'serveur démarré');
  isReady = true;
});

// Timeouts et arrêt gracieux
server.keepAliveTimeout = 61_000; // > keepalive du LB
server.headersTimeout = 65_000; // > keepAliveTimeout

const shutdown = () => {
  logger.info('arrêt commencé');
  isReady = false;
  server.close(err => {
    if (err) logger.error({ err }, 'erreur fermeture serveur');
    logger.info('arrêt terminé');
    process.exit(err ? 1 : 0);
  });
  setTimeout(() => {
    logger.error('arrêt forcé');
    process.exit(1);
  }, 30_000).unref();
};

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);
process.on('unhandledRejection', err => { logger.error({ err }, 'unhandledRejection'); shutdown(); });
process.on('uncaughtException', err => { logger.error({ err }, 'uncaughtException'); shutdown(); });

Observabilité et surveillance

Rendez chaque requête observable et alertez sur les symptômes visibles par l'utilisateur.

Journalisation
Logs JSON, une ligne par événement, avec champs : ts, level, msg, request_id, method, route, status, latency_ms, user_id (si disponible).
Ne journalisez pas de secrets ni de données personnelles.

Métriques
Exposez /metrics au format Prometheus.
Suivez le nombre de requêtes, le nombre d'erreurs et les histogrammes de latence par méthode/route/statut.

Traçage
Propagez x-request-id (et les en-têtes de trace si vous utilisez un traceur). Échantillonnez à un faible pourcentage pour les services à fort QPS.

Alertes (alignées aux SLO)
Latence p95 au-dessus du seuil pendant 5 min.
Taux 5xx au-dessus du seuil pendant 5 min.
Échec de la readiness sur plus d'une instance.
Pression disque ou mémoire près des limites.

Exemple de métriques avec prom-client :

const client = require('prom-client');
client.collectDefaultMetrics();
const httpLatency = new client.Histogram({
  name: 'http_request_duration_ms',
  help: 'Latence des requêtes HTTP en ms',
  labelNames: ['method', 'route', 'status_code'],
  // Buckets adaptés à la latence API typique : 5 ms à 2 s
  buckets: [5, 15, 50, 100, 300, 500, 1000, 2000]
});

app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const route = req.route && req.route.path ? req.route.path : req.path;
    httpLatency.labels(req.method, route, String(res.statusCode)).observe(Date.now() - start);
  });
  next();
});

app.get('/metrics', async (req, res) => {
  res.set('Content-Type', client.register.contentType);
  res.end(await client.register.metrics());
});

Opérations d'exécution

Opérez pour le zéro temps d'arrêt et un comportement prévisible.

Gestionnaire de processus
Utilisez un superviseur (par exemple, un gestionnaire de services ou PM2) pour redémarrer sur crash et gérer les instances.
Préférez un processus par CPU avec arrêt gracieux. Évitez le clustering en processus si votre orchestrateur gère les replicas.

Reverse proxy
Terminez le TLS, définissez les en-têtes proxy (X-Forwarded-*) et gardez le keep-alive activé.

Extrait NGINX d'exemple :

upstream api {
  server 127.0.0.1:3000;
  keepalive 64;
}
server {
  listen 443 ssl http2;
  server_name api.example.com;
  location / {
    proxy_pass http://api;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Request-Id $request_id;
    proxy_read_timeout 30s;
  }
}

Déploiement sans temps d'arrêt

Marquer l'instance comme non prête (readyz -> 503).
Drainer les connexions via le load balancer.
Arrêter le processus après la fin de server.close.
Démarrer la nouvelle instance, attendre readyz=200, puis l'ajouter au pool.

Limites de ressources
Définissez ulimit -n (descripteurs de fichiers) assez haut pour les sockets concurrentes.
Ajustez le heap Node via --max-old-space-size si nécessaire ; surveillez le GC.

Mise à l'échelle
Gardez l'API sans état ; utilisez des stockages externes pour les sessions ou le cache.
Pour les sessions collantes (si inévitable), assurez la persistance du LB et la limitation de débit par client.

Gestion des données

Votre API n'est fiable que par sa dernière restauration vérifiée.

Connexions MongoDB
Utilisez l'URI SRV avec TLS, ajustez maxPoolSize à la concurrence.
Timeouts : serverSelectionTimeoutMS et socketTimeoutMS.

Sauvegardes
Planifiez les dumps et conservez-les hors hôte avec rétention.
Testez la restauration régulièrement vers une base de staging.

Exemples :

# Sauvegarde
mongodump --uri "$MONGODB_URI" \
  --gzip --archive=/backups/$(date +%F).gz

# Restauration (vers une base de test)
mongorestore --uri "$MONGODB_RESTORE_URI" \
  --gzip --archive=/backups/2024-01-15.gz --drop

Migrations
Scripts de migration versionnés et idempotents.
Exécutez les migrations avant d'activer les nouveaux chemins de code.
Ajoutez des index TTL pour l'expiration automatique des données.

Maintenance et mises à niveau

Gardez la vélocité sans casser la production.

Dépendances
Verrouillez avec package-lock et mettez à jour selon un calendrier.
Surveillez les avis de sécurité et mettez à jour rapidement les paquets à risque élevé.

Node et Express
Suivez Node LTS et planifiez les mises à jour mineures chaque trimestre.
Utilisez des canary releases pour les sauts majeurs et surveillez p95/5xx.

Hygiène opérationnelle
Faites tourner les secrets et jetons.
Purgez les logs ; assurez-vous que le disque est surveillé et rotaté.
Menez des post-mortems d'incident et ajoutez des éléments à la checklist pour éviter les répétitions.

Plan Pilote Local

Commencez petit, mesurez et itérez. Gardez le premier pilote étroit et facile à inspecter localement avant le déploiement.

Périmètre du pilote :

Un endpoint (/v1/ping)
/healthz et /readyz
Journalisation JSON avec identifiants de requête
Métriques Prometheus avec histogramme de latence
Arrêt gracieux et timeouts

Étapes :

Échafaudez un serveur Express minimal avec l'exemple de ce guide.
Ajoutez l'identifiant de requête et la journalisation pino. Vérifiez que les logs montrent request_id et la latence.
Ajoutez les métriques prom-client et exposez /metrics. Confirmez que les compteurs et histogrammes changent sous charge.
Implémentez le gating de readiness (basculez isReady au démarrage et à l'arrêt).
Test de charge avec un petit outil (par exemple, autocannon) jusqu'à votre SLO de latence :

autocannon -c 50 -d 30 http://localhost:3000/v1/ping

Envoyez SIGTERM pendant la charge ; vérifiez qu'il n'y a pas de pics 5xx et aucune requête perdue.
Si vous utilisez MongoDB, connectez-vous avec une petite requête, définissez un index TTL dans une collection de test, et exécutez un cycle de sauvegarde et restauration.

Critères de sortie :

Latence p95 dans la cible sous la charge attendue
Aucune erreur pendant l'arrêt contrôlé
Métriques et logs complets et utiles pour le débogage

Pièges courants en production

Évitez ces sources fréquentes d'incidents :

Pas d'arrêt gracieux : les requêtes tombent au déploiement.
Timeouts manquants : les connexions pendent et les workers s'épuisent.
trust proxy non défini : IPs clients incorrectes ; limitation de débit inefficace.
Payloads illimités : gros corps font planter le processus.
Blocage de la boucle d'événements : crypto, zlib ou JSON synchrones sur gros payloads.
Fuites mémoire : rétention req/res ou gros caches sans bornes.
Prolifération des logs : logs non bornés remplissent le disque ; rotattez et plafonnez la taille.
Retries non bornés : troupeaux tonnants ; ajoutez un backoff avec gigue et des circuit breakers (ex. opossum).
Pool Mongo trop grand : timeouts et contention sous charge.
Secrets dans les logs : nettoyez les champs sensibles.
Pas de gestionnaire 404 : les défauts du framework fuient les internes.
Pas de validation d'env : l'application démarre avec de mauvais réglages et échoue sous trafic.

Conclusion

Une API Express prête pour la production est délibérée : valeurs par défaut sécurisées, observabilité forte, déploiements sûrs, sauvegardes testées et flux de travail répétable. Commencez par le pilote local, passez à un déploiement sans temps d'arrêt, et continuez d'itérer.

Checklist pré-vol :

[ ] NODE_ENV=production et Node LTS épinglé
[ ] helmet, compression (si nécessaire), limites de taille, limites de débit
[ ] trust proxy configuré correctement
[ ] Timeouts keep-alive et d'en-têtes définis ; timeout de requête appliqué
[ ] /healthz, /readyz, /metrics exposés et surveillés
[ ] Logs JSON avec identifiants de requête ; données personnelles nettoyées
[ ] Arrêt gracieux sur SIGTERM/SIGINT
[ ] Sauvegardes planifiées et restauration testée
[ ] Migrations versionnées et idempotentes
[ ] Alertes sur latence p95, taux d'erreur, readiness et limites de ressources
[ ] Runbook pour pics de latence et d'erreurs

Adoptez le flux de travail, gardez le pilote étroit, et élargissez avec confiance en prouvant la fiabilité à chaque étape.