Asset
Il contratto di integrazione oltre lo schema
Un contratto d'integrazione governa struttura, semantica, ownership, compatibilità ed errori operativi: validare il payload è necessario ma non sufficiente.
Il contratto non finisce nello schema
OpenAPI e JSON Schema descrivono struttura, vincoli ed esempi, ma non tutte le aspettative tra producer e consumer. Un contratto architetturale comprende significato dei dati, proprietari della verità, compatibilità nel tempo e comportamento atteso sotto errore, ritardo o ripetizione.
La stessa stringa può raccontare fatti diversi
Responsabilità e confini
Specificare chi possiede il dato, chi può cambiarne il significato, chi pubblica il contratto e chi approva cambiamenti incompatibili. Un sistema può essere autorevole per l'identità cliente e non per lo stato di pagamento: non confondere ownership del messaggio con ownership di ciascuna informazione.
Versionare anche il comportamento
Aggiungere campi opzionali non è sempre innocuo: consumer rigidi, nuovi valori enum o cambi di semantica possono rompere flussi esistenti. Definire politica di evoluzione, deprecazione, test tra producer e consumer e finestra di transizione; distinguere compatibilità sintattica da compatibilità semantica.
Il contratto nelle condizioni difficili
Timeout, retry, idempotenza, ordering, duplicati e stati incerti devono avere un significato condiviso, adeguato al tipo di interazione. Una risposta in timeout non prova che l'operazione non sia stata eseguita. Definire strategie di correlazione e riconciliazione e rendere espliciti gli errori di business e tecnici.
Modello a livelli di un contratto di integrazione: struttura, semantica, ownership, compatibilità e comportamento operativo
Checklist della design review
Tag