Dio: Was es ist und Funktionen des HTTP-Clients für Flutter

Was ist Dio?

Dio ist eine leistungsstarke HTTP-Client-Bibliothek für die Sprache Dart, die am häufigsten in Flutter-Anwendungen verwendet wird. Dio bietet eine umfangreiche API mit Unterstützung für Interceptors, globale Konfiguration, Transformatoren, FormData, Datei-Uploads und flexibles Timeout-Management, was es zur ersten Wahl für Netzwerkkommunikation in der Flutter-Community macht.

Die Bibliothek wurde 2018 von Wenda Wang als Alternative zum integrierten dart:io HttpClient entwickelt, dem viele moderne Funktionen fehlten: einheitliche Konfiguration für alle Anfragen, Interceptors und automatische Serialisierung. Bis 2025 übertraf Dio das http-Paket des Dart-Teams an Beliebtheit und belegte laut pub.dev den ersten Platz unter den HTTP-Clients im Flutter-Ökosystem.

Dio unterstützt drei Adapter: DartNativeAdapter (Standard auf Android, iOS, Desktop), BrowserAdapter (im Web) und IOAdapter. Der Adapter wird automatisch je nach Plattform ausgewählt. Dio bietet außerdem eine einheitliche Schnittstelle für alle Flutter-Plattformen — Android, iOS, Web, macOS, Windows und Linux.

Wie Dio funktioniert

Dios Architektur basiert auf einer Handler-Kette. Jede Anfrage durchläuft eine Sequenz von Interceptors, die die Anfrage (InterceptorsWrapper.onRequest), die Antwort (onResponse) modifizieren oder einen Fehler (onError) behandeln können. Nach den Interceptors gelangt die Anfrage zu den Transformatoren (Transformer), die die Daten vor dem Senden umwandeln.

Eine Dio-Instanz wird über ein BaseOptions-Objekt konfiguriert, das die Basis-URL, Standard-Header, Timeouts, Antworttyp (JSON, Stream, Plain), Abfrageparameter und Datenformat enthält. Diese Einstellungen gelten für alle Anfragen, können aber in einer bestimmten Anfrage überschrieben werden. BaseOptions bietet einen einzigen Konfigurationspunkt für die gesamte Anwendung, was Endpunktänderungen oder das Hinzufügen globaler Header vereinfacht.

Jede Dio-Anfrage gibt Response<T> zurück, wobei T der Datentyp nach der Transformer-Verarbeitung ist. Standardmäßig konvertiert Dio JSON-Antworten automatisch in Map<String, dynamic>. Für typisierte Antworten wird Dio zusammen mit Serialisierungspaketen verwendet: json_serializable, freezed oder built_value. Die Response enthält data, headers, statusCode, requestOptions und Zusatzdaten.

Globale Dio-Konfiguration

Die Basiskonfiguration wird über Dio(BaseOptions) erstellt. Sie können eine baseUrl für alle Anfragen, connectTimeout und receiveTimeout, content-type- und accept-Header sowie queryParameters festlegen. Alle diese Parameter gelten für jede Anfrage, beseitigen Code-Duplikation und zentralisieren die Netzwerkeinstellungsverwaltung.

Dio unterstützt zwei Serialisierungsmodi: standardmäßig JSON (responseType: ResponseType.json) und Streaming (ResponseType.stream). Im Stream-Modus gibt Response.data einen ResponseBody zurück, der in Teilen gelesen werden kann. Dies ist praktisch für große Nutzlastdateien, bei denen das vollständige Laden in den Speicher unerwünscht ist. Der Plain-Modus gibt einen Rohstring ohne automatische JSON-Analyse zurück.

Dio-Interceptors

Interceptors sind Dios Schlüsselmechanismus zum Abfangen und Modifizieren von Anfragen, Antworten und Fehlern. Sie ersetzen vollständig OkHttps Interceptor und Ktors Plugins, jedoch mit einer Dart-spezifischen API und asynchroner Unterstützung über Future. Interceptors können sowohl in der globalen Dio-Konfiguration als auch für einzelne Anfragen hinzugefügt werden.

LogInterceptor

Der integrierte LogInterceptor protokolliert jede Anfrage: Methode, URL, Header, Body und Ausführungszeit. Er hat zwei Modi: kompakt (eine Zeile pro Anfrage) und vollständig (vollständige Informationen mit Body). LogInterceptor ist besonders während der Entwicklung nützlich, aber es wird empfohlen, ihn in Release-Builds über bedingte Imports oder ein globales Flag zu deaktivieren.

Benutzerdefinierte Interceptors werden über die Klasse InterceptorsWrapper erstellt. Sie können eine, zwei oder alle drei Methoden (onRequest, onResponse, onError) überschreiben. Dio führt die Interceptors streng in der Reihenfolge ihrer Hinzufügung zur Interceptors-Liste aus. Wenn ein Interceptor handler.next() nicht aufruft, wird die Kette unterbrochen und die Antwort oder der Fehler erreicht die Anwendung nicht.

Für die Authentifizierung in Dio wird ein Interceptor verwendet, der ein Bearer-Token zum Authorization-Header hinzufügt. Wenn der Server 401 zurückgibt, versucht der Interceptor in onError, das Token über eine Aktualisierungsanfrage zu erneuern und wiederholt die ursprüngliche Anfrage mit dem neuen Token. Dieses Muster wird als Token-Refresh-Interceptor bezeichnet und über DioException durch Prüfung von response?.statusCode == 401 implementiert.

Dio bietet integrierte Unterstützung für Wiederholungslogik über das Paket dio_smart_retry oder einen benutzerdefinierten RetryInterceptor. Wiederholungen sind für mobile Anwendungen wichtig: Wenn die Verbindung für 2-3 Sekunden verloren geht, löst Dio eine DioException vom Typ connectionTimeout oder connectionError aus. RetryInterceptor fängt diese Ausnahme ab und wiederholt die Anfrage bis zu 3 Mal mit exponentiellem Backoff (1s, 2s, 4s), was die Zuverlässigkeit der Anwendung bei instabilen Netzwerkbedingungen verbessert.

Dio-Codebeispiele in Dart

Betrachten wir eine grundlegende GET-Anfrage mit Dio. Eine Instanz wird mit BaseOptions erstellt, wobei die Basis-URL und Timeouts festgelegt werden. Die Anfrage wird über die Methode get() ausgeführt und gibt eine Response mit Daten im Map-Format zurück.

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['Anmelden'])

Für eine POST-Anfrage mit JSON-Body wird ein Map-Objekt oder ein benutzerdefiniertes DTO übergeben. Dio serialisiert das Map automatisch über jsonEncode in JSON. Für typisierte DTOs werden die Option queryParameters, das data-Feld oder ein benutzerdefinierter Transformer verwendet.

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'])

Hinzufügen eines Autorisierungs-Interceptors

Ein benutzerdefinierter Interceptor fügt jeder Anfrage ein Bearer-Token hinzu. Die Methode onRequest wird vor dem Senden ausgelöst und modifiziert die Header. Bei einer 401-Antwort kann der Interceptor das Token aktualisieren und die Anfrage über die Methode dio.fetch(requestOptions) wiederholen.

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'))

Datei-Upload und -Download mit Dio

Dio vereinfacht Datei-Uploads über FormData. Zum Senden einer Datei wird ein MultipartFile aus File, Bytes oder AssetBundle erstellt. FormData setzt automatisch den multipart/form-data-Header mit der richtigen Grenze und Kodierung. Dio unterstützt Upload-Fortschritt über onSendProgress.

Für Datei-Downloads wird die Methode download() verwendet, die den Datenstrom direkt in eine Datei speichert. Dio unterstützt die Wiederaufnahme unterbrochener Downloads über den Range-Header, was besonders bei großen Dateien nützlich ist. Der Download-Fortschritt wird über onReceiveProgress verfolgt, sodass ein Fortschrittsbalken in der Benutzeroberfläche angezeigt werden kann.

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%')
    },
)

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

Häufige Fehler bei der Arbeit mit Dio

Falsche Fehlerbehandlung ist das häufigste Problem. Dio löst bei Problemen eine DioException (früher DioError) aus: Netzwerkunavailableität, Timeout, HTTP-Fehler 4xx/5xx. Viele Entwickler fangen nur die generische Exception und verlieren Informationen über den Fehlertyp und die Möglichkeit, ihn spezifisch zu behandeln. Verwenden Sie DioException.type, um die Fehlerursache zu bestimmen.

Ignorieren von CancelToken führt zu Anfragelecks. Wenn ein Benutzer einen Bildschirm verlässt, während eine Anfrage noch läuft, verschwendet Dio Ressourcen und könnte versuchen, einen zerstörten State zu aktualisieren. Erstellen Sie immer einen CancelToken für jede Anfrage und brechen Sie ihn in dispose() ab. CancelToken erzeugt eine DioException vom Typ cancel, die ordnungsgemäß behandelt werden muss.

Fehlende Wiederholungslogik für temporäre Ausfälle. Auf mobilen Geräten ist das Netzwerk oft kurzzeitig nicht verfügbar. Implementieren Sie einen Interceptor mit automatischer Anfragewiederholung bei Timeout oder 503/502-Antwort. Verwenden Sie RetryInterceptor aus dem Paket dio_smart_retry oder schreiben Sie einen benutzerdefinierten Interceptor mit exponentiellem Backoff zwischen den Versuchen.