Esagono API: Architettura Esagonale per API robuste, modulari e facili da testare

Nel panorama dello sviluppo software moderno, una delle sfide più comuni è creare API che siano robuste, facili da estendere e semplici da mantenere nel tempo. L’approccio noto come Esagono API, o Architettura Esagonale, offre una cornice concettuale che permette di separare in modo netto il cuore della logica di dominio dalle dipendenze esterne come database, UI, servizi esterni e infrastrutture. In questa guida approfondita esploreremo cosa sia Esagono API, perché è utile, come implementarla passo dopo passo e quali sono i migliori scenari di applicazione. Se vuoi costruire API che resistano al tempo e alle evoluzioni tecnologiche, l’Esagono API può diventare il tuo faro.

Che cos’è Esagono API e perché è importante

Esagono API, spesso chiamata Architettura Esagonale, è un modello di progettazione che mette al centro la logica di dominio e definisce una serie di porte (ports) e adattatori (adapters) per incorrere meno dipendenze con il mondo esterno. L’obiettivo principale è fornire una separazione di interessi: il core della tua applicazione resta indipendente dai dettagli di implementazione delle sorgenti dati, dei servizi esterni o dell’interfaccia utente. In pratica, Esagono API crea un anello interno che contiene le regole di business e un insieme di ponti che collegano quel dominio alle varie outer world, come API REST, GraphQL, code di messaggistica, logica di persistenza e tool di monitoraggio.

La scelta di utilizzare Esagono API non è casuale. L’architettura esagonale permette di rispondere a domande comuni durante lo sviluppo: come sostituire un database senza toccare la logica di dominio? Come testare il core senza dipendenze reali? Come aggiornare un componente di integrazione senza dover riscrivere intere parti dell’applicazione? Nel caso dell’esagono api, l’attenzione è posta sul rendere l’aggiunta di nuovi canali di accesso o di nuove fonti di dati una semplice operazione di estensione, piuttosto che una migrazione rischiosa di codice esistente.

Il concetto chiave dell’Esagono API affonda le radici nell’architettura esagonale proposta da Alistair Cockburn, spesso nota come Ports and Adapters. Quella che promette una struttura a sei lati non è una forma geometrica casuale, ma una metafora functionale: al centro c’è il dominio, protetto da porte che definiscono come interagire con il mondo esterno e da adattatori che implementano quelle interfacce per le diverse tecnologie esterne.

Origini: Ports, Adapters e la protezione del dominio

L’idea centrale è che il cuore dell’applicazione non debba conoscere l’implementazione concreta di database, UI o servizi esterni. Le porte rappresentano contratti che definiscono cosa può chiedere l’esterno al cuore dell’applicazione (input), e cosa il cuore può fornire all’esterno (output). Gli adattatori, a loro volta, implementano questi contratti in modo concreto: una porta di input potrebbe essere un controller REST che traduce una richiesta HTTP in un comando/domain event, mentre un adattatore di output potrebbe tradurre una risposta di dominio in JSON o scrivere su un database.

Per capire appieno Esagono API è utile fissare alcuni principi cardine che guidano ogni design successivo:

• Decoupling: il dominio non è legato a framework, database o API esterne; cambia l’implementazione degli adattatori senza toccare il cuore della logica di dominio.
• Testabilità: grazie ai contratti chiari tra dominio, porte e adattatori, è possibile testare il core con mock o stub delle porte, senza dipendenze reali.
• Flessibilità: l’architettura esagonale facilita l’introduzione di nuovi canali di accesso o nuove fonti dati, limitando al minimo l’impatto sulle componenti esistenti.
• Isolamento del dominio: la logica di business risiede in un nucleo stabile, che resta invariato dall’evoluzione delle interfacce esterne.
• Inversione delle dipendenze: le dipendenze puntano verso l’interno, verso il dominio, non verso gli elementi esterni, facilitando la sostituzione di componenti.

Immagina Esagono API come un modello a sei lati centrato su un nucleo di dominio. In un’applicazione tipica, troverai:

• Nucleo di dominio: contiene enti, regole di business, logica applicativa e casi d’uso. È l’essenza dell’API.
• Porte (Ports): interfacce che definiscono come il nucleo può essere interrogato o comandato dall’esterno. Sono contratti astratti, indipendenti da tecnologie specifiche.
• Adattatori (Adapters): implementazioni concrete delle porte per vari strumenti, come REST API, GraphQL, eventi, code di messaggi, o accesso a database.
• Infrastruttura: componenti che forniscono servizi comuni (log, configurazione, sicurezza, gestione delle transazioni) e che non fanno parte del dominio ma supportano i flussi di lavoro.

Nell’Esagono API, una richiesta in ingresso passa attraverso una porta di input (ad esempio un controller REST) che traduce la domanda in un comando del dominio. Il dominio esegue la logica, può generare eventi o chiamate a servizi, e restituisce una risposta che viene formattata dall’adattatore di output per tornare al chiamante. Questo flusso ragiona in modo molto chiaro: l’implementazione dell’adattatore è sostituibile, senza toccare la logica di dominio.

Pattern correlati all’Esagono API

• Anti-Corruption Layer (ACL): protezione del dominio da dipendenze pesanti o instabili, traducendo tra modelli di dati diversi.
• Dipendency Inversion Principle (DIP): le dipendenze puntano verso astrazioni, non verso implementazioni concrete.
• Event Sourcing e Command Query Responsibility Segregation (CQRS): quando utile, l’Esagono API può usare eventi per comunicare con i sistemi esterni, mantenendo la coerenza tra dominio e persistenza.

Adottare Esagono API comporta una serie di benefici tangibili:

• Testabilità avanzata: è possibile testare il dominio in isolamento, senza dover configurare database o servizi esterni.
• Manutenibilità a lungo termine: i cambiamenti nelle interfacce esterne richiedono interventi limitati agli adattatori, non al core di dominio.
• Scalabilità e flessibilità: è più semplice evolvere l’API includendo nuovi adattatori (ad es. supporto a GraphQL o eventi asincroni) senza rinunciare alla coerenza del modello.
• Isolamento delle dipendenze: la logica di business non teme le evoluzioni tecnologiche che riguardano infrastruttura, UI o servizi di terze parti.

Seguire una procedura ordinata facilita la riuscita di un progetto basato sull’architettura esagonale. Ecco una guida pratica per iniziare con Esagono API:

1) Definire il dominio e i casi d’uso

Inizia mappando le entità principali, i loro comportamenti e i casi d’uso chiave. Il dominio deve riflettere le regole di business in modo chiaro e consistente. In questa fase cerca di mantenere i confini del dominio ben definiti e stai attento a non introdurre logica di presentazione o infrastruttura all’interno del nucleo.

2) Progettare le porte

Identifica le porte di input e output necessarie per esporre la funzionalità. Le porte di input rappresentano le azioni che possono essere invocate dall’esterno (comandi, query) mentre le porte di output definiscono come reagire o come notificare il mondo esterno (servizi esterni, persistenza, messaggistica).

3) Implementare gli adattatori

Per ogni porta, sviluppa uno o più adattatori concreti. Ad esempio, un adattatore REST che traduca le richieste HTTP in comandi di dominio o un adattatore di persistenza che implementi l’interfaccia della porta di output using una specifica tecnologia di database.

4) Configurazione e injection

Collega le porte agli adattatori tramite un container di iniezione delle dipendenze o un factory di configurazione. L’obiettivo è che il dominio non conosca mai la collocazione reale dei componenti esterni.

5) Strategie di test

Con Esagono API, i test dovrebbero coprire principalmente il dominio, simulando le porte con mock o stub. I test di integrazione possono verificare il flusso end-to-end attraverso gli adattatori, ma senza compromettere la semplicità del dominio.

6) Evoluzione e manutenzione

Quando si aggiungono nuovi strumenti, come un database diverso o un nuovo tipo di client API, si implementano nuovi adattatori o si sostituiscono quelli esistenti, senza toccare la logica di dominio. Questo è il cuore dell’efficacia di Esagono API.

Immagina una piattaforma di e-commerce con una API per la gestione degli ordini. Con Esagono API, il nucleo di dominio gestisce stati, regole di business (stato dell’ordine, condizioni di pagamento, logica di evasione); le porte definiscono come creare un ordine, aggiornare lo stato, o recuperare una lista di ordini. Gli adattatori includono:

• Adattatore REST per i client web/mobile: traduce richieste HTTP in comandi di dominio come CreateOrderCommand, e restituisce risposte in JSON.
• Adattatore di persistenza: implementa l’interfaccia di output per salvare l’ordine in un database PostgreSQL o in una coda event-driven.
• Adattatore di integrazione: comunica con servizi esterni di pagamento o di logistica tramite API client dedicati.
• ACL per integrazione esterna: se necessario, traduce i modelli di dati tra dominio e sistema di pagamento, minimizzando la contaminazione delle regole di business.

Un altro scenario riguarda una API di gestione utenti. L’Esagono API facilita l’aggiunta di nuovi canali di autenticazione (OAuth, SAML, one-time password) senza modificare la logica di business: basta introdurre nuovi adattatori di autenticazione che si connettono alle porte di input e output.

Per valutare l’efficacia di Esagono API nel tuo progetto, considera metriche qualitative e quantitative:

• Tasso di cambiamento ridotto: minore impatto delle modifiche infrastrutturali sul dominio.
• Copertura di test sul nucleo: ampia gamma di test unitari e di integrazione per il cuore dell’applicazione.
• Tempo di onboarding per nuove integrazioni: integrazione rapida di nuovi adattatori senza intervento sul dominio.
• Resilienza e facilità di refactoring: capacità di sostituire componenti esterni senza rischi per la logica di dominio.

In confronto alle architetture tradizionali, come la classica architettura a livelli (presentation, service, persistence), Esagono API offre una separazione più netta tra dominio e infrastruttura. Mentre una struttura a strati può portare a dipendenze cicliche e test difficili, l’architettura esagonale evita l’overcoupling e facilita il test, la sostituzione e l’evoluzione delle parti esterne. Inoltre, nell’ambito di API moderne, Esagono API si allinea bene con microservizi, manutenibilità a lungo termine e gestione di API multiple attraverso adattatori specifici per ogni canale di comunicazione.

Per ottenere i migliori risultati con Esagono API, tieni a mente alcune best practice:

• Inizia dal dominio: definisci regole di business e casi d’uso prima di pensare all’UI o all’infrastruttura.
• Definisci contratti chiari: porte ben definite facilitano la sostituzione degli adattatori e riducono i rischi di regressione.
• Mantieni gli adattatori leggeri: limiti all’implementazione specifica e focalizzati sulla traduzione tra modelli di dati e contratti.
• Testa in isolamento: sfrutta mock delle porte per testare in modo affidabile la logica di dominio.
• Allinea la governance della sicurezza: integra meccanismi di autorizzazione e autenticazione tramite adattatori senza intaccare il dominio.

Esistono numerosi linguaggi e framework che si prestano bene a un’implementazione di Esagono API. Alcuni esempi comuni includono:

• Java con Spring (Spring Boot, Spring Cloud) per creare adattatori REST/GraphQL e componenti di infrastruttura modulabili.
• .NET con ASP.NET Core per API robuste e una mentalità DI (Dependency Injection) che si integra bene con pattern di architettura esagonale.
• Node.js con Express o NestJS per prototipi rapidi, con una chiara separazione tra dominio e adattatori.
• Event-driven design: utilizzo di Apache Kafka, RabbitMQ o altri broker di eventi per scenari CQRS/Event Sourcing.
• Strumenti di test come JUnit, xUnit o Jest per testare il dominio in isolamento e test di integrazione per gli adattatori.

Di seguito trovi un esempio descrittivo di come appare la separazione tra dominio e adattatori in un contesto di gestione ordini. Nota che si tratta di una descrizione testuale: i nomi possono variare a seconda del linguaggio e del framework scelto.

Dominio (core):

• Entità: Order, OrderLine
• Servizi di dominio: PlaceOrder, CancelOrder
• Interfacce di porta (input/output): IOrderService, IOrderRepository

Porta di input (ad es. REST controller):

• Endpoint: POST /orders
• Traduzione: REST request => PlaceOrderCommand => dominio

Adattatore di output (persistence):

• IOrderRepository implementato da OrderDatabaseAdapter
• Traduzione: Order aggregate => salvataggio nel database

Adattatore di output (infrastruttura di evento):

• EventPublisherAdapter che invia eventi di dominio a una coda

Esagono API è complicato da implementare?

può essere inizialmente introdotto in modo incrementale. Si parte da un dominio solido e si aggiungono porte e adattatori man mano che servono integratori o nuove interfacce.

È adatto a progetti piccoli?

Sebbene possa sembrare eccessivo per progetti estremamente ridotti, Esagono API offre una base solida che facilita la crescita e la manutenibilità, anche in contesti con poche risorse.

Come si misura la qualità di Esagono API?

Con una combinazione di metriche di test, copertura delle porte, modularità del dominio e facilità di sostituzione degli adattatori.

Esagono API rappresenta una robusta filosofia di progettazione per API moderne. L’architettura esagonale consente di isolare la logica di dominio, ridurre le dipendenze con infrastruttura e servizi esterni, facilitare il test e accelerare l’evoluzione dell’applicazione. Se vuoi creare API che resisteranno alle sfide del tempo, adottare Esagono API può essere una scelta strategica. Diagnosi, pianificazione e una fase di implementazione graduale ti permetteranno di ottenere i benefici fin dai primi sprint, mantenendo sempre una visione chiara del core della tua applicazione.

Per chi desidera approfondire l’argomento, ecco alcune direzioni utili:

• Riferimenti sull’Architettura Esagonale (Ports and Adapters) e su come tradurli in pratica per API moderne.
• Guide pratiche su come definire Porte e Adattatori, con esempi in diversi linguaggi.
• Esempi di implementazioni reali in progetti di API shipping e microservizi.