Issue 10001 · Integrazione
Contratti di integrazione: oltre lo schema
Quando il payload è corretto, ma semantica, ownership e scenari di fallimento restano ambigui.
· 5 min
Obiettivo
Recognize why successful enterprise integrations require explicit contracts covering data meaning, ownership, compatibility, failure behavior and operational expectations.
Cosa deve chiarire davvero un contratto
In un’integrazione enterprise, lo schema è solo il primo livello. Ti dice quali campi esistono, ma non ti dice cosa significano, chi li governa, quali valori sono stabili e come comportarsi quando il processo si inceppa. Da Solution Architect, la domanda utile non è solo: “L’API valida?”. È: “Produttore e consumatore hanno lo stesso modello operativo e semantico?”. Se la risposta è no, il sistema può restare tecnicamente compatibile e rompere comunque il business. Un contratto utile dovrebbe coprire almeno questi punti: - significato del dato, non solo formato; - ownership del campo o del concetto condiviso; - compatibilità attesa tra versioni; - comportamento in caso di timeoutGlossarioTimeoutUn limite definito a quanto un’operazione attende prima di considerare il tentativo non riuscito.Apri la voce completa, retryGlossarioRetryUn nuovo tentativo eseguito dopo un fallimento che potrebbe essere transitorio.Apri la voce completa, duplicati o dati mancanti; - responsabilità operative quando qualcosa fallisce. Questo cambia il modo in cui fai review: non stai solo controllando un payload, stai verificando se l’integrazione è sostenibile nel tempo.
I trade-off che devi esplicitare
Il vantaggio di un contratto esplicito è la riduzione dell’ambiguità. Le squadre smettono di interpretare i campi “a memoria” e puoi gestire il cambiamento con meno sorprese. Il costo è che devi investire tempo prima: allineamento tra team, decisioni su ownership, regole di compatibilità e comportamento operativo. All’inizio sembra più lento rispetto a “mandiamo il JSON e vediamo”. In realtà stai spostando il costo dall’incidente alla progettazione. Ci sono anche compromessi da accettare: - più rigore sul contratto significa meno libertà di reinterpretazione locale; - una semantica ben definita può richiedere proiezioni diverse per consumer diversi; - alcune evoluzioni non possono essere trattate come semplici aggiunte di campi e vanno negoziate come cambi di dominioGlossarioDominioLa parte del mondo reale, del business o dell’organizzazione che un sistema deve supportare.Apri la voce completa. La regola pratica è semplice: se un campo è condiviso tra più sistemi, la sua definizione non può vivere solo nel codice del producer o nel ricordo di un analista.
Esempio realistico in azienda
Immagina un gruppo retail con ordine, billing e fulfilment separati. Il servizio Ordini pubblica orderStatus. A prima vista tutto sembra chiaro, ma per billing “Pending” significa pagamento non ancora confermato, mentre per fulfilment significa magazzino non ancora assegnato. Il payload è valido per tutti. Il problema è che il significato non è unico. Quando il team Ordini introduce un nuovo stato, billing continua a processarlo come prima, fulfilment invece blocca alcune spedizioni. Nessuno ha rotto lo schema, ma il flusso end-to-end si è degradato. Con un contratto corretto, il team avrebbe dovuto dichiarare: - chi possiede il significato di orderStatus; - quali stati sono business-stable; - come devono reagire i consumer a nuovi valori; - quali errori sono retryable; - come si gestiscono duplicati e timeout. In pratica, il contratto avrebbe evitato che ogni team inventasse una propria verità sullo stesso campo.
Per approfondire
Una fonte primaria per collegare il contratto dichiarato al comportamento effettivo tra consumer e provider. • Pact — Contract testing: https://docs.pact.io/