Guide
Comment concevoir une petite API de production
Un projet de départ pour la production n’a pas besoin de dizaines d’abstractions. Il lui faut un périmètre de processus clair, une configuration prévisible et suffisamment de signaux pour l’exploiter sans risque.
La première version de production devrait être suffisamment petite pour être comprise sous pression.
Rendre déterministe le démarrage
Un service doit démarrer avec une commande documentée, écouter sur le port configuré et échouer avec une erreur utile si une configuration requise manque. Évitez toute configuration qui dépend de fichiers ou d’un état du shell extérieurs au dépôt et au manifeste.
Exécutez les migrations de schéma dans une étape explicite de mise en production si le framework le permet. Cacher une migration destructrice dans le démarrage du processus oblige chaque réplique à coordonner un changement de base au même moment.
name: orders-api
build_cmd: npm ci && npm run build
start_cmd: node dist/server.js
runtime:
name: node@24
port: 8080
health_path: /healthzGardez le chemin de requête visible
Commencez par une couche de routes légère, du code métier testable sans HTTP et un petit adaptateur pour chaque dépendance externe. N’ajoutez une file d’attente, un cache ou un second service que si le workload le justifie.
Renvoyez des structures d’erreur cohérentes et des identifiants de requête. Propagez l’identifiant dans les journaux et les appels sortants pour pouvoir suivre une requête échouée sans vous limiter à la recherche par horodatage.
- —Couche de routes : analyser les données HTTP et convertir les erreurs métier en réponses stables.
- —Fonction métier : appliquer les règles de commande sans dépendre du framework web.
- —Adaptateur de persistance : gérer le SQL et les limites des transactions.
- —Adaptateur du prestataire : imposer des délais limites et convertir les erreurs externes.
Livrer avec les signaux nécessaires à l’exploitation
Au minimum, exposez l’état de préparation, écrivez des journaux structurés et prévoyez un arrêt assez long pour terminer ou rejeter proprement les requêtes en cours. Imposez des délais limites aux appels sortants et des limites de ressources qui révèlent les fuites avant qu’elles affectent les workloads voisins.
Ces choix sont modestes, mais ils rendent le service débogable par l’équipe. Ajoutez de l’architecture quand l’application le justifie, pas parce que le projet de départ pouvait contenir un dossier supplémentaire.
const close = async (signal) => {
app.log.info({ signal }, "shutdown started");
await app.close();
await database.end();
process.exit(0);
};
process.once("SIGTERM", () => close("SIGTERM"));
process.once("SIGINT", () => close("SIGINT"));Tester un scénario de panne complet
Avant de déclarer le service prêt pour la production, choisissez une dépendance et provoquez délibérément sa panne. Pour l’API de commandes, arrêtez PostgreSQL pendant l’envoi de requêtes. Les nouvelles commandes doivent échouer avec une réponse 503 dans un délai limité, le contrôle de préparation doit retirer la réplique du trafic et les journaux doivent conserver l’identifiant de requête sans afficher la chaîne de connexion.
Rétablissez PostgreSQL et confirmez que le service redevient prêt sans créer de commandes en double. Cet exercice unique teste davantage le véritable contrat d’exploitation qu’un grand ensemble de tests unitaires limités aux routes.