Cos'è l'architettura esagonale (ports and adapters)?

L'architettura esagonale, chiamata anche ports and adapters (porte e adattatori), è un modo di organizzare un'applicazione in cui il nucleo, cioè le regole di business, non parla mai direttamente con database, interfacce utente o servizi esterni. Comunica solo tramite porte, interfacce che l'applicazione stessa definisce e che prendono il nome dal loro scopo, per esempio "per ottenere le aliquote fiscali". Per ogni tecnologia da collegare c'è un adattatore, il codice che traduce fra la porta e quel sistema specifico. L'ha proposta Alistair Cockburn in un rapporto tecnico del 2005, con un obiettivo preciso: far usare l'applicazione allo stesso modo da persone, altri programmi, test automatici o procedure pianificate, e poterla sviluppare e testare senza i database e i dispositivi con cui girerà davvero. L'esagono non ha niente a che fare con il numero sei: lascia spazio per disegnare le porte, che nel 2005 Cockburn preferiva limitare a due, tre o quattro.

Leggi anche: CQRS · Separare il modello che scrive i dati da quello che li legge, invece di usarne uno solo per entrambi i compiti.

Cosa si ottiene e cosa si paga

Il primo vantaggio è la testabilità: un adattatore può essere un finto database in memoria, così i test automatici verificano la logica di business senza quello vero. Il secondo è la sostituibilità: nelle slide di un intervento del 2025 Cockburn elenca fra i benefici la possibilità di cambiare i sistemi collegati, all'avvio o nel corso degli anni, senza toccare il nucleo. È una difesa concreta dal vendor lock-in nel codice: la dipendenza dal fornitore resta chiusa nel suo adattatore invece di spargersi in tutto il programma. Il terzo è l'integrazione: ogni funzione esposta su una porta è usabile anche da un altro programma.

Le stesse slide dedicano una pagina ai costi ("Costs"). Ogni sistema esterno che l'applicazione chiama richiede un punto di aggancio, e serve un componente che all'avvio monta i pezzi giusti; nei linguaggi tipizzati come Java servono anche interfacce dichiarate e cartelle dedicate alle porte. La guida AWS ai pattern cloud del 2024 aggiunge che gli adattatori sono giustificati solo se le sorgenti e le destinazioni dei dati sono più d'una, o se cambieranno nel tempo; altrimenti sono un livello in più da mantenere. In ogni caso possono aggiungere latenza. Non è una scelta di topologia: riguarda l'interno di un singolo programma, e vale tanto per un monolite quanto per un microservizio.

Un esempio enterprise

Un'azienda di distribuzione vende online e il suo gestionale ordini chiama le API del fornitore di pagamenti in decine di punti: conferme, resi, rimborsi. Se un fornitore concorrente offre commissioni più basse, il cambio tocca tutto il codice e richiede un collaudo completo. Con l'architettura esagonale il nucleo conosce solo una porta "per incassare un pagamento" e il fornitore vive in un adattatore. Cambiare significa scriverne uno nuovo e collegarli entrambi alla stessa porta per qualche tempo, perché i rimborsi dei pagamenti già incassati passano ancora dal vecchio fornitore. Lo stesso vale per l'ERP: dietro una porta "per registrare una fattura", vecchio e nuovo sistema possono convivere durante una sostituzione per gradi, secondo lo strangler fig pattern. La porta però non rende il cambio gratuito: se il nuovo fornitore gestisce i rimborsi in modo diverso, bisogna ripensare anche quella.

Perché conta per chi decide

È un investimento pagato in anticipo, che rende solo se qualcosa cambierà (un fornitore, un database, un canale in più) o se servono test automatici affidabili. In un'applicazione piccola che si limita a creare, leggere e aggiornare record è quasi sempre lavoro sprecato. Jeffrey Palermo dice lo stesso dell'affine onion architecture, che ha descritto nel 2008: la sconsiglia per i siti piccoli e la indica per le applicazioni di business di lunga durata. Nemmeno le guide AWS concordano fra loro: una del 2022 la raccomanda per ogni progetto enterprise a prescindere dalla complessità, dentro ciascun bounded context. Prima di approvarla chiedo un elenco, non un sì: quali sistemi esterni si prevede di sostituire, e se isolarli oggi costa meno che riscrivere domani il codice che li usa.