Dio: ano ito, mga tampok ng HTTP client para sa Flutter

Ano ang Dio?

Dio — ay isang makapangyarihang library ng HTTP client para sa wikang Dart, pinakamalawak na ginagamit sa mga application ng Flutter. Nagbibigay ang Dio ng mayamang API na may suporta para sa mga interceptor, global configuration, transformer, FormData, pag-upload ng file, at flexible na pamamahala ng timeout, na ginagawa itong pangunahing pagpipilian para sa network communication sa Flutter community.

Ang library ay nilikha ni Wenda Wang noong 2018 bilang alternatibo sa built-in na dart:io HttpClient na walang maraming modernong kakayahan: pinag-isang configuration para sa lahat ng request, interceptor, at automatic serialization. Pagsapit ng 2025, nalampasan ng Dio ang http package mula sa Dart team sa kasikatan, na kumuha ng unang pwesto sa mga HTTP client sa Flutter ecosystem ayon sa datos ng pub.dev.

Sinusuportahan ng Dio ang tatlong adapter: DartNativeAdapter (default sa Android, iOS, Desktop), BrowserAdapter (sa Web), at IOAdapter. Ang adapter ay awtomatikong pinipili batay sa platform. Nagbibigay din ang Dio ng pinag-isang interface para sa lahat ng Flutter platform — Android, iOS, Web, macOS, Windows, at Linux.

Paano gumagana ang Dio

Arkitektura ng Dio ay binuo sa isang kadena ng handler (handler chain). Ang bawat request ay dumadaan sa isang pagkakasunod-sunod ng mga interceptor na maaaring magbago ng request (InterceptorsWrapper.onRequest), response (onResponse), o humawak ng error (onError). Pagkatapos ng mga interceptor, ang request ay pumupunta sa mga transformer (Transformer) na nagbabago ng datos bago ipadala.

Ang instance ng Dio ay naka-configure sa pamamagitan ng BaseOptions object na naglalaman ng base URL, default na headers, timeouts, uri ng response (JSON, stream, plain), query parameter, at format ng datos. Ang mga setting na ito ay inilalapat sa lahat ng request, ngunit maaaring ma-override sa isang partikular na request. BaseOptions nagbibigay ng pinag-isang punto ng configuration para sa buong application, na nagpapasimple sa pagpapalit ng API endpoint o pagdagdag ng global headers.

Ang bawat request sa Dio ay nagbabalik ng Response<T>, kung saan ang T — ay ang uri ng datos pagkatapos ng pagproseso ng mga transformer. Bilang default, awtomatikong kino-convert ng Dio ang JSON response sa Map<String, dynamic>. Para sa mga naka-type na response, ginagamit ang Dio kasama ng mga serialization package: json_serializable, freezed, o built_value. Ang Response ay naglalaman ng data, headers, statusCode, requestOptions, at karagdagang datos.

Global configuration ng Dio

Base configuration ay nilikha sa pamamagitan ng Dio(BaseOptions). Maaaring itakda ang baseUrl para sa lahat ng request, connectTimeout at receiveTimeout, content-type at accept headers, pati na rin ang queryParameters. Ang lahat ng parameter na ito ay inilalapat sa bawat request, na nag-aalis ng pagdoble ng code at nagsasentralisa ng pamamahala ng mga network setting.

Sinusuportahan ng Dio ang dalawang mode ng serialization: default JSON (responseType: ResponseType.json) at streaming (ResponseType.stream). Sa streaming mode, ang Response.data ay nagbabalik ng ResponseBody na maaaring basahin nang baha-bahagi. Ito ay maginhawa para sa malalaking payload file kapag ang buong pag-load sa memory ay hindi kanais-nais. Ang plain mode ay nagbabalik ng raw string na walang automatic JSON parsing.

Mga interceptor ng Dio

Mga interceptor — pangunahing mekanismo ng Dio para sa pag-intercept at pagbabago ng mga request, response, at error. Ganap nilang pinapalitan ang Interceptor mula sa OkHttp at mga plugin mula sa Ktor, ngunit may Dart-specific na API at suporta para sa asynchrony sa pamamagitan ng Future. Ang mga interceptor ay maaaring idagdag pareho sa global configuration ng Dio at para sa mga indibidwal na request.

LogInterceptor

Ang built-in na LogInterceptor ay nagla-log ng bawat request: method, URL, headers, body, at oras ng pag-execute. Ito ay may dalawang mode: compact (isang linya bawat request) at full (kumpletong impormasyon na may body). Ang LogInterceptor ay lalong kapaki-pakinabang sa panahon ng pag-develop, ngunit inirerekomenda na huwag itong paganahin sa release build sa pamamagitan ng conditional import o global flag.

Ang mga custom na interceptor ay ginagawa sa pamamagitan ng InterceptorsWrapper class. Maaaring i-override ang isa, dalawa, o lahat ng tatlong paraan (onRequest, onResponse, onError). Isinasagawa ng Dio ang mga interceptor nang mahigpit sa pagkakasunud-sunod ng kanilang pagdagdag sa interceptors list. Kung ang isang interceptor ay hindi tumawag ng handler.next(), ang kadena ay napuputol at ang response/error ay hindi umaabot sa application.

Para sa pagpapatotoo sa Dio, ginagamit ang isang interceptor na nagdaragdag ng Bearer token sa Authorization header. Kung ang server ay nagbalik ng 401, ang interceptor sa onError ay sumusubok na i-refresh ang token sa pamamagitan ng refresh request at inuulit ang orihinal na request gamit ang bagong token. Ang pattern na ito ay tinatawag na token refresh interceptor at ipinapatupad sa pamamagitan ng DioException na may pagsusuri ng response?.statusCode == 401.

Nagbibigay ang Dio ng built-in na suporta para sa retry logic sa pamamagitan ng dio_smart_retry package o custom na RetryInterceptor. Ang pag-retry ay mahalaga para sa mga mobile application: sa pagkawala ng koneksyon sa loob ng 2–3 segundo, nagtatapon ang Dio ng DioException na may uri na connectionTimeout o connectionError. Ang RetryInterceptor ay humahawak ng exception na ito at inuulit ang request hanggang 3 beses na may exponential delay (1s, 2s, 4s), na nagpapataas ng reliability ng application sa mga kondisyon ng hindi matatag na network.

Mga halimbawa ng code ng Dio sa Dart

Tingnan natin ang basic GET request sa pamamagitan ng Dio. Gumagawa ng instance na may BaseOptions, itinatakda ang base URL at timeouts. Ang request ay isinasagawa sa pamamagitan ng get() method, na nagbabalik ng Response na may datos sa 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['mag-login'])

Para sa POST request na may JSON body, isang Map object o custom na DTO ang ipinapasa. Awtomatikong sine-serialize ng Dio ang Map sa JSON sa pamamagitan ng jsonEncode. Para sa naka-type na DTO, ginagamit ang queryParameters option, data field, o custom na 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'])

Pagdagdag ng authorization interceptor

Ang custom na interceptor ay nagdaragdag ng Bearer token sa bawat request. Ang onRequest method ay gumagana bago ang pagpapadala, binabago ang headers. Sa 401 response, maaaring i-refresh ng interceptor ang token at ulitin ang request sa pamamagitan ng 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'))

Pag-upload at pag-download ng file sa pamamagitan ng Dio

Pinapasimple ng Dio ang pag-upload ng file sa pamamagitan ng FormData. Para magpadala ng file, gumagawa ng MultipartFile mula sa File, Bytes, o AssetBundle. Awtomatikong itinatakda ng FormData ang multipart/form-data header na may tamang boundary at encoding. Sinusuportahan ng Dio ang progress ng pag-upload sa pamamagitan ng onSendProgress.

Para sa pag-download ng file, ginagamit ang download() method, na nagse-save ng data stream nang direkta sa file. Sinusuportahan ng Dio ang pagpapatuloy (resume) ng mga naantala na pag-download sa pamamagitan ng Range header, na lalong kapaki-pakinabang para sa malalaking file. Progress ng pag-download ay sinusubaybayan sa pamamagitan ng onReceiveProgress, na nagpapahintulot sa pagpapakita ng progress bar sa 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('I-upload: $progress%')
    },
)

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

Mga karaniwang pagkakamali sa paggamit ng Dio

Maling paghawak ng error — pinakakaraniwang problema. Nagtatapon ang Dio ng DioException (dating DioError) sa anumang problema: walang network, timeout, HTTP 4xx/5xx errors. Maraming developer ang humahawak lamang ng generic Exception, nawawalan ng impormasyon tungkol sa uri ng error at posibilidad ng custom na paghawak nito. Gamitin ang DioException.type upang matukoy ang sanhi ng pagkabigo.

Pagbalewala sa CancelToken ay humahantong sa pagtagas ng request. Kung ang user ay umalis sa screen habang ang request ay tumatakbo pa, ang Dio ay gumagamit ng resources at maaaring subukang i-update ang nawasak na State. Palaging gumawa ng CancelToken para sa bawat request at kanselahin ito sa dispose(). Ang CancelToken ay bumubuo ng DioException na may uri na cancel, na dapat na maayos na hawakan.

Kawalan ng retry logic para sa pansamantalang pagkabigo. Sa mga mobile device, ang network ay madalas na pansamantalang hindi available. Magpatupad ng interceptor na may awtomatikong pag-uulit ng request sa timeout o 503/502 response. Gamitin ang RetryInterceptor mula sa dio_smart_retry package o sumulat ng custom na interceptor na may exponential delay sa pagitan ng mga pagtatangka.