“Clean Architecture” è un paradigma di progettazione software che Robert C. Martin propose sul suo blog “Uncle Bob” e che ad oggi rimane uno dei riferimenti principali del software design orientato agli oggetti.
Questo approccio cerca di promuovere una metodologia di sviluppo del codice scalabile, facile da mantenere e che abbia dipendenze ridotte al minimo. L’idea di fondo consiste nell’organizzare la codebase in strati applicativi distinti, ognuno con responsabilità e dipendenze ben definite.
Possiamo quindi pensare a questo approccio come una serie di buone pratiche che un programmatore dovrebbe seguire al fine di applicare i cosiddetti principi SOLID, un acronimo ben conosciuto nel mondo dell’ingegneria del software. Non è un caso infatti che mettere in pratica il paradigma clean significhi implementare principi come Single Responsability, Dependency Inversion e Separation of concerns.
Nel mondo dello sviluppo mobile, creare applicazioni scalabili e facili da mantenere è uno degli obiettivi primari dei team mobile in Neosperience: la scelta di adottare un framework UI come Flutter per lo sviluppo di applicazioni cross-platform va proprio in questa direzione.
Ecco perché quando un progetto mobile aumenta di complessità e potrebbe diventare complicato da gestire, la necessità di avere un’architettura strutturata diventa fondamentale per ottenere benefici nel lungo periodo in termini di delivery verso il cliente finale e allo stesso tempo efficacia nella manutenzione del progetto.
In questo articolo vedremo come possiamo applicare il paradigma clean nell’ambito dello sviluppo di un’applicazione Flutter e come l’applicazione dei suoi principi determinano la struttura del progetto e il processo di sviluppo della codebase.
Prendendo spunto da un progetto Flutter realizzato per un nostro cliente e attraverso l’analisi dei vari strati applicativi, vedremo come questo paradigma ci ha aiutato a raggiungere con successo obiettivi in termini di manutenzione, testing e flessibilità.
Con il paradigma clean dobbiamo strutturare i componenti applicativi in moduli per i quali possiamo definire uno scopo ben preciso. L’idea principale che ci sta dietro è separare l’applicazione in tre strati principali distinti: data, domain e presentation.
Per definire questi tre strati concettuali nell’ambito del nostro progetto mobile abbiamo deciso di utilizzare il pattern MVVM (Model-View-ViewModel), uno dei design pattern più indicati per lo sviluppo software che prevede la presenza di una user interface (UI).
Spesso questo tipo di pattern prevede di creare un meccanismo di binding dei dati, per cui i cambiamenti sulla UI automaticamente aggiornano i dati sottostanti e viceversa. Dal momento che Flutter nativamente non vincola lo sviluppatore sull’adozione MVVM, abbiamo implementato questo pattern strutturando il codice applicativo in modo appropriato.
Il model rappresenta essenzialmente la business logic e i dati. Esso è responsabile della gestione dei dati e garantisce una consistenza applicativa. Generalmente è indipendente dall’interfaccia utente ed è riutilizzabile per differenti strati presentation.
In Flutter questo strato è costituito essenzialmente da classi e oggetti Dart che mantengono lo stato dell’applicazione e non interagisce direttamente con la UI.
class JCashStore {
String id;
String name;
String storeNumber;
JCashStore({
required this.id,
required this.name,
required this.storeNumber,
});
}
Lo strato View si occupa di presentare i dati all’utente e intercettarne le sue interazioni. Questo strato deve essere tenuto il più leggero e agnostico possibile e il suo compito principale deve essere quello di visualizzare le informazioni.
È in questo strato che spesso si implementa il meccanismo del data-binding osservando i cambiamenti di stato del ViewModel e aggiornando la UI di conseguenza.
In Flutter lo strato View è implementato dai cosiddetti widgets, componenti responsabili di renderizzare elementi della UI e catturare le interazioni utente. E’ possibile quindi assemblare e organizzare una serie di widget per rappresentare uno screen completo della nostra UI.
class JCashStoreInfoButton extends StatelessWidget {
final JCashStoreViewModel cashStore;
JCashStoreInfoButton({required this.cashStore});
@override
Widget build(BuildContext context) {
return ElevatedButton(
title: Text(cashStore.name),
subtitle: Text(‘#: ${cashStore.storeNumber}’),
onPressed: () => viewModel.InfoTap(). //capture user interaction
);
}
}
Il ViewModel è lo strato responsabile di intermediare tra la View e il Model. Esso contiene logiche su come le informazioni devono essere presentate, trasforma opportunamente i dati del Model e fornisce una serie di ‘comandi’ ai quali lo strato View può agganciarsi (binding) per interagire con i dati presentati.
Come dicevamo in precedenza Flutter non fornisce un oggetto ViewModel predefinito. Per questo motivo possiamo creare una nostra implementazione o affidarci a framework e librerie esterne come Provider, BloC, Riverpod. Nel nostro caso abbiamo scelto il framework BloC, come vedremo più avanti.
A questo punto possiamo mappare i tre strati clean nei nostri strati applicativi secondo il pattern MVVM:.
Organizzazione delle singole features
Da notare che la scelta di come suddividere e organizzare i file del progetto non è necessariamente vincolata ad un mapping puntuale dei tre strati clean: trattandosi di un insieme di principi da seguire è possibile rappresentarli generando la propria struttura di cartelle e file a seconda delle proprie esigenze. L’ importante è che la struttura risultante del progetto sia conosciuta e condivisa per l’intero team di sviluppo.
Mapping degli strati Clean sul pattern MVVM
Lo strato di Presentation è rappresentato dalla cartella UI della singola feature, in cui sono inclusi tutti i componenti visuali: screens e singoli elementi di UI custom.
Inoltre condivide la cartella blocs con il Domain layer per la parte di gestione dello stato e esposizione del set di API di interazione con l’interfaccia utente.
Presenta le informazioni e cattura le interazioni utente. Include tutti i componenti relativi all’interfaccia utente (screens, widgets) collegati ad un determinato stato applicativo e ne controlla il loro stato.
Struttura del Presentation Layer per singola funzionalità
Lo strato Domain è anche sinonimo di Business Logic Layer o Use Case Layer. Esso include tutte le logiche e le regole business dell’applicazione. Astrae e incapsula le funzionalità essenziali che sono indipendenti da un particolare framework. Nel nostro caso esso è rappresentato dalle cartelle bloc (in condivisione con Presentation), models e repository (in condivisione con lo strato Data)
Struttura del Domain Layer per singola funzionalità
Lo strato Data si occupa di comunicare con le sorgenti dati ‘esterne’ come servizi di rete, database. Gestisce inoltre le operazioni sullo storage applicativo e il recupero dei dati. Nel nostro caso esso è rappresentato dalle cartelle data, models/api (in cui risiedono i modelli delle entità esterne all’applicazione) e repository (in cui vi è l’implementazione concreta delle regole di business definite dal domain layer)
Struttura del Data Layer per singola funzionalità
In una architettura Clean generalmente il flusso delle dipendenze va dall’esterno verso l’interno: questo significa che gli strati applicativi più interni (es. Domain) sono indipendenti da quelli più esterni. Gli strati più interni infatti definiscono le regole applicative in modo astratto mentre gli strati più esterni ne contengono i dettagli implementativi.
Questo modo di organizzare la codebase comporta benefici in termini di separazione dei compiti, modularità e testabilità dei singoli componenti. Se i singoli strati hanno responsabilità distinte allora è possibile sostituire i singoli strati con altri senza produrre effetti collaterali sui quelli restanti e i vantaggi in termini di flessibilità e adattabilità sono concreti.
Prima di passare ad un esempio concreto è bene dedicare qualche riga sul tema della injection dei componenti. Si tratta di avere un meccanismo centralizzato di creazione delle istanze dei vari componenti senza per forza conoscerne i dettagli implementativi.
Questo meccanismo è conosciuto come Dependency Injection ed è molto utile ad esempio quando vogliamo effettuare unit tests su un determinato layer, per cui possiamo fornire un’istanza mocked dei componenti coinvolti nel test.
Nella nostra applicazione Flutter abbiamo quindi implementato un service locator che gestisce in autonomia la creazione delle istanze dei nostri componenti applicativi. La funzione setup() verrà richiamata nella fase di inizializzazione dell’applicazione Flutter all’interno del main(). In questo modo tutte le istanze dei nostri componenti applicativi sono pronte all’occorrenza.
import ‘package:get_it/get_it.dart';
import 'package:juice_shared/shared.dart';
import 'http/http_client.service.dart';
final sl = GetIt.instance;
class Locator {
static JLogger get logger => sl();
static JCustomerApiClient get apiClient => sl();
static JCustomerRepository get customerRepository => sl();
static Future setup() async {
/* Core Services */
sl.registerSingleton(
JLogger(),
);
/* http client service */
sl.registerSingleton(
JCustomerApiClient(Dio(basePath: Constants.apiHost)),
);
/* customer repository */
sl.registerSingleton(
CustomerRepositoryImpl(customerClientApi: Locator.apiClient),
);
.. .. .. .. ..
}
}
Nota: il package get_it ci aiuta ad implementare il service locator sottostante.
Passiamo quindi ad un esempio concreto estratto dal progetto Flutter di un nostro cliente. Nel caso illustrato andremo a recuperare una lista paginata di clienti tramite una API REST esposta dai nostri servizi cloud e dopo aver recuperato i dati, li faremo transitare attraverso i vari strati applicativi che abbiamo definito in precedenza secondo i principi clean.
Nota: Gli snippet di codice che seguiranno sono solo una parte dell’intera codebase, al fine di illustrare le parti salienti che costituiscono l’approccio clean.
Partiamo dallo strato di Domain in cui andiamo a creare:
/* customer_search_response.dart */
part 'customer_search_response.g.dart';
part 'customer_search_response.freezed.dart';
@freezed()
class JCustomerSearchResponse with _$JCustomerSearchResponse {
factory JCustomerSearchResponse({
required List results,
required String? cursor,
}) = _JCustomerSearchResponse;
factory JCustomerSearchResponse.fromJson(Map<string, dynamic=""> json) =>
_$JCustomerSearchResponseFromJson(json);
}
/* customer_list.dart */
part 'customer_list.freezed.dart';
part 'customer_list.g.dart';
@freezed()
class JListCustomer with _$JListCustomer {
factory JListCustomer({
String? id,
String? juiceId,
bool? invoiceEnabled,
bool? individualPerson,
String? name,
String? customerPriceGroup,
String? phone,
String? email,
bool? blocked,
String? blockedReason,
@JsonValue('_score') int? score,
@Default(0) int pendingInvoicesCount,
}) = _JListCustomer;
factory JListCustomer.fromJson(Map<string, dynamic=""> json) =>
_$JListCustomerFromJson(json);
}
Ora sullo strato Data andremo a creare il nostro Data Source, incaricato di consumare l’API.
Dal momento che faremo uso del package retrofit , ci basterà definire un’interfaccia in cui indicare le operazioni dovrà fare e in cui possiamo definire i parametri della richiesta e come deserializzare la risposta. Retrofit dal canto suo penserà a crearne l’implementazione concreta del nostro datasource. Inoltre per implementare il client http sottostante utilizzeremo il package Dio.
/* customer.client.dart */
import 'package:retrofit/retrofit.dart';
import 'package:dio/dio.dart';
part 'customer.client.g.dart';
@RestApi()
abstract class JCustomerApiClient {
factory JCustomerApiClient(Dio dio) = _JCustomerApiClient;
@GET('/customers')
Future getCustomers(
@Query('q') String querySearch,
@Query('size') int size,
@Query('cursor') String? cursor,
);
.. .. ..
}
Ora possiamo tornare sul nostro strato Domain per definire l’operazione di recupero dei clienti attraverso un’interfaccia definita sul repository della funzionalità.
/* customer.repository.dart */
abstract class JCustomerRepository {
Future<either<jcustomersearchresponse, jexception="">> getCustomers(
String querySearch, String? cursor);
...
}Procediamo quindi a scrivere un’implementazione concreta del nostro repository clienti sullo strato Data:
import 'package:dartz/dartz.dart';
import 'package:juice_shared/shared.dart';
import '/core/locator.dart';
import '../models/customer_search_response.dart';
import '../data/customer.client.dart';
class JCustomerRepositoryImpl extends JCustomerRepository {
final CustomerApiClient customerClientApi;
JCustomerRepositoryImpl({
required this.customerClientApi,
});
Future<either<jcustomersearchresponse, jexception="">> getCustomers(
String querySearch, String? cursor) async {
try {
var response =
await customerClientApi.getCustomers(querySearch, 10, cursor);
return Left(response);
} catch (e) {
return Right(JException.fromException(e));
}
}
...
}Nota: si fa uso della libreria dartz che tra le sue funzionalità ci permette di utilizzare il costrutto Either, utile per gestire gli errori che possono emergere dagli strati sottostanti e gestirli in modo differente rispetto ai casi di successo.
A questo punto abbiamo completato la scrittura dello strato Data e Domain per la funzionalità di fetch della lista clienti e possiamo iniziare a definire lo strato Presentation.
Nel nostro caso abbiamo:
/* customer_search_event.dart */
part of 'customer_search_bloc.dart';
@freezed()
class CustomerSearchEvent with _$CustomerSearchEvent {
const factory CustomerSearchEvent.searchCustomers({
String? query,
String? cursor,
@Default(false) bool resetPreviousList,
}) = SearchCustomers;
}
/* customer_search_state.dart*/
part of 'customer_search_bloc.dart';
@freezed()
class CustomerSearchState with _$CustomerSearchState {
const CustomerSearchState._();
const factory CustomerSearchState() = _CustomerSearchState;
factory CustomerSearchState.initial() = CustomerSearchInitial;
factory CustomerSearchState.loading() = CustomerSearchLoading;
const factory CustomerSearchState.loaded({
required List customers,
String? cursor,
String? query,
}) = CustomerSearchLoaded;
const factory CustomerSearchState.failure({
required String message,
List? customers,
String? query,
}) = CustomerSearchFailure;
}
/* customer_search_bloc.dart */
import 'package:flutter_bloc/flutter_bloc.dart';
import '../../data/customer.repository.dart';
part 'customer_search_event.dart';
part 'customer_search_state.dart';
part 'customer_search_bloc.freezed.dart';
class CustomerSearchBloc extends Bloc<customersearchevent, customersearchstate=""> {
final JCustomerRepository customerRepository;
CustomerSearchBloc({
required this.customerRepository,
}) : super(CustomerSearchInitial()) {
on(_onCustomerSearch);
}
Future _onCustomerSearch(
SearchCustomers event,
Emitter emit,
) async {
List customers =
state.mapOrNull(
(value) => [],
loaded: (state) => (state.customers)) ?? [];
if(event.resetPreviousList || customers.isEmpty || event.query != state.query)
{
emit(CustomerSearchLoading());
customers = [];
}
final result = await customerRepository.getCustomers(
event.query ?? '',
event.cursor,
);
result.fold(
(customerList) {
emit(
CustomerSearchLoaded(
customers: customers + customerList.results,
cursor: customerList.cursor,
query: event.query,
)
);
},
(error) =>
emit(CustomerSearchFailure(message: error.getMessage())));
}
}
In questo modo ora abbiamo la possibilità di:
Lo screen incaricato di visualizzare la lista clienti renderizza la UI a partire dallo stato applicativo in cui il viewModel si trova (initial, loading, loaded, failure) e per ognuno degli stati censiti costruisce la UI appropriata, utilizzando i widget messi disposizione da Flutter e i widget custom creati ad hoc.
/* customer_search.sc.dart */
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:juice_ui/ui.dart';
import 'widgets/customer-search.dart';
class JSearchCustomerScreen extends StatefulWidget {
const JSearchCustomerScreen({ super.key });
@override
State createState() => _JSearchCustomerScreenState();
}
class _JSearchCustomerScreenState extends State {
final late CustomerSearchBloc _vm;;
@override
void initState() {
_vm = CustomerSearchBloc(
customerRepository: Locator.customerRepository,
);
_fetchCustomers();
super.initState();
}
void _fetchCustomers({String? query, String? cursor}) {
_bloc.add(
CustomerSearchEvent.searchCustomers(
query: query,
cursor: cursor,
),
);
}
@override
Widget build(BuildContext context) {
return BlocConsumer<customersearchbloc, customersearchstate="">(
listener: (context, state) {
state.whenOrNull(
() => null,
failure: (message, customers, _) {
if (customers != null) {
JToastrService()
.showToast(context, message, JToastStatus.error, true);
}
},
);
},
builder: (context, state) => _buildContent(state),
);
}
Widget _buildContent(CustomerSearchState state) {
/* customer list UI */
return Column(
children: [
Expanded(
child: JCard(
padding: const EdgeInsets.all(0.0),
body: JCustomerSearch(
query: state.query,
onSubmit: (query) =>
_fetchCustomers(query: query, cursor: null),
),
),
),
state.maybeWhen(
() => const SizedBox(
height: 0,
),
loading: () => const Expanded(child: Center(child: JSpinner())),
loaded: (costumers, _, query) {
if (customers.isEmpty) {
return Center(
child: JH4(
'Nessun risultato per $query',
color: JPalette.grey,
));
}
return const SizedBox(height: 0);
},
orElse: () => const SizedBox(height: 0),
),
Expanded(
child: ListView.separated(
separatorBuilder: (context, index) => const SizedBox(height: 10.0),
itemCount:
state.cursor != null ?
state.customers.length + 1 : state.customers.length,
itemBuilder: (context, i) {
if (i == state.customers.length) {
// fetch the next customer page
_fetchCustomers(query: state.query, cursor: state.cursor);
return const Padding(
padding: EdgeInsets.only(top: 10.0, bottom: 10.0),
child: Center(child: JSpinner()),
);
}
/* render a tappable customer card info*/
return JCustomerCard(
customer: state.customers[i],
onTap: () {
/* …Go to customer detail screen …*/
},
);
},
),
),
],
);
}
}Anche in questo caso lo screen crea un'istanza del proprio viewModel utilizzando il service locator e la Dependency Injection per iniettare come dipendenza il repository appropriato. Questo assicura un testing efficiente della singola funzionalità ad esempio iniettando un’istanza
L’architettura Clean nelle applicazioni Flutter può apportare benefici concreti ma dovrebbe essere fatta una valutazione accurata per decidere se adottarla o meno, in quanto questo approccio può influenzare anche di molto le scelte delle modalità di sviluppo dell’applicazione. Ci sono vari fattori da prendere in considerazione, ad esempio la grandezza e la complessità dell’applicazione.
Possiamo in ogni caso fare delle considerazioni generali:
In generale possiamo quindi dire che applicare un approccio Clean alla propria architettura software può essere un’ottima soluzione per la realizzazione di app Flutter, specialmente se ci aspettiamo una crescita dell’applicazione o viene richiesto un alto grado di manutenzione e testabilità.
Come sempre quindi è essenziale un’attenta valutazione per capire come bilanciare i benefici che introdurrebbe questo approccio con i vincoli progettuali.