Dio: wat is het, kenmerken van de HTTP-client voor Flutter

Wat is Dio?

Dio — is een krachtige HTTP-clientbibliotheek voor de taal Dart, het meest gebruikt in Flutter-applicaties. Dio biedt een rijke API met ondersteuning voor interceptors, globale configuratie, transformatoren, FormData, bestandsuploads en flexibel beheer van time-outs, wat het de belangrijkste keuze maakt voor netwerkcommunicatie in de Flutter-gemeenschap.

De bibliotheek is in 2018 gemaakt door Wenda Wang als alternatief voor de ingebouwde dart:io HttpClient, die veel moderne mogelijkheden miste: uniforme configuratie voor alle verzoeken, interceptors en automatische serialisatie. Tegen 2025 heeft Dio het http-pakket van het Dart-team in populariteit overtroffen en de eerste plaats ingenomen onder HTTP-cliënten in het Flutter-ecosysteem volgens pub.dev-gegevens.

Dio ondersteunt drie adapters: DartNativeAdapter (standaard op Android, iOS, Desktop), BrowserAdapter (op Web) en IOAdapter. De adapter wordt automatisch geselecteerd op basis van het platform. Dio biedt ook een uniforme interface voor alle Flutter-platforms — Android, iOS, Web, macOS, Windows en Linux.

Hoe werkt Dio

Dio-architectuur is gebouwd op een handlerketen (handler chain). Elk verzoek doorloopt een reeks interceptors die het verzoek (InterceptorsWrapper.onRequest), het antwoord (onResponse) kunnen wijzigen of de fout (onError) kunnen afhandelen. Na de interceptors komt het verzoek bij de transformatoren (Transformer) die de gegevens transformeren vóór verzending.

Een Dio-instantie wordt geconfigureerd via een BaseOptions-object met de basis-URL, standaardheaders, time-outs, antwoordtype (JSON, stream, plain), queryparameters en gegevensformaat. Deze instellingen worden toegepast op alle verzoeken, maar kunnen in een specifiek verzoek worden overschreven. BaseOptions biedt een uniform configuratiepunt voor de hele applicatie, wat het wijzigen van een API-endpoint of het toevoegen van globale headers vereenvoudigt.

Elk verzoek in Dio retourneert Response<T>, waarbij T — het gegevenstype is na verwerking door de transformatoren. Standaard converteert Dio automatisch het JSON-antwoord naar Map<String, dynamic>. Voor getypeerde antwoorden wordt Dio samen met serialisatiepakketten gebruikt: json_serializable, freezed of built_value. Response bevat data, headers, statusCode, requestOptions en extra gegevens.

Globale configuratie van Dio

Basisconfiguratie wordt gemaakt via Dio(BaseOptions). U kunt baseUrl voor alle verzoeken instellen, connectTimeout en receiveTimeout, content-type en accept-headers, evenals queryParameters. Al deze parameters worden op elk verzoek toegepast, waardoor code-duplicatie wordt geëlimineerd en het beheer van netwerkinstellingen wordt gecentraliseerd.

Dio ondersteunt twee serialisatiemodi: standaard JSON (responseType: ResponseType.json) en streaming (ResponseType.stream). In de streamingmodus retourneert Response.data een ResponseBody dat in delen kan worden gelezen. Dit is handig voor grote payload-bestanden wanneer het volledig laden in het geheugen niet gewenst is. De plain-modus retourneert een ruwe tekenreeks zonder automatische JSON-parsing.

Dio-interceptors

Interceptors — het belangrijkste mechanisme van Dio voor het onderscheppen en wijzigen van verzoeken, antwoorden en fouten. Ze vervangen volledig Interceptor uit OkHttp en plug-ins uit Ktor, maar met Dart-specifieke API en ondersteuning voor asynchroniteit via Future. Interceptors kunnen zowel in de globale configuratie van Dio als voor afzonderlijke verzoeken worden toegevoegd.

LogInterceptor

De ingebouwde LogInterceptor logt elk verzoek: methode, URL, headers, body en uitvoeringstijd. Het heeft twee modi: compact (één regel per verzoek) en full (volledige informatie met body). LogInterceptor is vooral handig tijdens de ontwikkeling, maar het wordt aanbevolen om het uit te schakelen in release-builds via een conditionele import of een globale vlag.

Aangepaste interceptors worden gemaakt via de klasse InterceptorsWrapper. U kunt één, twee of alle drie methoden (onRequest, onResponse, onError) overschrijven. Dio voert interceptors strikt uit in de volgorde waarin ze aan de interceptors-lijst zijn toegevoegd. Als een interceptor handler.next() niet aanroept, wordt de keten onderbroken en bereiken het antwoord/de fout de applicatie niet.

Voor authenticatie in Dio wordt een interceptor gebruikt die een Bearer-token toevoegt aan de Authorization-header. Als de server 401 retourneert, probeert de interceptor in onError het token te vernieuwen via een refresh-verzoek en herhaalt het originele verzoek met het nieuwe token. Dit patroon wordt token refresh interceptor genoemd en wordt geïmplementeerd via DioException met controle op response?.statusCode == 401.

Dio biedt ingebouwde ondersteuning voor pogingslogica via het pakket dio_smart_retry of een aangepaste RetryInterceptor. Opnieuw proberen is belangrijk voor mobiele applicaties: bij verbindingsverlies gedurende 2–3 seconden gooit Dio een DioException met het type connectionTimeout of connectionError. RetryInterceptor vangt deze uitzondering op en herhaalt het verzoek tot 3 keer met exponentiële vertraging (1s, 2s, 4s), wat de betrouwbaarheid van de applicatie verhoogt in omstandigheden met onstabiel netwerk.

Dio-codevoorbeelden in Dart

Laten we een basis-GET-verzoek via Dio bekijken. Er wordt een instantie gemaakt met BaseOptions, de basis-URL en time-outs worden ingesteld. Het verzoek wordt uitgevoerd via de methode get(), die Response retourneert met gegevens in Map-formaat.

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

Voor een POST-verzoek met JSON-body wordt een Map-object of aangepaste DTO doorgegeven. Dio serialiseert automatisch Map naar JSON via jsonEncode. Voor getypeerde DTO wordt de optie queryParameters, het data-veld of een aangepaste Transformer gebruikt.

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

Autorisatie-interceptor toevoegen

Een aangepaste interceptor voegt een Bearer-token toe aan elk verzoek. De methode onRequest werkt vóór verzending en wijzigt de headers. Bij een 401-antwoord kan de interceptor het token vernieuwen en het verzoek herhalen via de methode 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'))

Bestanden uploaden en downloaden via Dio

Dio vereenvoudigt het uploaden van bestanden via FormData. Om een bestand te verzenden wordt een MultipartFile gemaakt van File, Bytes of AssetBundle. FormData stelt automatisch de multipart/form-data-header in met de juiste grens en codering. Dio ondersteunt uploadvoortgang via onSendProgress.

Voor het downloaden van bestanden wordt de methode download() gebruikt, die de gegevensstroom rechtstreeks naar een bestand opslaat. Dio ondersteunt hervatten (resume) van onderbroken downloads via de Range-header, wat vooral handig is voor grote bestanden. Downloadvoortgang wordt gevolgd via onReceiveProgress, waardoor een voortgangsbalk in de UI kan worden weergegeven.

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('Uploaden: $progress%')
    },
)

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

Veelgemaakte fouten bij het werken met Dio

Onjuiste foutafhandeling — het meest voorkomende probleem. Dio gooit DioException (voorheen DioError) bij problemen: geen netwerk, time-out, HTTP-fouten 4xx/5xx. Veel ontwikkelaars vangen alleen de generieke Exception, waardoor informatie over het fouttype en de mogelijkheid tot aangepaste afhandeling verloren gaat. Gebruik DioException.type om de oorzaak van de fout te bepalen.

Negeren van CancelToken leidt tot lekkage van verzoeken. Als de gebruiker het scherm verlaat terwijl het verzoek nog wordt uitgevoerd, verbruikt Dio bronnen en kan het proberen een vernietigde State bij te werken. Maak altijd een CancelToken voor elk verzoek en annuleer het in dispose(). CancelToken genereert DioException met het type cancel, dat correct moet worden afgehandeld.

Ontbreken van pogingslogica voor tijdelijke fouten. Op mobiele apparaten is het netwerk vaak tijdelijk niet beschikbaar. Implementeer een interceptor met automatische herhaling van het verzoek bij time-out of antwoord 503/502. Gebruik RetryInterceptor uit het pakket dio_smart_retry of schrijf een aangepaste interceptor met exponentiële vertraging tussen pogingen.