Dio: cos'è e caratteristiche del client HTTP per Flutter

Cos'è Dio?

Dio è una potente libreria client HTTP per il linguaggio Dart, più ampiamente utilizzata nelle applicazioni Flutter. Dio fornisce un'API ricca con supporto per intercettori, configurazione globale, trasformatori, FormData, caricamento di file e gestione flessibile dei timeout, rendendolo la scelta principale per le comunicazioni di rete nella comunità Flutter.

La libreria è stata creata da Wenda Wang nel 2018 come alternativa all'HttpClient integrato di dart:io, che mancava di molte funzionalità moderne: configurazione unificata per tutte le richieste, intercettori e serializzazione automatica. Entro il 2025, Dio ha superato in popolarità il pacchetto http del team Dart, occupando il primo posto tra i client HTTP nell'ecosistema Flutter secondo pub.dev.

Dio supporta tre adattatori: DartNativeAdapter (predefinito su Android, iOS, Desktop), BrowserAdapter (sul Web) e IOAdapter. L'adattatore viene selezionato automaticamente in base alla piattaforma. Dio fornisce anche un'interfaccia unificata per tutte le piattaforme Flutter — Android, iOS, Web, macOS, Windows e Linux.

Come funziona Dio

L'architettura di Dio è costruita su una catena di gestori. Ogni richiesta passa attraverso una sequenza di intercettori che possono modificare la richiesta (InterceptorsWrapper.onRequest), la risposta (onResponse) o gestire un errore (onError). Dopo gli intercettori, la richiesta va ai trasformatori (Transformer), che trasformano i dati prima dell'invio.

Un'istanza di Dio viene configurata tramite un oggetto BaseOptions contenente l'URL di base, le intestazioni predefinite, i timeout, il tipo di risposta (JSON, stream, plain), i parametri di query e il formato dei dati. Queste impostazioni si applicano a tutte le richieste ma possono essere sovrascritte in una richiesta specifica. BaseOptions fornisce un unico punto di configurazione per l'intera applicazione, semplificando le modifiche agli endpoint o l'aggiunta di intestazioni globali.

Ogni richiesta in Dio restituisce Response<T>, dove T è il tipo di dati dopo l'elaborazione dei trasformatori. Per impostazione predefinita, Dio converte automaticamente le risposte JSON in Map<String, dynamic>. Per risposte tipizzate, Dio viene utilizzato insieme a pacchetti di serializzazione: json_serializable, freezed o built_value. Response contiene data, headers, statusCode, requestOptions e dati aggiuntivi.

Configurazione globale di Dio

La configurazione di base viene creata tramite Dio(BaseOptions). È possibile impostare un baseUrl per tutte le richieste, connectTimeout e receiveTimeout, intestazioni content-type e accept, nonché queryParameters. Tutti questi parametri si applicano a ogni richiesta, eliminando la duplicazione del codice e centralizzando la gestione delle impostazioni di rete.

Dio supporta due modalità di serializzazione: JSON per impostazione predefinita (responseType: ResponseType.json) e streaming (ResponseType.stream). In modalità stream, Response.data restituisce un ResponseBody che può essere letto a pezzi. Questo è conveniente per file di grandi dimensioni dove il caricamento completo in memoria non è desiderabile. La modalità plain restituisce una stringa grezza senza analisi JSON automatica.

Intercettori di Dio

Gli intercettori sono il meccanismo chiave di Dio per intercettare e modificare richieste, risposte ed errori. Sostituiscono completamente l'Interceptor di OkHttp e i plugin di Ktor, ma con un'API specifica di Dart e supporto asincrono tramite Future. Gli intercettori possono essere aggiunti sia nella configurazione globale di Dio che per richieste individuali.

LogInterceptor

Il LogInterceptor integrato registra ogni richiesta: metodo, URL, intestazioni, corpo e tempo di esecuzione. Ha due modalità: compatta (una riga per richiesta) e completa (informazioni complete con corpo). LogInterceptor è particolarmente utile durante lo sviluppo, ma si consiglia di disabilitarlo nelle build di rilascio tramite import condizionali o un flag globale.

Gli intercettori personalizzati vengono creati tramite la classe InterceptorsWrapper. È possibile sovrascrivere uno, due o tutti e tre i metodi (onRequest, onResponse, onError). Dio esegue gli intercettori rigorosamente nell'ordine in cui vengono aggiunti alla lista degli intercettori. Se un intercettore non chiama handler.next(), la catena viene interrotta e la risposta o l'errore non raggiunge l'applicazione.

Per l'autenticazione in Dio, si usa un intercettore che aggiunge un token Bearer all'intestazione Authorization. Se il server restituisce 401, l'intercettore in onError tenta di rinnovare il token tramite una richiesta di refresh e ripete la richiesta originale con il nuovo token. Questo modello è chiamato token refresh interceptor ed è implementato tramite DioException verificando response?.statusCode == 401.

Dio fornisce supporto integrato per la logica di ripetizione tramite il pacchetto dio_smart_retry o un RetryInterceptor personalizzato. La ripetizione è importante per le applicazioni mobili: quando la connessione viene persa per 2-3 secondi, Dio lancia una DioException con tipo connectionTimeout o connectionError. RetryInterceptor cattura questa eccezione e ripete la richiesta fino a 3 volte con backoff esponenziale (1s, 2s, 4s), migliorando l'affidabilità dell'applicazione in condizioni di rete instabili.

Esempi di codice Dio in Dart

Vediamo una richiesta GET di base con Dio. Viene creata un'istanza con BaseOptions, impostando l'URL di base e i timeout. La richiesta viene eseguita tramite il metodo get(), che restituisce una Response con dati in formato Map.

final dio = Dio(BaseOptions(
    baseUrl: 'https://api.github.com',
    connectTimeout: Duration(seconds: 15),
    receiveTimeout: Duration(seconds: 15),
    headers: {
        'Accept': 'application/vnd.github.v3+json',
    },
))

final response = await dio.get('/users/octocat')
print(response.data['accesso'])

Per una richiesta POST con corpo JSON, viene passato un oggetto Map o un DTO personalizzato. Dio serializza automaticamente Map in JSON tramite jsonEncode. Per DTO tipizzati, si utilizzano l'opzione queryParameters, il campo data o un Transformer personalizzato.

final data = {
    'name': 'my-project',
    'description': 'Created via Dio',
    'private': false,
}

final response = await dio.post(
    '/user/repos',
    data: data,
    options: Options(
        contentType: ContentType.json.value,
    ),
)

print(response.data['ID'])

Aggiunta di un intercettore di autorizzazione

Un intercettore personalizzato aggiunge un token Bearer a ogni richiesta. Il metodo onRequest si attiva prima dell'invio, modificando le intestazioni. Su una risposta 401, l'intercettore può rinnovare il token e ripetere la richiesta tramite il metodo dio.fetch(requestOptions).

class AuthInterceptor extends InterceptorsWrapper {
    final String token

    AuthInterceptor(this.token)

    @override
    void onRequest(
        RequestOptions options,
        RequestInterceptorHandler handler,
    ) {
        options.headers['Authorization'] = 'Bearer $token'
        handler.next(options)
    }
}

dio.interceptors.add(AuthInterceptor('ghp_abc123'))

Caricamento e download di file con Dio

Dio semplifica il caricamento di file tramite FormData. Per inviare un file, viene creato un MultipartFile da File, Bytes o AssetBundle. FormData imposta automaticamente l'intestazione multipart/form-data con il confine e la codifica corretti. Dio supporta il progresso di caricamento tramite onSendProgress.

Per il download di file, viene utilizzato il metodo download(), che salva il flusso di dati direttamente in un file. Dio supporta la ripresa di download interrotti tramite l'intestazione Range, particolarmente utile per file di grandi dimensioni. Il progresso del download viene tracciato tramite onReceiveProgress, consentendo di visualizzare una barra di avanzamento nell'interfaccia utente.

final formData = FormData.fromMap({
    'file': await MultipartFile.fromFile(
        '/path/to/photo.jpg',
        filename: 'photo.jpg',
    ),
    'description': 'Profile photo',
})

await dio.post(
    '/upload',
    data: formData,
    onSendProgress: (sent, total) {
        final progress = sent / total * 100
        print('Upload: $progress%')
    },
)

// Download file
await dio.download(
    'https://example.com/file.zip',
    '/storage/emulated/0/Download/file.zip',
    onReceiveProgress: (received, total) {
        print('Download: ${received / total * 100}%')
    },
)

Errori comuni nell'uso di Dio

La gestione errata degli errori è il problema più comune. Dio lancia una DioException (precedentemente DioError) per qualsiasi problema: indisponibilità di rete, timeout, errori HTTP 4xx/5xx. Molti sviluppatori catturano solo l'Exception generica, perdendo informazioni sul tipo di errore e la possibilità di gestirlo specificamente. Utilizzare DioException.type per determinare la causa del fallimento.

Ignorare CancelToken porta a perdite di richieste. Se un utente lascia una schermata mentre una richiesta è ancora in esecuzione, Dio spreca risorse e potrebbe tentare di aggiornare uno State distrutto. Creare sempre un CancelToken per ogni richiesta e annullarlo in dispose(). CancelToken genera una DioException con tipo cancel, che deve essere gestita correttamente.

Mancanza di logica di ripetizione per guasti temporanei. Su dispositivi mobili, la rete è spesso brevemente non disponibile. Implementare un intercettore con ripetizione automatica della richiesta in caso di timeout o risposta 503/502. Utilizzare RetryInterceptor dal pacchetto dio_smart_retry o scrivere un intercettore personalizzato con backoff esponenziale tra i tentativi.