Issue 10010 · Integrazione
Claim Check Pattern: tenere piccoli i messaggi, senza perdere governance
Quando il payload non deve viaggiare nel broker: reference, ownership e controlli da chiarire prima di andare in produzione
· 5 min
Obiettivo
Usare il Claim Check pattern per mantenere i messaggi piccoli e sicuri, archiviando payload grandi o sensibili all’esterno e passando riferimenti attraverso il flusso di messaggistica.
Cosa fare in pratica
Il Claim Check pattern serve quando il messaggio non dovrebbe contenere il payload completo, ma solo un riferimento a un contenuto archiviato altrove. In pratica, il producer salva il documento o i dati pesanti in uno store autorevole e pubblica nel messaggio un identificativo, un URI o un token di recupero. Da architetto, il punto non è solo “ridurre la size del messaggio”. Il vero obiettivo è separare il trasporto dalla gestione del dato quando cambiano i requisiti di sicurezza, retention, auditing o dimensione. Questo significa chiarire subito tre cose: chi possiede il payload, chi può leggerlo e per quanto tempo il riferimento resta valido. Se il consumer deve recuperare il contenuto più tardi, il contratto del messaggio cambia: il messaggio non è più autosufficiente, quindi devi progettare bene idempotenzaGlossarioIdempotenzaLa proprietà per cui ripetere un’operazione non produce effetti aggiuntivi indesiderati.Apri la voce completa, retryGlossarioRetryUn nuovo tentativo eseguito dopo un fallimento che potrebbe essere transitorio.Apri la voce completa e gestione degli errori quando il contenuto non è disponibile o non è più accessibile. Il pattern funziona bene se il riferimento è trattato come una parte esplicita del contratto di integrazione, non come un dettaglio tecnico nascosto.
Trade-off da esplicitare
Il guadagno principale è evidente: messaggi più piccoli, broker meno stressato, meno rischi di superare limiti di payload e maggiore controllo su dati sensibili e politiche di retention. In alcuni casi ottieni anche una governance migliore, perché il contenuto può stare in uno store con audit, cifratura e accesso più granulari. Il costo è la complessità aggiuntiva. Hai due risorse da coordinare: il messaggio e il contenuto esterno. Questo introduce nuovi failure mode, come riferimenti scaduti, contenuti già cancellati, accessi non autorizzati o ritardi nel recupero. Inoltre, se lo store non è davvero autorevole, rischi di creare una soluzione fragile che sposta il problema invece di risolverlo. Il trade-offGlossarioTrade-offUno scambio in cui migliorare un risultato ne indebolisce o ne rende più costoso un altro.Apri la voce completa più importante da discutere in design review è questo: vuoi un messaggio più semplice da trasportare, oppure vuoi un eventoGlossarioEventoUna dichiarazione durevole che qualcosa di significativo è già accaduto.Apri la voce completa completamente self-contained? Se il consumer deve poter elaborare offline o con forte disaccoppiamento temporale, il Claim Check può diventare un vincoloGlossarioVincoloUna condizione che limita lo spazio delle soluzioni praticabili e non può essere semplicemente ignorata.Apri la voce completa. Se invece il payload è grande, sensibile o soggetto a policy rigorose, il pattern è spesso la scelta più pulita.
Esempio enterprise realistico
Immagina un processo di onboarding documentale in una banca. L’applicazione di front office carica documenti KYC e allegati PDF; questi file non devono viaggiare nel bus eventi interno né essere duplicati in più code. Il producer salva i documenti in uno storage governato, con cifratura e retention definite, e pubblica un evento con il claim check. Il servizio downstream riceve il riferimento, verifica i propri diritti di accesso e recupera i documenti solo quando deve eseguire i controlli. In questo scenarioGlossarioScenarioUna situazione concreta usata per testare come un design o una decisione si comporta.Apri la voce completa il vantaggio è doppio: i messaggi restano leggeri e il documento vive in un dominioGlossarioDominioLa parte del mondo reale, del business o dell’organizzazione che un sistema deve supportare.Apri la voce completa di storage più adatto a policy di compliance e audit. Se però il team non definisce bene ownership e lifecycle, emergono problemi immediati: documenti cancellati prima del consumo, retry che falliscono in modo non deterministico, oppure integrazioni che iniziano a dipendere da un recupero sincrono troppo lento. Qui il Claim Check funziona solo se architettura applicativa, sicurezza e operations sono allineate.
Per approfondire
Riferimenti esterni autorevoli per approfondire il pattern e il suo uso in architetture di integrazione enterprise. • Claim Check - Enterprise Integration Patterns - https://www.enterpriseintegrationpatterns.com/patterns/messaging/StoreInLibrary.html • Message Design: payload, metadata e contratti di integrazione - Microsoft Azure Architecture Center - https://learn.microsoft.com/azure/architecture/guide/architecture-styles/event-driven • Design Patterns for Cloud Applications - Google Cloud Architecture Center - https://cloud.google.com/architecture/patterns