Clean Architecture: guida pratica per chi deve spedire software

La clean architecture è una di quelle idee che quasi tutti citano e pochi applicano con criterio: c'è chi la ignora e vive in un fango di dipendenze, e chi la applica come dogma e trasforma un CRUD in quaranta file di cerimonia. In Lasting Dynamics la usiamo su sistemi in produzione da anni e la insegniamo nella nostra academy — questa guida è il modo in cui la spieghiamo ai nostri: pratico, con la regola che conta, i confini che contano, e il coraggio di dire quando non usarla.

L'unica regola che conta davvero

Tolti i diagrammi a cerchi concentrici, la clean architecture (Robert C. Martin, 2012 — ma l'idea è più vecchia: hexagonal architecture, ports & adapters, onion architecture sono parenti stretti) si riduce a una regola sola:

Le dipendenze puntano verso l'interno: la logica di business non sa nulla di database, framework, UI o servizi esterni.

Tutto il resto — entities, use case, interface adapters, frameworks — è un modo di organizzare questa regola in livelli. Il cuore è: il codice che decide cosa fa il tuo sistema non importa express, non importa prisma, non conosce HTTP. Sono i dettagli tecnici a dipendere dalle decisioni di business, mai il contrario.

Perché è la regola giusta? Perché i dettagli cambiano e le regole di business restano. In dieci anni di progetti abbiamo cambiato ORM, database, provider di pagamento, framework frontend — più volte. Le regole di business dei clienti sono sopravvissute a tutto. Un'architettura che lega le seconde ai primi paga quel cambio ogni volta, con gli interessi.

Come si presenta in un progetto vero

Dimentica i quattro cerchi per un attimo; in un progetto tipico la sostanza è questa:

src/
  domain/          ← entità e regole di business. Zero import esterni.
  application/     ← use case: orchestrano il dominio. Definiscono
                     INTERFACCE per ciò che serve (repository, mailer…)
  infrastructure/  ← implementazioni concrete: Postgres, Stripe, SMTP.
                     Implementano le interfacce di application.
  interface/       ← HTTP handlers, CLI, UI: traducono il mondo esterno
                     in chiamate agli use case.

Il meccanismo che fa funzionare tutto è l'inversione delle dipendenze: lo use case dichiara interface ApplicationRepository { save(app): ... } e non sa se dietro c'è Postgres, un file o un mock nei test. L'implementazione concreta sta fuori e viene iniettata.

I benefici sono immediati e misurabili:

• Testabilità. Gli use case si testano in millisecondi senza database né rete. La suite gira in secondi, e i test veloci sono test che si scrivono davvero.
• Sostituibilità. Cambiare ORM o provider tocca infrastructure/, non le regole.
• Leggibilità dell'intenzione. application/submit-application.ts racconta cosa fa il sistema; il codice diventa documentazione del business.

Dove la gente sbaglia (in entrambe le direzioni)

Errore 1 — Il dogma dei layer. Quattro livelli, mapper tra ogni livello, DTO per ogni passaggio: per un form che salva una riga in tabella sono 300 righe di cerimonia per 10 di logica. La clean architecture protegge la logica di business; se la logica di business è "salva e mostra", non c'è niente da proteggere. Un CRUD può restare un CRUD.

Errore 2 — I confini finti. Layer che esistono nei nomi delle cartelle ma non nelle dipendenze: il "dominio" che importa l'ORM, lo use case che legge req.headers. È il peggio dei due mondi — la cerimonia senza i benefici. Il test è meccanico: cosa importa il tuo dominio? Se la risposta non è "niente di esterno", i confini sono decorativi.

Errore 3 — L'astrazione preventiva su tutto. Interfacce per cose che non cambieranno mai, "per sicurezza". Le astrazioni si pagano in indirezione; falle dove il cambiamento è plausibile (storage, servizi esterni, canali di I/O), non ovunque per principio.

Errore 4 — Confondere clean architecture con microservizi. Sono ortogonali. Un monolite con confini interni puliti è un'ottima architettura — e, di solito, il punto di partenza giusto. I confini interni ben fatti sono anche ciò che rende possibile estrarre un servizio domani, se mai servirà.

Quando ripaga e quando è overkill

Vale la pena quando: la logica di business è vera (regole, stati, calcoli, policy), il sistema vivrà anni, il team è più di una persona, o i dettagli tecnici sono instabili (capita più spesso di quanto si pensi).

È overkill quando: è un prototipo, un tool interno usa-e-getta, un CRUD sottile su un database — o quando il team non ha ancora il giudizio per tracciare i confini giusti, perché confini sbagliati costano più di nessun confine.

La versione onesta della best practice: parti semplice, ma tieni la regola delle dipendenze come bussola. Anche in un progetto piccolo, tenere la logica fuori dai controller HTTP costa quasi zero e lascia aperta ogni strada.

Nell'era degli agenti AI conta di più, non di meno

Un dettaglio che è diventato centrale: gli strumenti di agentic coding lavorano molto meglio su codebase con confini chiari. Un agente che deve modificare una regola di business in un sistema con dominio isolato tocca un file e i suoi test; nello spaghetti tocca venti file e speri. I confini architetturali sono il modo in cui anche l'AI capisce dove mettere le mani — l'abbiamo scritto anche nella guida a Claude Code: l'architettura la decidi tu, l'AI riempie la struttura.

Come si impara davvero

La clean architecture non si impara dai diagrammi — si impara tracciando confini su sistemi veri e facendosi dire da qualcuno più esperto perché quel confine è nel posto sbagliato. È esattamente il formato della Lasting Dynamics Academy: le architetture software sono nel curriculum accanto a design pattern, RDBMS e testing, allenate con task reali e una review settimanale col mentore. Gratuita, full remote, a numero chiuso, e chi completa riceve un'offerta di lavoro. Se questa guida ti è sembrata ragionevole, le candidature sono aperte.

Domande frequenti

Clean architecture ed esagonale sono la stessa cosa? Parenti strettissimi: hexagonal (ports & adapters), onion e clean condividono l'idea centrale — dominio al centro, dipendenze verso l'interno, dettagli ai bordi. Le differenze sono di terminologia e granularità dei livelli. Scegline una e sii coerente; litigare sui nomi è tempo perso.

Va bene per il frontend? Il principio sì: separare la logica di stato e di business dai componenti UI (che sono "dettaglio" quanto il database). L'apparato completo dei layer di solito è troppo; la regola delle dipendenze basta e avanza.

Da dove comincio su un codebase esistente? Dal prossimo pezzo di logica che devi toccare: estrailo in una funzione pura, dagli un'interfaccia per le sue dipendenze, coprilo di test. La clean architecture su un sistema legacy si conquista un confine alla volta, non con il big bang.