Dio: vad det är, funktioner hos HTTP-klienten för Flutter

Vad är Dio?

Dio — är ett kraftfullt HTTP-klientbibliotek för språket Dart, mest använt i Flutter-applikationer. Dio erbjuder ett rikt API med stöd för avlyssnare, global konfiguration, transformatorer, FormData, filuppladdning och flexibel hantering av tidsgränser, vilket gör det till det främsta valet för nätverkskommunikation i Flutter-gemenskapen.

Biblioteket skapades av Wenda Wang 2018 som ett alternativ till den inbyggda dart:io HttpClient, som saknade många moderna funktioner: enhetlig konfiguration för alla förfrågningar, avlyssnare och automatisk serialisering. År 2025 hade Dio överträffat http-paketet från Dart-teamet i popularitet och intog första platsen bland HTTP-klienter i Flutter-ekosystemet enligt pub.dev-data.

Dio stöder tre adaptrar: DartNativeAdapter (standard på Android, iOS, Desktop), BrowserAdapter (på webben) och IOAdapter. Adaptern väljs automatiskt beroende på plattform. Dio tillhandahåller också ett enhetligt gränssnitt för alla Flutter-plattformar — Android, iOS, Web, macOS, Windows och Linux.

Hur Dio fungerar

Dios arkitektur är byggd på en hanterarkedja (handler chain). Varje förfrågan går igenom en sekvens av avlyssnare som kan ändra förfrågan (InterceptorsWrapper.onRequest), svaret (onResponse) eller hantera felet (onError). Efter avlyssnarna kommer förfrågan till transformatorerna (Transformer) som omvandlar data före sändning.

En Dio-instans konfigureras via BaseOptions-objektet som innehåller bas-URL, standardrubriker, tidsgränser, svarstyp (JSON, stream, plain), frågeparametrar och dataformat. Dessa inställningar tillämpas på alla förfrågningar men kan åsidosättas i en specifik förfrågan. BaseOptions tillhandahåller en enhetlig konfigurationspunkt för hela applikationen, vilket förenklar byte av API-slutpunkt eller tillägg av globala rubriker.

Varje förfrågan i Dio returnerar Response<T>, där T — är datatypen efter bearbetning av transformatorerna. Som standard konverterar Dio automatiskt JSON-svar till Map<String, dynamic>. För typade svar används Dio tillsammans med serialiseringspaket: json_serializable, freezed eller built_value. Response innehåller data, headers, statusCode, requestOptions och ytterligare data.

Global konfiguration av Dio

Grundkonfiguration skapas via Dio(BaseOptions). Du kan ställa in baseUrl för alla förfrågningar, connectTimeout och receiveTimeout, content-type och accept-rubriker samt queryParameters. Alla dessa parametrar tillämpas på varje förfrågan, vilket eliminerar kodduplicering och centraliserar hanteringen av nätverksinställningar.

Dio stöder två serialiseringslägen: standard JSON (responseType: ResponseType.json) och strömning (ResponseType.stream). I strömningsläge returnerar Response.data en ResponseBody som kan läsas i delar. Detta är praktiskt för stora nyttolastfiler när fullständig inläsning i minnet inte är önskvärd. Plain-läget returnerar en rå sträng utan automatisk JSON-tolkning.

Dios avlyssnare

Avlyssnare — Dios nyckelmekanism för att avlyssna och ändra förfrågningar, svar och fel. De ersätter helt Interceptor från OkHttp och plugin-program från Ktor, men med Dart-specifikt API och stöd för asynkronitet via Future. Avlyssnare kan läggas till både i Dios globala konfiguration och för enskilda förfrågningar.

LogInterceptor

Den inbyggda LogInterceptor loggar varje förfrågan: metod, URL, rubriker, brödtext och exekveringstid. Den har två lägen: compact (en rad per förfrågan) och full (fullständig information med brödtext). LogInterceptor är särskilt användbar under utveckling, men det rekommenderas att inaktivera den i release-byggen via villkorlig import eller en global flagga.

Anpassade avlyssnare skapas via klassen InterceptorsWrapper. Du kan åsidosätta en, två eller alla tre metoder (onRequest, onResponse, onError). Dio utför avlyssnare strikt i den ordning de läggs till i interceptors-listan. Om en avlyssnare inte anropar handler.next(), bryts kedjan och svaret/felet når inte applikationen.

För autentisering i Dio används en avlyssnare som lägger till en Bearer-token i Authorization-rubriken. Om servern returnerar 401 försöker avlyssnaren i onError att uppdatera token via en refresh-förfrågan och upprepar den ursprungliga förfrågan med den nya token. Detta mönster kallas token refresh interceptor och implementeras via DioException med kontroll av response?.statusCode == 401.

Dio tillhandahåller inbyggt stöd för logik för nytt försök via paketet dio_smart_retry eller en anpassad RetryInterceptor. Nytt försök är viktigt för mobilapplikationer: vid förlorad anslutning i 2–3 sekunder kastar Dio DioException med typen connectionTimeout eller connectionError. RetryInterceptor fångar detta undantag och upprepar förfrågan upp till 3 gånger med exponentiell fördröjning (1s, 2s, 4s), vilket ökar applikationens tillförlitlighet under instabila nätverksförhållanden.

Kodexempel för Dio i Dart

Låt oss titta på en grundläggande GET-förfrågan via Dio. En instans skapas med BaseOptions, bas-URL och tidsgränser ställs in. Förfrågan utförs via metoden get(), som returnerar Response med data i Map-format.

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

För en POST-förfrågan med JSON-brödtext skickas ett Map-objekt eller anpassad DTO. Dio serialiserar automatiskt Map till JSON via jsonEncode. För typad DTO används alternativet queryParameters, fältet data eller en anpassad Transformer.

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

Lägga till auktoriseringsavlyssnare

En anpassad avlyssnare lägger till Bearer-token till varje förfrågan. Metoden onRequest aktiveras före sändning och ändrar rubrikerna. Vid 401-svar kan avlyssnaren uppdatera token och upprepa förfrågan via metoden 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'))

Ladda upp och ladda ner filer via Dio

Dio förenklar uppladdning av filer via FormData. För att skicka en fil skapas en MultipartFile från File, Bytes eller AssetBundle. FormData ställer automatiskt in multipart/form-data-rubriken med korrekt gräns och kodning. Dio stöder uppladdningsförlopp via onSendProgress.

För nedladdning av filer används metoden download(), som sparar dataströmmen direkt till en fil. Dio stöder återupptagning (resume) av avbrutna nedladdningar via Range-rubriken, vilket är särskilt användbart för stora filer. Nedladdningsförloppet spåras via onReceiveProgress, vilket gör det möjligt att visa en förloppsindikator i gränssnittet.

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

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

Vanliga misstag vid arbete med Dio

Felaktig felhantering — det vanligaste problemet. Dio kastar DioException (tidigare DioError) vid alla problem: inget nätverk, tidsgräns, HTTP-fel 4xx/5xx. Många utvecklare fångar bara generisk Exception och förlorar information om felttypen och möjligheten till anpassad hantering. Använd DioException.type för att fastställa orsaken till felet.

Ignorering av CancelToken leder till läckage av förfrågningar. Om användaren lämnar skärmen medan förfrågan fortfarande körs, förbrukar Dio resurser och kan försöka uppdatera en förstörd State. Skapa alltid en CancelToken för varje förfrågan och annullera den i dispose(). CancelToken genererar DioException med typen cancel, som måste hanteras korrekt.

Brist på logik för nytt försök för tillfälliga fel. På mobila enheter är nätverket ofta tillfälligt otillgängligt. Implementera en avlyssnare med automatisk upprepning av förfrågan vid tidsgräns eller svar 503/502. Använd RetryInterceptor från paketet dio_smart_retry eller skriv en anpassad avlyssnare med exponentiell fördröjning mellan försöken.