Checklist d'opérations en production pour une Express API (exemples pratiques)

Intro

Cette version française explique Express API production operations checklist with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Exécuter une Express API en production va bien au‑delà du simple démarrage d'un serveur. Il faut des défauts sécurisés, des déploiements fiables, une visibilité profonde, des sauvegardes éprouvées et un plan clair pour les montées de version et les incidents. Cette checklist pratique vous offre des exemples copiables et des critères de sortie concrets pour que votre équipe opère avec confiance. Vous y trouverez des Express API best practices et une Express API checklist centrées sur l'opérationnel.

Aperçu du workflow

Adoptez un flux explicite, par étapes, avec des responsables et des critères de sortie clairs :

1. Plan

• Définir des SLO : disponibilité (p.ex. 99,9 %), latence p95 et budgets d'erreurs.
• Choisir l'environnement d'exécution : Node LTS, version d'Express et gestionnaire de processus.
• Décider la pile d'observabilité : logs, métriques, traces et cibles d'alerte.

1. Durcir (Harden)

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

1. Observer

• Émettre des logs JSON avec request IDs.
• Exposer /healthz, /readyz et /metrics.

1. Vérifier

• Test de charge au niveau des SLO.
• Chaos basique : terminer un processus et vérifier l'absence de perte de requêtes.
• Exécuter un exercice de sauvegarde et de restauration.

1. Publier (Release)

• Déploiement sans interruption (drain, swap ou rolling update).
• Surveiller pendant 30 minutes ; détecter toute régression.

1. Exploiter (Operate)

• Runbooks d'astreinte pour haute latence, pics d'erreurs, pression disque et échecs de dépendances.

Une checklist concise et relue réduit les reprises et accroît la cohérence entre les releases.

Configuration et durcissement

Appliquez ces défauts avant votre première requête de production.

• Node et Express
• Utiliser Node LTS et le pinner via engines dans package.json.
• Définir NODE_ENV=production.
• Éviter tout travail CPU synchrone lourd dans le chemin des requêtes.

• Middleware de sécurité et limites
• helmet() pour les en‑têtes courants.
• compression() uniquement si l'amont ne compresse pas déjà.
• express.json/urlencoded avec limites de taille strictes.
• express-rate-limit ou limitation au niveau passerelle.
• Désactiver x-powered-by et valider CORS avec une allowlist.

• Trust proxy
• Si vous êtes derrière un reverse proxy ou un load balancer, définir app.set('trust proxy', true) (ou un sous‑réseau) afin que req.ip et le protocole soient corrects.

• Timeouts et en‑têtes
• Les keep‑alive et header timeouts évitent les sockets bloqués et le slowloris.
• Toujours définir un timeout côté serveur pour les requêtes.

• Erreurs et 404
• Gestionnaire d'erreurs central avec JSON cohérent et sans stack traces côté client.

• 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.

Exemple de serveur de démarrage pratique (à adapter) :

// 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' }));

// ID 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 }));

// Santé et readiness
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 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 }, 'Unhandled error');
  res.status(500).json({ error: 'Internal Server Error' });
});

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

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

const shutdown = () => {
  logger.info('shutdown start');
  isReady = false;
  server.close(err => {
    if (err) logger.error({ err }, 'server close error');
    logger.info('shutdown complete');
    process.exit(err ? 1 : 0);
  });
  setTimeout(() => {
    logger.error('forced shutdown');
    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 monitoring

Rendez chaque requête observable et alertez sur les symptômes côté utilisateur.

• Logging
• Logs JSON, une ligne par événement, avec : ts, level, msg, request_id, method, route, status, latency_ms, user_id (si dispo).
• Ne pas journaliser de secrets ni de PII.

• Métriques
• Exposer /metrics au format Prometheus.
• Suivre le nombre de requêtes, le nombre d'erreurs et des histogrammes de latence par méthode/route/statut.

• Tracing
• Propager x-request-id (et en‑têtes de trace si un tracer est utilisé). Échantillonner faiblement pour les services à fort QPS.

• Alertes (alignées sur les SLO)
• Latence p95 au‑dessus du seuil pendant 5 minutes.
• Taux de 5xx au‑dessus du seuil pendant 5 minutes.
• Readiness en échec sur plus d'une instance.
• Pression disque ou mémoire proche 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: 'HTTP request latency in ms',
  labelNames: ['method', 'route', 'status_code'],
  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 au runtime

Exploitez pour un comportement prévisible et sans interruption.

• Gestionnaire de processus
• Utiliser un superviseur (service manager ou PM2) pour redémarrer en cas de crash et gérer les instances.
• Préférer un processus par CPU avec arrêt gracieux. Éviter le clustering in‑process si votre orchestrateur gère les réplicas (utile avec Docker ou Kubernetes).

• Reverse proxy
• Terminer TLS, définir les en‑têtes proxy (X‑Forwarded-*), laisser le keep‑alive activé.

Exemple NGINX :

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;
  }
}

• Release sans interruption
• Étape 1 : marquer l'instance non prête (readyz -> 503),
• Étape 2 : drainer les connexions via le load balancer,
• Étape 3 : arrêter le processus après server.close,
• Étape 4 : démarrer la nouvelle instance, attendre readyz=200, puis l'ajouter au pool.

• Limites de ressources
• Régler ulimit -n (descripteurs de fichiers) suffisamment haut pour les sockets concurrentes.
• Ajuster le tas Node via --max-old-space-size si nécessaire ; surveiller le GC.

• Scalabilité
• Garder l'API stateless ; utiliser des stores externes pour sessions ou cache.
• Si affinité de session indispensable, assurer la stickiness du LB et limiter par client.

Gestion des données

Votre API n'est fiable qu'à hauteur de votre dernière restauration vérifiée.

• Connexions MongoDB
• Utiliser l'URI SRV avec TLS, régler maxPoolSize selon la concurrence.
• Timeouts : serverSelectionTimeoutMS et socketTimeoutMS.

• Sauvegardes
• Planifier des dumps conservés hors hôte avec rétention.
• Tester régulièrement la restauration vers une base de staging.

Exemples :

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

# Restore (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écuter les migrations avant d'activer de nouveaux chemins de code.
• Ajouter des index TTL pour expirer automatiquement certaines données.

Maintenance et mises à niveau

Conservez la vélocité sans casser la production.

• Dépendances
• Verrouiller avec un package-lock et mettre à jour selon un rythme régulier.
• Revoir les avis de sécurité et mettre à jour rapidement les paquets à risque.

• Node et Express
• Suivre le cycle LTS de Node et planifier des montées mineures trimestrielles.
• Utiliser des canaris pour les versions majeures et surveiller p95/5xx.

• Hygiène opérationnelle
• Faire tourner secrets et tokens.
• Purger/faire tourner les logs ; surveiller et faire tourner le disque.
• Mener des postmortems et enrichir la checklist pour éviter les récidives.

Plan pilote local

Démarrez petit, mesurez et itérez. Le premier pilote doit rester étroit et inspectable en local avant tout déploiement.

Périmètre du pilote :

• Un endpoint (/v1/ping),
• /healthz et /readyz,
• Logs JSON avec request IDs,
• Métriques Prometheus avec histogramme de latence,
• Arrêt gracieux et timeouts.

Étapes :

1. Échafauder un serveur Express minimal en vous appuyant sur l'exemple de ce guide.
2. Ajouter l'ID de requête et le logging pino. Vérifier que les logs affichent request_id et la latence.
3. Ajouter les métriques prom-client et exposer /metrics. Confirmer que compteurs et histogrammes évoluent sous charge.
4. Implémenter la gating de readiness (basculer isReady au démarrage et à l'arrêt).
5. Charger avec un petit outil (p.ex. autocannon) jusqu'à votre SLO de latence :

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

1. Envoyer SIGTERM pendant la charge ; vérifier l'absence de pics 5xx et de requêtes perdues.
2. Si vous utilisez MongoDB, vous connecter avec une petite requête, créer un index TTL sur une collection de test, puis réaliser un cycle sauvegarde/restauration.

Critères de sortie :

• Latence p95 dans la cible sous charge attendue,
• Aucune erreur lors d'un arrêt contrôlé,
• Métriques et logs complets et utiles pour le debug.

Pièges courants en production

Évitez ces sources fréquentes d'incidents :

• Pas d'arrêt gracieux : des requêtes tombent au déploiement.
• Timeouts manquants : connexions pendantes et workers épuisés.
• trust proxy non défini : IP clients erronées ; rate limiting inefficace.
• Charges utiles illimitées : gros corps qui font crasher le process.
• Blocage de l'event loop : crypto, zlib ou JSON synchrones sur gros payloads.
• Fuites mémoire : rétention de req/res ou caches non bornés.
• Prolifération de logs : disques saturés ; faire tourner et borner la taille.
• Retries non bornés : thundering herds ; ajouter backoff aléatoire et circuit breakers.
• Pool Mongo trop grand : timeouts et contention en charge.
• Secrets dans les logs : nettoyer les champs sensibles.
• Pas de handler 404 : les défauts du framework exposent des détails internes.
• Pas de validation d'env : l'app démarre mal configurée et échoue sous trafic.

Conclusion

Une Express API prête pour la production est le fruit d'un travail délibéré : défauts sécurisés, forte observabilité, déploiements sûrs, sauvegardes testées et workflow reproductible. Commencez par le pilote local, passez au déploiement sans interruption, et poursuivez l'itération. Cette approche renforce vos Express API operations et soutient une Express API maintenance prévisible.

Preflight checklist :

• [ ] NODE_ENV=production et Node LTS épinglé
• [ ] helmet, compression (si besoin), limites de taille et de débit
• [ ] trust proxy configuré correctement
• [ ] Keep‑alive et header timeouts définis ; timeout requêtes appliqué
• [ ] /healthz, /readyz, /metrics exposés et monitorés
• [ ] Logs JSON avec request IDs ; PII 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'erreurs, readiness et ressources
• [ ] Runbook pour pics de latence et d'erreurs

Adoptez ce workflow, gardez un pilote étroit et élargissez avec confiance à mesure que vous prouvez la fiabilité à chaque étape. De bonnes Express API best practices aujourd'hui évitent des incidents demain, tout en restant compatibles avec votre pile Node.js, REST API, MongoDB, Docker et security.