Dio: apa itu, fitur klien HTTP untuk Flutter

Apa itu Dio?

Dio — adalah perpustakaan klien HTTP yang kuat untuk bahasa Dart, yang paling banyak digunakan dalam aplikasi Flutter. Dio menyediakan API yang kaya dengan dukungan untuk penyadap, konfigurasi global, transformator, FormData, unggah file, dan manajemen batas waktu yang fleksibel, menjadikannya pilihan utama untuk komunikasi jaringan di komunitas Flutter.

Perpustakaan ini dibuat oleh Wenda Wang pada tahun 2018 sebagai alternatif untuk dart:io HttpClient bawaan yang tidak memiliki banyak kemampuan modern: konfigurasi terpadu untuk semua permintaan, penyadap, dan serialisasi otomatis. Pada tahun 2025, Dio telah melampaui paket http dari tim Dart dalam popularitas, menempati posisi pertama di antara klien HTTP di ekosistem Flutter menurut data pub.dev.

Dio mendukung tiga adaptor: DartNativeAdapter (default di Android, iOS, Desktop), BrowserAdapter (di Web), dan IOAdapter. Adaptor dipilih secara otomatis tergantung pada platform. Dio juga menyediakan antarmuka terpadu untuk semua platform Flutter — Android, iOS, Web, macOS, Windows, dan Linux.

Bagaimana Dio bekerja

Arsitektur Dio dibangun di atas rantai penangan (handler chain). Setiap permintaan melewati urutan interceptor yang dapat memodifikasi permintaan (InterceptorsWrapper.onRequest), respons (onResponse), atau menangani kesalahan (onError). Setelah interceptor, permintaan masuk ke transformator (Transformer) yang mengubah data sebelum dikirim.

Instance Dio dikonfigurasi melalui objek BaseOptions yang berisi URL dasar, header default, batas waktu, tipe respons (JSON, stream, plain), parameter kueri, dan format data. Pengaturan ini diterapkan ke semua permintaan, tetapi dapat ditimpa dalam permintaan tertentu. BaseOptions menyediakan titik konfigurasi terpadu untuk seluruh aplikasi, menyederhanakan perubahan endpoint API atau penambahan header global.

Setiap permintaan di Dio mengembalikan Response<T>, di mana T — adalah tipe data setelah diproses oleh transformator. Secara default, Dio secara otomatis mengonversi respons JSON menjadi Map<String, dynamic>. Untuk respons yang diketik, Dio digunakan bersama dengan paket serialisasi: json_serializable, freezed, atau built_value. Response berisi data, headers, statusCode, requestOptions, dan data tambahan.

Konfigurasi global Dio

Konfigurasi dasar dibuat melalui Dio(BaseOptions). Anda dapat mengatur baseUrl untuk semua permintaan, connectTimeout dan receiveTimeout, header content-type dan accept, serta queryParameters. Semua parameter ini diterapkan ke setiap permintaan, menghilangkan duplikasi kode dan memusatkan pengelolaan pengaturan jaringan.

Dio mendukung dua mode serialisasi: default JSON (responseType: ResponseType.json) dan streaming (ResponseType.stream). Dalam mode streaming, Response.data mengembalikan ResponseBody yang dapat dibaca per bagian. Ini berguna untuk file payload besar ketika memuat penuh ke memori tidak diinginkan. Mode plain mengembalikan string mentah tanpa penguraian JSON otomatis.

Interceptor Dio

Interceptor — mekanisme utama Dio untuk menyadap dan memodifikasi permintaan, respons, dan kesalahan. Mereka sepenuhnya menggantikan Interceptor dari OkHttp dan plugin dari Ktor, tetapi dengan API khusus Dart dan dukungan asinkron melalui Future. Interceptor dapat ditambahkan baik dalam konfigurasi global Dio maupun untuk permintaan individu.

LogInterceptor

LogInterceptor bawaan mencatat setiap permintaan: metode, URL, header, body, dan waktu eksekusi. Ini memiliki dua mode: compact (satu baris per permintaan) dan full (informasi lengkap dengan body). LogInterceptor sangat berguna selama pengembangan, tetapi disarankan untuk menonaktifkannya di rilis build melalui impor bersyarat atau bendera global.

Interceptor kustom dibuat melalui kelas InterceptorsWrapper. Anda dapat menimpa satu, dua, atau ketiga metode (onRequest, onResponse, onError). Dio menjalankan interceptor secara ketat sesuai urutan penambahannya ke daftar interceptors. Jika interceptor tidak memanggil handler.next(), rantai terputus dan respons/kesalahan tidak mencapai aplikasi.

Untuk autentikasi di Dio, digunakan interceptor yang menambahkan token Bearer ke header Authorization. Jika server mengembalikan 401, interceptor di onError mencoba memperbarui token melalui permintaan refresh dan mengulangi permintaan asli dengan token baru. Pola ini disebut token refresh interceptor dan diimplementasikan melalui DioException dengan pemeriksaan response?.statusCode == 401.

Dio menyediakan dukungan bawaan untuk logika percobaan ulang melalui paket dio_smart_retry atau RetryInterceptor kustom. Percobaan ulang penting untuk aplikasi seluler: saat kehilangan koneksi selama 2–3 detik, Dio melempar DioException dengan tipe connectionTimeout atau connectionError. RetryInterceptor menangkap pengecualian ini dan mengulangi permintaan hingga 3 kali dengan penundaan eksponensial (1s, 2s, 4s), yang meningkatkan keandalan aplikasi dalam kondisi jaringan tidak stabil.

Contoh kode Dio di Dart

Mari kita lihat permintaan GET dasar melalui Dio. Instance dibuat dengan BaseOptions, URL dasar dan batas waktu ditetapkan. Permintaan dijalankan melalui metode get(), mengembalikan Response dengan data dalam format 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['masuk'])

Untuk permintaan POST dengan body JSON, objek Map atau DTO kustom dikirimkan. Dio secara otomatis menserialisasi Map ke JSON melalui jsonEncode. Untuk DTO yang diketik, gunakan opsi queryParameters, bidang data, atau Transformer kustom.

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

Menambahkan interceptor otorisasi

Interceptor kustom menambahkan token Bearer ke setiap permintaan. Metode onRequest berfungsi sebelum pengiriman, memodifikasi header. Pada respons 401, interceptor dapat memperbarui token dan mengulangi permintaan melalui metode 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'))

Unggah dan unduh file melalui Dio

Dio menyederhanakan unggah file melalui FormData. Untuk mengirim file, MultipartFile dibuat dari File, Bytes, atau AssetBundle. FormData secara otomatis mengatur header multipart/form-data dengan batas dan pengkodean yang benar. Dio mendukung kemajuan unggahan melalui onSendProgress.

Untuk mengunduh file, digunakan metode download(), yang menyimpan aliran data langsung ke file. Dio mendukung melanjutkan (resume) unduhan yang terputus melalui header Range, yang sangat berguna untuk file besar. Kemajuan unduhan dilacak melalui onReceiveProgress, memungkinkan menampilkan bilah kemajuan di 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('Unggah: $progress%')
    },
)

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

Kesalahan umum saat bekerja dengan Dio

Penanganan kesalahan yang salah — masalah paling umum. Dio melempar DioException (sebelumnya DioError) pada masalah apa pun: tidak ada jaringan, batas waktu, kesalahan HTTP 4xx/5xx. Banyak pengembang hanya menangkap Exception generik, kehilangan informasi tentang jenis kesalahan dan kemungkinan penanganan kustomnya. Gunakan DioException.type untuk menentukan penyebab kegagalan.

Mengabaikan CancelToken menyebabkan kebocoran permintaan. Jika pengguna meninggalkan layar sementara permintaan masih berjalan, Dio menghabiskan sumber daya dan mungkin mencoba memperbarui State yang sudah dihancurkan. Selalu buat CancelToken untuk setiap permintaan dan batalkan di dispose(). CancelToken menghasilkan DioException dengan tipe cancel, yang harus ditangani dengan benar.

Tidak adanya logika percobaan ulang untuk kegagalan sementara. Pada perangkat seluler, jaringan sering tidak tersedia untuk sementara. Implementasikan interceptor dengan pengulangan otomatis permintaan saat batas waktu atau respons 503/502. Gunakan RetryInterceptor dari paket dio_smart_retry atau tulis interceptor kustom dengan penundaan eksponensial antara percobaan.