Clean Architecture: gli strati che proteggono il dominio

L'idea centrale: la regola della dipendenza

La Clean Architecture, formalizzata da Robert C. Martin (Uncle Bob) nel 2012, ha un'unica regola fondamentale: le dipendenze del codice sorgente puntano solo verso l'interno. I cerchi esterni (framework, database, UI) dipendono dai cerchi interni (business rules, entità). Mai il contrario. Un'entità non importa mai un controller. Un use case non importa mai un framework.

Questa regola produce un effetto pratico: il core dell'applicazione — la business logic — è completamente indipendente da come viene consegnata (web, CLI, API) e da dove i dati vengono salvati (PostgreSQL, file, API esterna). Puoi cambiare il framework senza toccare una riga di business logic.

I quattro cerchi

1. Entities (cerchio interno)

Le Entities contengono le regole di business più generali: quelle che non cambiano quando cambia il modo di consegnare l'applicazione. Un'entità Order con le regole di calcolo totale, validazione degli stati e politiche di cancellazione. Queste regole valgono sia per il web che per un'app mobile o un import batch.

2. Use Cases (application business rules)

Gli Use Cases orchestrano le entità per realizzare le operazioni specifiche dell'applicazione: PlaceOrder, CancelOrder, GenerateMonthlyReport. Ogni use case è una classe con un metodo execute() che coordina entità e servizi di dominio. Gli use case definiscono le interfacce (ports) per accedere al mondo esterno.

3. Interface Adapters

Gli Adapter traducono tra il formato dei dati del mondo esterno e il formato del dominio. Controller, Presenter, Gateway. Il controller traduce la HTTP request in un DTO per lo use case. Il presenter traduce il risultato dello use case in un ViewModel per la view. Il gateway implementa l'interfaccia del repository definita dallo use case.

4. Frameworks & Drivers (cerchio esterno)

Il cerchio più esterno contiene i dettagli: il framework web, il driver del database, il template engine, le librerie di terze parti. Questi componenti sono plug-in che si collegano ai cerchi interni tramite le interfacce. Sono i più facili da sostituire perché nulla di importante dipende da loro.

Clean Architecture vs Hexagonal

Clean Architecture e Hexagonal Architecture condividono lo stesso principio (le dipendenze puntano verso il dominio) ma hanno sfumature diverse:

• Hexagonal: due lati — driving (chi usa il dominio) e driven (chi il dominio usa). Focus sulla simmetria dei ports.
• Clean: quattro cerchi concentrici con granularità maggiore. Distingue Entities da Use Cases da Adapters. Focus sulla direzione delle dipendenze.

In pratica, per un progetto PHP di dimensioni medie, le differenze sono sottili. Entrambe producono lo stesso risultato: business logic isolata e testabile.

Esempio pratico: struttura di directory

• src/Domain/ — Entities, Value Objects, Domain Services, Repository Interfaces
• src/Application/ — Use Cases (Command/Query Handlers), DTOs, Application Services
• src/Infrastructure/ — Repository implementations, External API clients, Email services
• src/Presentation/ — Controllers, ViewModels, API Resources, CLI Commands

Le dipendenze: Presentation → Application → Domain. Infrastructure → Application → Domain. Domain non importa nulla dagli altri layer.

Il costo della Clean Architecture

La Clean Architecture ha un costo reale: più classi, più interfacce, più trasformazioni di dati tra layer. Un semplice CRUD che in Laravel richiede un Controller e un Model, in Clean Architecture richiede: Controller, Request DTO, Use Case, Response DTO, Entity, Repository Interface, Repository Implementation, ViewModel. Per un blog con 5 pagine, questo è over-engineering.

Quando usare la Clean Architecture

• Usa Clean Architecture quando il dominio è complesso e la business logic deve essere protetta da cambiamenti tecnologici
• Usa Clean Architecture quando il progetto ha una vita lunga (3+ anni) e il framework potrebbe cambiare
• Usa Clean Architecture quando la testabilità del dominio è un requisito non negoziabile
• Non usare Clean Architecture per prototipi, MVP o CRUD semplici: il costo di astrazione supera il beneficio
• Non usare Clean Architecture se il team non la capisce: una Clean Architecture mal implementata è peggio di un monolite ben organizzato

La Clean Architecture non è un dogma: è un set di principi. Puoi adottarla parzialmente — separare il dominio dalla persistenza senza creare quattro cerchi formali. Il valore sta nel principio (dipendenze verso l'interno), non nella struttura rigida.