Dio: co to je, vlastnosti HTTP klienta pro Flutter

Co je Dio?

Dio — je výkonná knihovna HTTP klienta pro jazyk Dart, nejvíce používaná v aplikacích Flutter. Dio poskytuje bohaté API s podporou zachytávačů, globální konfigurace, transformátorů, FormData, nahrávání souborů a flexibilního řízení časových limitů, což z něj činí hlavní volbu pro síťovou komunikaci v komunitě Flutter.

Knihovnu vytvořil Wenda Wang v roce 2018 jako alternativu k vestavěnému dart:io HttpClient, který postrádal mnoho moderních schopností: jednotnou konfiguraci pro všechny požadavky, zachytávače a automatickou serializaci. Do roku 2025 Dio v popularitě předstihl http balíček od týmu Dart a obsadil první místo mezi HTTP klienty v ekosystému Flutter podle údajů pub.dev.

Dio podporuje tři adaptéry: DartNativeAdapter (výchozí na Android, iOS, Desktop), BrowserAdapter (na Webu) a IOAdapter. Adaptér je automaticky vybrán na základě platformy. Dio také poskytuje jednotné rozhraní pro všechny platformy Flutter — Android, iOS, Web, macOS, Windows a Linux.

Jak Dio funguje

Architektura Dio je postavena na řetězci handlerů (handler chain). Každý požadavek prochází sekvencí zachytávačů, které mohou upravit požadavek (InterceptorsWrapper.onRequest), odpověď (onResponse) nebo zpracovat chybu (onError). Po zachytávačích se požadavek dostává k transformátorům (Transformer), které transformují data před odesláním.

Instance Dio se konfiguruje pomocí objektu BaseOptions obsahujícího základní URL, výchozí hlavičky, časové limity, typ odpovědi (JSON, stream, plain), parametry dotazu a formát dat. Tato nastavení se aplikují na všechny požadavky, ale mohou být přepsána v konkrétním požadavku. BaseOptions poskytuje jednotný konfigurační bod pro celou aplikaci, což zjednodušuje změnu API endpointu nebo přidávání globálních hlaviček.

Každý požadavek v Dio vrací Response<T>, kde T — je typ dat po zpracování transformátory. Ve výchozím nastavení Dio automaticky převádí JSON odpověď na Map<String, dynamic>. Pro typované odpovědi se Dio používá spolu se serializačními balíčky: json_serializable, freezed nebo built_value. Response obsahuje data, headers, statusCode, requestOptions a další data.

Globální konfigurace Dio

Základní konfigurace se vytváří pomocí Dio(BaseOptions). Lze nastavit baseUrl pro všechny požadavky, connectTimeout a receiveTimeout, hlavičky content-type a accept a také queryParameters. Všechny tyto parametry se aplikují na každý požadavek, což eliminuje duplicitu kódu a centralizuje správu síťových nastavení.

Dio podporuje dva režimy serializace: výchozí JSON (responseType: ResponseType.json) a proudový (ResponseType.stream). V proudovém režimu Response.data vrací ResponseBody, který lze číst po částech. To je vhodné pro velké payload soubory, kdy není žádoucí úplné načtení do paměti. Režim plain vrací surový řetězec bez automatického parsování JSONu.

Zachytávače Dio

Zachytávače — klíčový mechanismus Dio pro zachycování a úpravu požadavků, odpovědí a chyb. Zcela nahrazují Interceptor z OkHttp a pluginy z Ktor, ale s API specifickým pro Dart a podporou asynchronnosti přes Future. Zachytávače lze přidávat jak v globální konfiguraci Dio, tak pro jednotlivé požadavky.

LogInterceptor

Vestavěný LogInterceptor zaznamenává každý požadavek: metodu, URL, hlavičky, tělo a čas provedení. Má dva režimy: compact (jeden řádek na požadavek) a full (úplné informace s tělem). LogInterceptor je užitečný zejména během vývoje, ale doporučuje se jej vypnout v release sestaveních pomocí podmíněného importu nebo globálního příznaku.

Vlastní zachytávače se vytvářejí pomocí třídy InterceptorsWrapper. Lze přepsat jednu, dvě nebo všechny tři metody (onRequest, onResponse, onError). Dio provádí zachytávače striktně v pořadí jejich přidání do seznamu interceptors. Pokud zachytávač nezavolá handler.next(), řetězec se přeruší a odpověď/chyba se nedostane k aplikaci.

Pro autentizaci v Dio se používá zachytávač přidávající Bearer token do hlavičky Authorization. Pokud server vrátí 401, zachytávač v onError se pokusí obnovit token pomocí refresh požadavku a zopakuje původní požadavek s novým tokenem. Tento vzor se nazývá token refresh interceptor a je implementován přes DioException s kontrolou response?.statusCode == 401.

Dio poskytuje vestavěnou podporu pro logiku opakování prostřednictvím balíčku dio_smart_retry nebo vlastního RetryInterceptor. Opakování je důležité pro mobilní aplikace: při ztrátě připojení na 2–3 sekundy Dio vyhodí DioException s typem connectionTimeout nebo connectionError. RetryInterceptor zachytí tuto výjimku a zopakuje požadavek až 3krát s exponenciálním zpožděním (1s, 2s, 4s), což zvyšuje spolehlivost aplikace v podmínkách nestabilní sítě.

Příklady kódu Dio v Dartu

Podívejme se na základní GET požadavek přes Dio. Vytvoří se instance s BaseOptions, nastaví se základní URL a časové limity. Požadavek se provede pomocí metody get(), která vrací Response s daty ve formátu 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['přihlášení'])

Pro POST požadavek s JSON tělem se předá objekt Map nebo vlastní DTO. Dio automaticky serializuje Map do JSON pomocí jsonEncode. Pro typované DTO se používá možnost queryParameters, pole data nebo vlastní 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'])

Přidání autorizačního zachytávače

Vlastní zachytávač přidává Bearer token ke každému požadavku. Metoda onRequest funguje před odesláním a upravuje hlavičky. Při odpovědi 401 může zachytávač obnovit token a zopakovat požadavek pomocí metody 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'))

Nahrávání a stahování souborů přes Dio

Dio zjednodušuje nahrávání souborů přes FormData. Pro odeslání souboru se vytvoří MultipartFile z File, Bytes nebo AssetBundle. FormData automaticky nastaví hlavičku multipart/form-data se správnou hranicí a kódováním. Dio podporuje průběh nahrávání přes onSendProgress.

Pro stahování souborů se používá metoda download(), která ukládá datový proud přímo do souboru. Dio podporuje obnovení (resume) přerušených stahování přes hlavičku Range, což je užitečné zejména pro velké soubory. Průběh stahování je sledován přes onReceiveProgress, což umožňuje zobrazit průběhový pruh v UI.

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

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

Typické chyby při práci s Dio

Nesprávné zpracování chyb — nejčastější problém. Dio vyhazuje DioException (dříve DioError) při jakýchkoli problémech: chybějící síť, časový limit, HTTP chyby 4xx/5xx. Mnoho vývojářů zachytává pouze obecnou Exception, čímž ztrácí informaci o typu chyby a možnosti jejího vlastního zpracování. Používejte DioException.type k určení příčiny selhání.

Ignorování CancelToken vede k únikům požadavků. Pokud uživatel opustí obrazovku, zatímco požadavek stále běží, Dio spotřebovává zdroje a může se pokusit aktualizovat zničený State. Vždy vytvářejte CancelToken pro každý požadavek a rušte jej v dispose(). CancelToken generuje DioException s typem cancel, kterou je třeba správně zpracovat.

Chybějící logika opakování pro dočasné výpadky. Na mobilních zařízeních je síť často dočasně nedostupná. Implementujte zachytávač s automatickým opakováním požadavku při časovém limitu nebo odpovědi 503/502. Použijte RetryInterceptor z balíčku dio_smart_retry nebo napište vlastní zachytávač s exponenciálním zpožděním mezi pokusy.