Dio: mi ez, a HTTP-kliens jellemzői Flutterhez

Mi az a Dio?

Dio — egy hatékony HTTP-kliens könyvtár a Dart nyelvhez, amelyet legszélesebb körben Flutter alkalmazásokban használnak. A Dio gazdag API-t kínál elfogók, globális konfiguráció, transzformátorok, FormData, fájlfeltöltés és rugalmas időtúllépés-kezelés támogatásával, ami a hálózati kommunikáció fő választásává teszi a Flutter közösségben.

A könyvtárat Wenda Wang hozta létre 2018-ban a beépített dart:io HttpClient alternatívájaként, amelyből hiányzott számos modern képesség: egységes konfiguráció minden kéréshez, elfogók és automatikus szerializáció. 2025-re a Dio népszerűségben megelőzte a Dart csapat http csomagját, elfoglalva az első helyet a HTTP-kliensek között a Flutter ökoszisztémában a pub.dev adatai szerint.

A Dio három adaptert támogat: DartNativeAdapter (alapértelmezett Android, iOS, Desktop rendszeren), BrowserAdapter (Web-en) és IOAdapter. Az adapter automatikusan kiválasztásra kerül a platformtól függően. A Dio egységes interfészt is biztosít az összes Flutter platformhoz — Android, iOS, Web, macOS, Windows és Linux.

Hogyan működik a Dio

A Dio architektúrája egy kezelőláncra (handler chain) épül. Minden kérés áthalad egy interceptor sorozaton, amelyek módosíthatják a kérést (InterceptorsWrapper.onRequest), a választ (onResponse) vagy kezelhetik a hibát (onError). Az interceptorok után a kérés a transzformátorokhoz (Transformer) kerül, amelyek átalakítják az adatokat küldés előtt.

A Dio példány a BaseOptions objektumon keresztül kerül konfigurálásra, amely tartalmazza az alap URL-t, az alapértelmezett fejléceket, időtúllépéseket, választípust (JSON, stream, plain), lekérdezési paramétereket és adatformátumot. Ezek a beállítások minden kérésre érvényesek, de egy adott kérésben felülírhatók. A BaseOptions egységes konfigurációs pontot biztosít a teljes alkalmazáshoz, leegyszerűsítve az API-végpont váltását vagy globális fejlécek hozzáadását.

Minden kérés a Dio-ban Response<T> értéket ad vissza, ahol T — az adatok típusa a transzformátorok általi feldolgozás után. Alapértelmezés szerint a Dio automatikusan JSON-választ Map<String, dynamic> típusra alakítja. Tipizált válaszokhoz a Dio-t szerializációs csomagokkal együtt használják: json_serializable, freezed vagy built_value. A Response tartalmazza a data, headers, statusCode, requestOptions és kiegészítő adatokat.

A Dio globális konfigurációja

Alapkonfiguráció a Dio(BaseOptions) segítségével hozható létre. Beállítható a baseUrl minden kéréshez, connectTimeout és receiveTimeout, content-type és accept fejlécek, valamint queryParameters. Ezek a paraméterek minden kérésre érvényesülnek, kiküszöbölve a kódismétlést és központosítva a hálózati beállítások kezelését.

A Dio két szerializációs módot támogat: alapértelmezett JSON (responseType: ResponseType.json) és adatfolyam (ResponseType.stream). Adatfolyam módban a Response.data egy ResponseBody-t ad vissza, amely részenként olvasható. Ez nagy payload fájlok esetén kényelmes, amikor a teljes memóriába töltés nem kívánatos. A plain mód nyers karakterláncot ad vissza automatikus JSON-elemzés nélkül.

Dio interceptorok

Az interceptorok — a Dio kulcsmechanizmusa a kérések, válaszok és hibák elfogására és módosítására. Teljesen helyettesítik az OkHttp Interceptor-ját és a Ktor beépülő moduljait, de Dart-specifikus API-val és aszinkron támogatással a Future segítségével. Az interceptorok hozzáadhatók mind a Dio globális konfigurációjában, mind az egyes kérésekhez.

LogInterceptor

A beépített LogInterceptor naplóz minden kérést: metódust, URL-t, fejléceket, törzset és végrehajtási időt. Két módja van: compact (egy sor kérésenként) és full (teljes információ a törzzsel). A LogInterceptor különösen hasznos fejlesztés során, de ajánlott release build-ekben kikapcsolni feltételes import vagy globális jelző segítségével.

Egyéni interceptorok az InterceptorsWrapper osztályon keresztül hozhatók létre. Egy, kettő vagy mindhárom metódus (onRequest, onResponse, onError) felülírható. A Dio szigorúan az interceptors listába való hozzáadás sorrendjében hajtja végre az interceptorokat. Ha egy interceptor nem hívja meg a handler.next()-et, a lánc megszakad, és a válasz/hiba nem jut el az alkalmazáshoz.

Hitelesítéshez a Dio-ban egy olyan interceptor használatos, amely Bearer tokent ad az Authorization fejléchez. Ha a szerver 401-et ad vissza, az interceptor az onError-ban megpróbálja frissíteni a tokent egy refresh kérésen keresztül, és megismétli az eredeti kérést az új tokennal. Ezt a mintát token refresh interceptor-nak hívják, és DioException segítségével implementálható a response?.statusCode == 401 ellenőrzéssel.

A Dio beépített támogatást nyújt az újrapróbálkozási logikához a dio_smart_retry csomagon vagy egyéni RetryInterceptor-on keresztül. Az újrapróbálkozás fontos a mobilalkalmazásoknál: 2–3 másodperces kapcsolatvesztéskor a Dio connectionTimeout vagy connectionError típusú DioException-t dob. A RetryInterceptor elkapja ezt a kivételt, és legfeljebb 3-szor megismétli a kérést exponenciális késleltetéssel (1s, 2s, 4s), ami növeli az alkalmazás megbízhatóságát instabil hálózati körülmények között.

Dio kódpéldák Dart-ban

Vizsgáljuk meg az alapvető GET kérést Dio-n keresztül. Létrejön egy példány BaseOptions-szal, beállításra kerül az alap URL és az időtúllépések. A kérés a get() metóduson keresztül hajtódik végre, amely Response-t ad vissza Map formátumú adatokkal.

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['bejelentkezés'])

POST kérés JSON törzzsel esetén egy Map objektum vagy egyéni DTO kerül átadásra. A Dio automatikusan sorosítja a Map-ot JSON-ba a jsonEncode segítségével. Tipizált DTO-hoz a queryParameters opció, a data mező vagy egyéni Transformer használható.

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

Hitelesítési interceptor hozzáadása

Az egyéni interceptor Bearer tokent ad minden kéréshez. Az onRequest metódus küldés előtt aktiválódik, módosítva a fejléceket. 401-es válasz esetén az interceptor frissítheti a tokent, és megismételheti a kérést a dio.fetch(requestOptions) metóduson keresztül.

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

Fájlok feltöltése és letöltése Dio-n keresztül

A Dio leegyszerűsíti a fájlok feltöltését a FormData segítségével. Fájl küldéséhez MultipartFile jön létre File, Bytes vagy AssetBundle alapján. A FormData automatikusan beállítja a multipart/form-data fejlécet a megfelelő határral és kódolással. A Dio támogatja a feltöltés előrehaladását az onSendProgress segítségével.

Fájlok letöltéséhez a download() metódus használatos, amely az adatfolyamot közvetlenül fájlba menti. A Dio támogatja a megszakított letöltések folytatását (resume) a Range fejléc segítségével, ami különösen hasznos nagy fájlok esetén. A letöltés előrehaladása az onReceiveProgress segítségével követhető, lehetővé téve a folyamatjelző sáv megjelenítését a felhasználói felületen.

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('Feltöltés: $progress%')
    },
)

// Fájl letöltése
await dio.download(
    'https://example.com/file.zip',
    '/storage/emulated/0/Download/file.zip',
    onReceiveProgress: (received, total) {
        print('Letöltés: ${received / total * 100}%')
    },
)

Gyakori hibák a Dio használatakor

A hibák helytelen kezelése — a leggyakoribb probléma. A Dio DioException-t (korábban DioError) dob bármilyen probléma esetén: nincs hálózat, időtúllépés, HTTP 4xx/5xx hibák. Sok fejlesztő csak az általános Exception-t fogja el, elveszítve információt a hiba típusáról és az egyéni kezelés lehetőségéről. Használja a DioException.type-t a hiba okának meghatározásához.

A CancelToken figyelmen kívül hagyása kérésszivárgáshoz vezet. Ha a felhasználó elhagyja a képernyőt, miközben a kérés még fut, a Dio erőforrásokat fogyaszt, és megpróbálhatja frissíteni a megsemmisített State-et. Mindig hozzon létre CancelToken-t minden kéréshez, és szakítsa meg a dispose()-ban. A CancelToken DioException-t generál a cancel típussal, amelyet megfelelően kell kezelni.

Az újrapróbálkozási logika hiánya átmeneti hibák esetén. Mobileszközökön a hálózat gyakran átmenetileg nem elérhető. Implementáljon egy interceptor-t automatikus kérésismétléssel időtúllépés vagy 503/502 válasz esetén. Használja a RetryInterceptor-t a dio_smart_retry csomagból, vagy írjon egyéni interceptor-t exponenciális késleltetéssel a próbálkozások között.