Guida
Come progettare una piccola API di produzione
Uno starter di produzione non richiede decine di astrazioni. Richiede un confine di processo chiaro, una configurazione prevedibile e segnali sufficienti per operare in sicurezza.
La prima versione di produzione deve essere abbastanza piccola da poterla comprendere sotto pressione.
Rendi deterministico l'avvio
Un servizio deve avviarsi con un solo comando documentato, ascoltare sulla porta configurata e terminare con un errore utile quando manca una configurazione necessaria. Evita procedure che dipendono da file o stato della shell esterni al repository e al manifest.
Esegui le migrazioni dello schema come passaggio esplicito del rilascio quando il framework lo supporta. Nascondere una migrazione distruttiva nell'avvio del processo rende ogni replica responsabile del coordinamento simultaneo di una modifica al database.
name: orders-api
build_cmd: npm ci && npm run build
start_cmd: node dist/server.js
runtime:
name: node@24
port: 8080
health_path: /healthzMantieni visibile il percorso della richiesta
Inizia con un livello di route sottile, codice del dominio verificabile senza HTTP e un piccolo adattatore per ogni dipendenza esterna. Aggiungi una coda, una cache o un secondo servizio solo quando il carico di lavoro ne dà motivo.
Restituisci errori con una struttura coerente e identificatori delle richieste. L'identificatore deve passare nei log e nelle chiamate in uscita, così una richiesta non riuscita può essere seguita senza cercare solo per timestamp.
- —Livello delle route: interpreta l'input HTTP e associa gli errori del dominio a risposte stabili.
- —Funzione del dominio: applica le regole degli ordini senza dipendere dal framework web.
- —Adattatore del repository: gestisce SQL e confini delle transazioni.
- —Adattatore del provider: applica timeout e traduci gli errori esterni.
Pubblica con segnali operativi
Come minimo, esponi lo stato di readiness, scrivi log strutturati e gestisci l'arresto con tempo sufficiente per completare o rifiutare correttamente le richieste in corso. Imposta timeout sulle chiamate in uscita e limiti di risorse che rendano visibili le perdite prima che colpiscano i carichi di lavoro vicini.
Sono scelte semplici, ma creano un servizio su cui il team può fare debug. Aggiungi architettura quando l'applicazione ne ha bisogno, non perché nello starter c'era spazio per un'altra cartella.
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"));Simula un guasto completo
Prima di definire il servizio pronto per la produzione, scegli una dipendenza e rendila deliberatamente indisponibile. Per l'API degli ordini, ferma PostgreSQL mentre invii richieste. I nuovi ordini devono fallire con una risposta 503 entro tempi limitati, la readiness deve rimuovere la replica dalla rotazione e i log devono conservare l'ID della richiesta senza stampare la stringa di connessione.
Ripristina PostgreSQL e conferma che il servizio torni pronto senza ordini duplicati. Questa singola simulazione verifica più aspetti del contratto operativo reale di una vasta serie di test unitari limitati alle route.