Ingegneria
Come progettare controlli di integrità per API create con IA
L’IA può generare rapidamente un’API, ma la piattaforma richiede comunque un endpoint di integrità attendibile prima di inviarle traffico di produzione.
Il controllo di integrità più semplice restituisce sempre 200. Quello utile sa quando un’API creata con IA deve smettere di ricevere traffico.
Distingui un processo attivo da uno pronto a servire traffico
Il controllo di attività, o liveness, verifica se il processo funziona ancora abbastanza bene da riprendersi senza riavvio. Il controllo di disponibilità, o readiness, verifica se può servire traffico in sicurezza adesso. Unire entrambi in un endpoint costoso può trasformare una dipendenza lenta in un ciclo di riavvii.
Mantieni locale e leggero il controllo di attività. Il controllo di disponibilità deve coprire solo le dipendenze il cui guasto rende inutilizzabile il percorso di risposta. Un servizio di analisi in background raramente ne fa parte; una connessione necessaria al database spesso sì.
- —Attività: event loop o processo risponde; non servono chiamate esterne.
- —Disponibilità: le dipendenze necessarie al percorso della richiesta rispondono entro un termine fisso.
- —Avvio: inizializzazione e migrazioni sono complete prima che il controllo di disponibilità dia esito positivo.
Limita la durata dei controlli in caso di guasto
Una sonda che attende indefinitamente non è utile. Imposta un timeout breve, evita tentativi illimitati nell’handler e restituisci un errore chiaro se l’app non dimostra in tempo di essere pronta. La piattaforma può così smettere di instradare nuovo traffico mentre il processo si riprende o si avvia una sostituzione.
L’endpoint deve anche evitare di modificare dati. I controlli di integrità vengono eseguiti spesso, da più luoghi e in condizioni già degradate. Una query in sola lettura o un ping leggero alla dipendenza è più sicuro di una scrittura usata soltanto per dimostrare l’accesso.
export async function GET() {
const ready = await dependenciesReady({ timeoutMs: 500 });
return Response.json(
{ status: ready ? "ready" : "not_ready" },
{ status: ready ? 200 : 503 },
);
}Prova i casi di errore
Una route di integrità testata soltanto con tutte le dipendenze funzionanti è incompleta. Arresta il database, esaurisci un pool di connessioni, fai superare il timeout a un servizio upstream necessario e verifica che il controllo di disponibilità fallisca prima che si accumulino le richieste normali.
Poi ripristina la dipendenza e verifica che il processo torni a ricevere traffico senza intervento manuale. Anche il percorso di ripristino fa parte del contratto.
- —Blocca le connessioni al database e verifica che il controllo di disponibilità restituisca 503.
- —Ritarda un servizio upstream necessario oltre il termine della sonda.
- —Invia SIGTERM e verifica che il controllo di disponibilità fallisca prima dell’inizio dell’arresto.
- —Ripristina le dipendenze e verifica che la replica rientri in rotazione quando è stabile.
Evita incidenti causati dalle sonde
La frequenza delle sonde si moltiplica rapidamente tra repliche e luoghi di monitoraggio. Dieci repliche controllate ogni secondo possono aggiungere centinaia di query alle dipendenze al minuto. Mantieni leggera la query, usa cache soltanto se non nasconde un guasto reale e aggiungi variazioni casuali nei tempi se tutte le repliche effettuerebbero la sonda nello stesso istante.
Genera avvisi per una perdita prolungata di disponibilità e per il numero di repliche funzionanti, non per ogni singolo controllo fallito. Un timeout transitorio è un’evidenza; un insieme di repliche disponibili che si riduce è un incidente.