Mock API contract-first

Perché iniziare con un contratto

Ho costruito MockDeck dopo aver visto team sprecare settimane aspettando un backend che non arrivava mai in tempo. Il primo passo che faccio con ogni nuova funzionalità è scrivere una breve descrizione dell'endpoint che sia sia gli ingegneri frontend che backend possano revisionare. Quella descrizione diventa il contratto. Quando il contratto è fisso, il frontend può iniziare a codificare contro un mock che si comporta esattamente come il servizio reale, mentre il team backend lavora sull'implementazione in parallelo. Ciò elimina il periodo di inattività in cui gli sviluppatori fissano un 404 o un placeholder che restituisce solo codici di successo. Ancorando il lavoro a un artefatto concreto, riduciamo il ciclo di feedback da giorni a ore e evitiamo il costoso rifacimento che si verifica quando le ipotesi sulla forma del payload o sulla gestione degli errori si rivelano errate.

Quando esiste un contratto fin dall'inizio, i designer possono creare componenti UI che consumano la forma dei dati esatta, QA può scrivere casi di test basati sulle risposte di errore definite e DevOps può configurare server mock negli ambienti di staging senza aspettare il servizio reale. Il contratto diventa una singola fonte di verità che riduce la discomunicazione tra le discipline.

Scrivere il contratto

Un contratto deve catturare ogni comportamento osservabile dell'endpoint. Inizio con il percorso HTTP e il metodo, quindi annoto eventuali schemi di autenticazione (chiave API, token bearer, TLS reciproco). Successivamente elenco i parametri della richiesta: stringhe di query, header e campi del corpo, contrassegnandoli come obbligatori o facoltativi. Per ogni campo aggiungo un tipo (stringa, numero, booleano, array, oggetto) e un formato se necessario (email, data/ora, uuid). Quindi definisco la risposta di successo: codice di stato, eventuali header e la forma completa del payload con tipi e formati. Infine aggiungo casi di errore che il frontend deve gestire: errori di convalida (400), non trovato (404), non autorizzato (401), limitazione della velocità (429) e errori del server (5xx). Per ogni errore includo un corpo di esempio che mostra la forma del messaggio di errore.

Elemento del contratto | Valore di esempio | Note Percorso | /v1/orders | Risorsa con versione Metodo | POST | Crea un nuovo ordine Autenticazione | Token bearer | Header di autorizzazione obbligatorio Corpo della richiesta – obbligatorio | customer_id (stringa, uuid) | Deve esistere nel database Corpo della richiesta – facoltativo | nota (stringa, max 500) | Commento libero Risposta di successo | 201, {order_id, created_at} | Header di localizzazione con URL Errore di convalida | 400, {errors: [{field: "customer_id", message: "must be uuid"}]} | Aiuta il frontend a visualizzare avvisi inline Non trovato | 404, {error: "ordine non trovato"} | Si verifica su GET /v1/orders/:id quando l'ID è sconosciuto

Conservo il contratto in un file di testo semplice (YAML o JSON) che si trova accanto alla branch delle funzionalità. Ciò rende facile la differenza delle modifiche durante la revisione del codice e archiviare l'artefatto nel controllo di versione insieme al codice sorgente. Quando un contratto cambia, la differenza mostra esattamente quale campo è stato aggiunto, rimosso o ha avuto il suo tipo alterato, innescando una conversazione tra i proprietari del frontend e del backend prima che venga scritto alcun codice.

Generazione della specifica mock

Una volta scritto il contratto in un file markdown o JSON semplice, MockDeck lo legge e produce tre artefatti: un documento OpenAPI 3, una raccolta Postman e un file delle route grezzo (JSON semplice con percorso, metodo e risposte di esempio). Il documento OpenAPI include gli schemi esatti che hai definito, più esempi generati automaticamente che sembrano dati reali - pensa a nomi che seguono modelli tipici, numeri che rientrano in intervalli previsti e stringhe che raggiungono lunghezze minime e massime. La raccolta Postman può essere importata direttamente nel client API che utilizzi per i test manuali e il file delle route grezzo può essere servito da un server mock leggero (come Mirage JS o json-server) senza alcuna configurazione.

Il passaggio di generazione è deterministico: dato lo stesso file di contratto, ottieni sempre lo stesso output mock. Ciò ti consente di commitare gli artefatti generati nel tuo repository se desideri un mock statico o puoi eseguire MockDeck come parte dell'avvio del tuo server di sviluppo per mantenere il mock in memoria. Poiché il mock è derivato dal contratto, non devi mai mantenere due fonti di verità separate; qualsiasi modifica al contratto si propaga automaticamente al mock quando lo rigeneri.

MockDeck aggiunge anche alcune funzionalità di convenienza out of the box: imposta gli header CORS appropriati per lo sviluppo locale, aggiunge un controllo del ritardo in modo da poter simulare il ritardo di rete e registra ogni richiesta nella console in modo da poter verificare che il frontend stia colpendo il punto finale previsto con il payload corretto. Gli strumenti come possono essere utilizzati in combinazione con MockDeck per migliorare l'esperienza di sviluppo.

Integrazione dei mock nel flusso di lavoro frontend

Nei miei progetti, aggiungo uno script di avvio che lancia il server mock prima del server di sviluppo frontend. Lo script legge la cartella dei contratti, esegue MockDeck per produrre il file delle route, quindi avvia un server node-express che serve quelle route su http://localhost:3001. Il proxy frontend è configurato per inoltrare tutte le richieste /api a quella porta, in modo che il codicebase veda uno strato API uniforme senza alcun cambiamento nella sorgente.

- Aggiungere una directory dei contratti alla radice del repository. - Per ogni endpoint creare un file.yaml che segue la struttura descritta in precedenza. - Aggiungere uno script start:mock in package.json che esegue mockdeck build./contracts --out./mock e poi node./mock/server.js. - Configurare il server di sviluppo frontend (ad esempio Vite, CRA) per proxy /api a http://localhost:3001. - Eseguire npm run start:mock in un terminale e npm run dev in un altro.

Quando un contratto cambia, è necessario solo riavviare lo script mock; il frontend adotta il nuovo comportamento istantaneamente perché il proxy inoltra al server mock aggiornato. Questo ciclo stretto incoraggia gli sviluppatori a trattare il contratto come il primo artefatto che modificano quando una funzionalità evolve.

Scrivo anche un semplice test Jest che importa il documento OpenAPI generato e afferma che la forma della richiesta corrisponde alle chiamate API del componente.

Gestione delle versioni dei contratti e gestione del drift

I contratti evolvono proprio come il codice. Tratto ogni file di contratto come versionato insieme alla branch delle funzionalità. Quando è necessario un cambiamento significativo - come ad esempio rinominare un campo o cambiare un flag obbligatorio - creo una nuova versione del contratto (ad esempio v2/order-create.yaml) e aggiorno il generatore OpenAPI per includere un blocco servers che punta al percorso versionato. Il server mock serve quindi entrambe le versioni contemporaneamente, consentendo al frontend di optare per il nuovo contratto cambiando l'URL di base.

Per rilevare il drift eseguo un lavoro notturno che confronta la specifica OpenAPI del backend live (generata dal codice effettivo) con la specifica generata dal contratto. Qualsiasi discrepanza viene segnalata come avvertimento nel nostro dashboard di CI. Questo approccio ha rilevato casi in cui uno sviluppatore backend ha aggiunto un nuovo campo opzionale senza aggiornare il contratto, il che avrebbe causato errori di convalida frontend in produzione.

Quando un contratto è deprecato, aggiungo una data di fine vita in un commento in alto nel file e mantengo il mock attivo per due settimane dopo la data per dare tempo ai team di migrare. Dopo tale periodo, il server mock restituisce una risposta 410 Gone con una breve spiegazione, rendendo esplicito il ciclo di vita del contratto.

Test dei contratti come rete di sicurezza

Il test dei contratti verifica che il mock e la reale implementazione parlino lo stesso linguaggio. Utilizzo uno strumento come Pact o Dredd per eseguire il contratto contro sia il server mock che il backend di staging. La suite di test invia ogni richiesta definita nel contratto, controlla il codice di stato della risposta, gli header e lo schema del corpo, e registra eventuali deviazioni.

Incorporare questo passaggio nel flusso di lavoro della richiesta di pull significa che una modifica al backend che viola il contratto fallirà la build prima di raggiungere master. Allo stesso modo, se uno sviluppatore frontend aggiorna il payload della richiesta senza aggiornare il contratto, il test fallirà perché il mock non riconoscerà la nuova forma.

Per i team focalizzati sulla sicurezza, eseguo anche il contratto contro le linee guida OWASP per le applicazioni di grandi modelli linguistici (https://owasp.org/www-project-top-10-for-large-language-model-applications) per assicurarmi che i mock generati non espongano involontariamente pattern pericolosi come l'upload di file non restrittivo o la perdita di dati eccessiva.

La suite di test del contratto si esegue in meno di due secondi su un laptop tipico, quindi aggiunge un sovraccarico trascurabile alla pipeline CI mentre fornisce un'elevata fiducia che il mock rimanga fedele alla specifica concordata, come ad esempio MockDeck, e che gli strumenti come funzionino correttamente.

Cosa questo non è

Questo approccio non garantisce che il backend sarà consegnato in tempo. Un mock può solo simulare il comportamento, non può sostituire la logica aziendale reale, le interazioni con il database o le chiamate a servizi esterni che l'implementazione reale eseguirà.

Non è un sostituto al 100% dei test end-to-end. È ancora necessario verificare che il sistema integrato funzioni correttamente con dati autentici, caratteristiche di prestazione ed errori che possono apparire solo sotto carico.

Non elimina la necessità di una comunicazione chiara tra i team. Il contratto è uno strumento per facilitare la discussione, ma non sostituisce le regolari sincronizzazioni, le revisioni del design o la documentazione condivisa.

Infine, l'utilizzo di mock con contratto non renderà il tuo prodotto immune agli errori di specifica. Se il contratto stesso è ambiguo o incompleto, il mock implementerà fedelmente quelle lacune e il frontend si costruirà su un'ipotesi errata. Tratta il contratto come un documento vivo che evolve con i feedback da entrambi i lati.

Riferimenti

- https://owasp.org/www-project-top-10-for-large-language-model-applications

- https://www.nist.gov/itl/ai-risk-management-framework

Domande frequenti

È questo un server di mock in esecuzione?

No. MockDeck genera la specifica dell'API di mock — OpenAPI 3, Postman o route grezze. Servirla è un passaggio separato.

Può chiamare il nostro backend reale?

No. Non proxy o esegue il tuo backend; l'output è una specifica e risposte di esempio.

Quali formati produce?

OpenAPI 3, raccolte Postman o route grezze.

Perché preoccuparsi delle risposte di errore in un mock?

Perché è lì che di solito si rompe il codice frontend. Un mock che restituisce solo 200 nasconde gli stati che più hai bisogno di gestire.

Quanto è realistico il dati di esempio?

È generato per sembrare payload reali, il che è sufficiente per catturare bug di formattazione e stato vuoto precocemente. Non è dati di produzione.

Convalida il nostro API esistente contro il contratto?

No. La convalida del contratto e del test sono strumenti separati.

No, MockDeck è uno strumento indipendente che non dipende da questi progetti o normative.

Riferimenti

- Specifica OpenAPI - JSON Schema

Prova il prodotto: MockDeck

2026-09-20 · sole fonti primarie · nessuna metrica di traffico fabbricata · supporto alle decisioni solo

Articoli correlati

- Server di simulazione vs esempi OpenAPI - Esplora la matrice completa dei temi di AI micro-SaaS →