Architettura

Clean Architecture in Flutter: principi e implementazione

Guida completa alla Clean Architecture in Flutter: dalla regola delle dipendenze ai layer Domain, Data e Presentation, con struttura cartelle e best practice.

Fabrizio Billeci
Fabrizio Billeci
15 febbraio 2026 · 7 min di lettura
Clean Architecture in Flutter: principi e implementazione

Introduzione: perché l'architettura conta

Quando un'app Flutter cresce oltre il proof-of-concept, la domanda architetturale si fa pressante: come organizzare il codice in modo che resti manutenibile, testabile e scalabile? La risposta più citata è la Clean Architecture, introdotta da Robert C. Martin (Uncle Bob) nel 2012 e adattata da migliaia di team al mondo Flutter.

Questo articolo ti guida attraverso i principi, i layer, l'implementazione pratica in Flutter e quando ha senso adottarla — o quando invece può essere overkill.

Cos'è la Clean Architecture

La Clean Architecture è un approccio di progettazione software che separa l'applicazione in cerchi concentrici: i cerchi interni contengono la logica di business (le politiche), quelli esterni i dettagli implementativi (database, UI, framework). L'obiettivo è rendere il sistema indipendente da framework, database, UI e qualsiasi agenzia esterna.

I benefici dichiarati

  • Indipendenza dal framework: puoi sostituire Flutter con un altro framework senza stravolgere la logica.
  • Indipendenza dal database: swap tra SQLite, Firestore, API REST senza toccare le regole di business.
  • Indipendenza dalla UI: la stessa logica può servire mobile, web, CLI.
  • Testabilità: la business logic è testabile senza UI, DB o web server.

La regola delle dipendenze

Il cuore della Clean Architecture è la Dependency Rule: le dipendenze del codice possono puntare solo verso l'interno. Nessun cerchio interno può conoscere nulla di ciò che sta in un cerchio esterno. In altre parole, il Domain non deve importare Flutter, http, sqlite o qualsiasi package di infrastruttura. Solo il contrario è ammesso: i layer esterni dipendono da quelli interni, mai il contrario.

Questo si ottiene grazie al principio di Dependency Inversion: il dominio definisce interfacce (abstract repository, porte), e i layer esterni le implementano. Così il flusso di controllo va dalla UI verso il dominio, ma le dipendenze del codice vanno dalla UI verso il dominio — tramite le interfacce.

I layer nella Clean Architecture (versione Flutter)

In Flutter si usano tipicamente tre layer principali, che mappano i cerchi di Uncle Bob:

Domain Layer (centro)

È il cuore dell'applicazione. Contiene solo codice Dart puro, nessuna dipendenza da Flutter o da package esterni (http, firebase, ecc.).

  • Entities: oggetti di business, le regole aziendali più generali. Es: User, Product, Order.
  • Repository (abstract): interfacce che dichiarano come ottenere/salvare i dati. Es: abstract class UserRepository { Future<User> getUser(String id); }
  • Use Cases: casi d'uso dell'applicazione. Ogni use case incapsula una singola operazione (es. GetUserProfile, CreateOrder). Chiamano i repository e orchestrano il flusso dati.

Data Layer (esterno al Domain)

Implementa le interfacce definite nel Domain e gestisce fonti dati esterne.

  • Models: DTO e mapping da/verso JSON, API, database. Possono estendere o convertire le Entity.
  • Data Sources: Remote (chiamate HTTP) e Local (SQLite, Hive, SharedPreferences).
  • Repository Implementations: classi concrete che implementano i repository del Domain, coordinando data sources e mapping.

Presentation Layer (più esterno)

Gestisce UI e stato visuale. Usa Use Cases (o Controller/Bloc che a loro volta usano Use Cases), non i repository direttamente.

  • Widgets / Screens: l'interfaccia utente.
  • State management: BLoC, Cubit, Riverpod, Provider, ChangeNotifier — a scelta. La logica di presentazione comunica con i Use Cases.

Struttura delle cartelle

Una struttura tipica in Flutter:

lib/
├── core/           # errori, costanti, utils condivisi
├── data/
│   ├── datasources/   # remote, local
│   ├── models/
│   └── repositories/  # implementazioni
├── domain/
│   ├── entities/
│   ├── repositories/  # interfacce abstract
│   └── usecases/
├── presentation/
│   ├── bloc/      # o cubit, provider, ecc.
│   ├── screens/
│   └── widgets/
└── main.dart

Puoi organizzare per tipo (tutti i repository insieme) o per feature (cartella auth/ con entities, usecases, repository, UI di quell'area). La guida ufficiale Flutter (Compass app) propone un mix: data/domain per tipo, presentation per feature.

Use Cases: il ponte tra UI e Domain

I Use Cases incapsulano una singola azione di business. Esempio: GetUserProfile riceve un UserRepository (iniettato), chiama repository.getUser(id) e ritorna il risultato. La UI (o un Bloc/Riverpod) invoca il Use Case, non il repository direttamente. Così:

  • La logica di business resta riutilizzabile e testabile.
  • Puoi cambiare l'implementazione del repository senza toccare la presentation.
  • Ogni Use Case ha una responsabilità chiara (Single Responsibility).

Repository Pattern

Il Repository astrae l'origine dei dati. Il Domain definisce abstract class ProductRepository con metodi come getProducts(), addProduct(Product p). La Data Layer implementa ProductRepositoryImpl che può usare API REST, Firestore, cache locale — il Domain non lo sa. Questo permette di cambiare backend, aggiungere caching o mockare in test senza modificare il dominio.

Dependency Injection

Per rispettare la Dependency Rule, i Use Cases e i Controller ricevono i repository (e altre dipendenze) dall'esterno, tipicamente in main.dart o in un modulo di setup. In Flutter si usano spesso GetIt, Riverpod o Provider per iniettare le implementazioni concrete. Il Domain espone solo interfacce; il wiring avviene nello strato più esterno.

Integrazione con Riverpod e BLoC

Clean Architecture non prescrive un particolare state manager. Puoi usare Riverpod definendo provider che dipendono dai Use Cases; o BLoC con Cubit che riceve Use Cases nel costruttore. La Presentation Layer resta separata: i widget leggono lo stato da Bloc/Riverpod, che a loro volta chiamano Use Cases. Il flusso è: UI → Bloc/Provider → Use Case → Repository (interface) → Repository Impl → Data Source.

Quando usare la Clean Architecture

  • App complesse con molte feature, team multipli, previsione di crescita.
  • Logica di business non banale che deve essere testata in isolamento.
  • Piattaforme multiple (mobile + web + backend) che condividono la stessa logica.
  • Frequenti cambi di backend (API, database, cache) senza riscrivere l'app.

Quando evitarla (o semplificarla)

Per app piccole, proof-of-concept o progetti senza previsione di scala, la Clean Architecture completa può essere overkill. Troppi layer e file per poche schermate creano complessità inutile. In questi casi è più pragmatico:

  • Organizzare per cartelle base (screens, models, services/widgets).
  • Usare BLoC o Riverpod con repository semplificati, senza necessariamente un layer Domain dedicato.
  • Introduire Use Cases e separazione rigida solo quando il progetto cresce e la manutenibilità diventa un problema.

Conclusione

La Clean Architecture in Flutter offre un modello solido per app scalabili e manutenibili: Domain puro, Data che implementa le interfacce, Presentation che usa Use Cases. La chiave è la Dependency Rule e l'uso coerente di interfacce e dependency injection.

Non è obbligatoria per ogni progetto: per app piccole può essere eccessiva. L'importante è applicare i principi in modo proporzionato — separazione delle responsabilità, testabilità, indipendenza dai dettagli — e adattarli al contesto. Come ricorda la documentazione Flutter: "Regardless of how you answer these questions, the principles in this guide will help you write scalable Flutter apps."

Sulla gestione dello stato, confronta Riverpod e BLoC. Per il rilascio in produzione, vedi ambienti, flavor e rilasci in Flutter.

Fabrizio Billeci
Fabrizio Billeci
Sviluppatore app Flutter e full-stack · Catania

Torna al blog

Articoli correlati

Hai un progetto in mente?

Raccontami obiettivi e tempi: ti rispondo con una proposta concreta, una roadmap e una stima economica.

Parliamo del tuo progetto