Dio: Nedir ve Flutter için HTTP istemcisinin özellikleri

Dio nedir?

Dio, Dart dili için güçlü bir HTTP istemci kütüphanesidir ve en yaygın olarak Flutter uygulamalarında kullanılır. Dio, interceptor'lar, global yapılandırma, dönüştürücüler, FormData, dosya yükleme ve esnek zaman aşımı yönetimi desteğiyle zengin bir API sunar ve Flutter topluluğunda ağ iletişimi için birincil seçim haline gelir.

Kütüphane, 2018 yılında Wenda Wang tarafından, birçok modern özellikten yoksun olan yerleşik dart:io HttpClient'e alternatif olarak oluşturuldu: tüm istekler için birleşik yapılandırma, interceptor'lar ve otomatik serileştirme. 2025 yılına kadar Dio, popülerlikte Dart ekibinin http paketini geride bırakarak pub.dev'e göre Flutter ekosistemindeki HTTP istemcileri arasında birinci sırayı aldı.

Dio üç adaptörü destekler: DartNativeAdapter (Android, iOS, Desktop'ta varsayılan), BrowserAdapter (Web'de) ve IOAdapter. Adaptör, platforma bağlı olarak otomatik olarak seçilir. Dio ayrıca tüm Flutter platformları için birleşik bir arayüz sağlar — Android, iOS, Web, macOS, Windows ve Linux.

Dio nasıl çalışır

Dio'nun mimarisi bir işleyici zinciri üzerine kurulmuştur. Her istek, isteği (InterceptorsWrapper.onRequest), yanıtı (onResponse) değiştirebilen veya bir hatayı (onError) işleyebilen bir dizi interceptor'dan geçer. Interceptor'lardan sonra istek, göndermeden önce verileri dönüştüren dönüştürücülere (Transformer) gider.

Bir Dio örneği, temel URL, varsayılan başlıklar, zaman aşımları, yanıt türü (JSON, stream, plain), sorgu parametreleri ve veri formatını içeren bir BaseOptions nesnesi aracılığıyla yapılandırılır. Bu ayarlar tüm isteklere uygulanır ancak belirli bir istekte geçersiz kılınabilir. BaseOptions, tüm uygulama için tek bir yapılandırma noktası sağlayarak uç nokta değişikliklerini veya global başlık eklemeyi basitleştirir.

Dio'daki her istek Response<T> döndürür; burada T, dönüştürücü işlemesinden sonraki veri türüdür. Varsayılan olarak Dio, JSON yanıtlarını otomatik olarak Map<String, dynamic>'e dönüştürür. Tür belirtilmiş yanıtlar için Dio, serileştirme paketleriyle birlikte kullanılır: json_serializable, freezed veya built_value. Response; data, headers, statusCode, requestOptions ve ek veriler içerir.

Dio global yapılandırması

Temel yapılandırma Dio(BaseOptions) aracılığıyla oluşturulur. Tüm istekler için baseUrl, connectTimeout ve receiveTimeout, content-type ve accept başlıkları ile queryParameters ayarlanabilir. Tüm bu parametreler her isteğe uygulanır, kod tekrarını ortadan kaldırır ve ağ ayarları yönetimini merkezileştirir.

Dio iki serileştirme modunu destekler: varsayılan olarak JSON (responseType: ResponseType.json) ve akış (ResponseType.stream). Akış modunda, Response.data parçalar halinde okunabilen bir ResponseBody döndürür. Bu, her şeyi belleğe yüklemenin istenmediği büyük yük dosyaları için kullanışlıdır. Düz mod, otomatik JSON ayrıştırması olmadan ham bir dize döndürür.

Dio interceptor'ları

Interceptor'lar, istekleri, yanıtları ve hataları yakalamak ve değiştirmek için Dio'nun temel mekanizmasıdır. OkHttp'nin Interceptor'ını ve Ktor'un eklentilerini tamamen değiştirirler, ancak Dart'a özgü bir API ve Future aracılığıyla eşzamansız destek ile. Interceptor'lar hem global Dio yapılandırmasına hem de bireysel isteklere eklenebilir.

LogInterceptor

Yerleşik LogInterceptor, her isteği günlüğe kaydeder: yöntem, URL, başlıklar, gövde ve yürütme süresi. İki modu vardır: kompakt (istek başına bir satır) ve tam (gövdeyle birlikte tam bilgi). LogInterceptor özellikle geliştirme sırasında kullanışlıdır, ancak koşullu içe aktarma veya global bir bayrak aracılığıyla sürüm yapılarında devre dışı bırakılması önerilir.

Özel interceptor'lar InterceptorsWrapper sınıfı aracılığıyla oluşturulur. Bir, iki veya üç yöntemin tümü (onRequest, onResponse, onError) geçersiz kılınabilir. Dio, interceptor'ları interceptor listesine eklenme sırasına göre kesin olarak yürütür. Bir interceptor handler.next()'i çağırmazsa, zincir kesilir ve yanıt veya hata uygulamaya ulaşmaz.

Dio'da kimlik doğrulama için, Authorization başlığına Bearer token'ı ekleyen bir interceptor kullanılır. Sunucu 401 döndürürse, onError içindeki interceptor bir yenileme isteği aracılığıyla token'ı yenilemeyi dener ve orijinal isteği yeni token'la tekrarlar. Bu desen token yenileme interceptor'ı olarak adlandırılır ve response?.statusCode == 401'i kontrol ederek DioException aracılığıyla uygulanır.

Dio, yeniden deneme mantığı için dio_smart_retry paketi veya özel bir RetryInterceptor aracılığıyla yerleşik destek sağlar. Mobil uygulamalar için yeniden deneme önemlidir: bağlantı 2-3 saniye boyunca kesildiğinde, Dio connectionTimeout veya connectionError türünde bir DioException fırlatır. RetryInterceptor bu istisnayı yakalar ve üstel geri alma (1s, 2s, 4s) ile isteği 3 defaya kadar yeniden dener ve kararsız ağ koşullarında uygulama güvenilirliğini artırır.

Dart'ta Dio kod örnekleri

Dio ile temel bir GET isteğine bakalım. BaseOptions ile bir örnek oluşturulur, temel URL ve zaman aşımları ayarlanır. İstek, Map formatında veri içeren bir Response döndüren get() yöntemi aracılığıyla yürütülür.

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['giriş yap'])

JSON gövdesi olan bir POST isteği için, bir Map nesnesi veya özel bir DTO iletilir. Dio, jsonEncode aracılığıyla Map'i otomatik olarak JSON'a serileştirir. Tür belirtilmiş DTO'lar için queryParameters seçeneği, data alanı veya özel bir Transformer kullanılır.

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

Yetkilendirme interceptor'ı ekleme

Özel bir interceptor, her isteğe Bearer token'ı ekler. onRequest yöntemi, göndermeden önce tetiklenerek başlıkları değiştirir. 401 yanıtında, interceptor token'ı yenileyebilir ve dio.fetch(requestOptions) yöntemi aracılığıyla isteği tekrarlayabilir.

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

Dio ile dosya yükleme ve indirme

Dio, FormData aracılığıyla dosya yüklemeyi basitleştirir. Bir dosya göndermek için File, Bytes veya AssetBundle'dan bir MultipartFile oluşturulur. FormData, doğru sınır ve kodlamayla multipart/form-data başlığını otomatik olarak ayarlar. Dio, onSendProgress aracılığıyla yükleme ilerlemesini destekler.

Dosya indirme için, veri akışını doğrudan bir dosyaya kaydeden download() yöntemi kullanılır. Dio, Range başlığı aracılığıyla kesintiye uğramış indirmeleri sürdürmeyi destekler; bu özellikle büyük dosyalar için kullanışlıdır. İndirme ilerlemesi, onReceiveProgress aracılığıyla izlenir ve kullanıcı arayüzünde bir ilerleme çubuğu görüntülenmesine olanak tanır.

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('Yükleme: $progress%')
    },
)

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

Dio ile çalışırken yaygın hatalar

Yanlış hata işleme en yaygın sorundur. Dio, herhangi bir sorun için bir DioException (önceden DioError) fırlatır: ağ kullanılamazlığı, zaman aşımı, HTTP hataları 4xx/5xx. Birçok geliştirici yalnızca genel Exception'ı yakalar ve hata türü ile onu özel olarak işleme yeteneği hakkında bilgi kaybeder. Başarısızlığın nedenini belirlemek için DioException.type'ı kullanın.

CancelToken'ı yok saymak istek sızıntılarına yol açar. Bir kullanıcı, bir istek hala çalışırken ekrandan ayrılırsa, Dio kaynakları boşa harcar ve yok edilmiş bir State'i güncellemeye çalışabilir. Her istek için her zaman bir CancelToken oluşturun ve dispose() içinde iptal edin. CancelToken, cancel türünde bir DioException oluşturur ve bu doğru şekilde işlenmelidir.

Geçici arızalar için yeniden deneme mantığının eksikliği. Mobil cihazlarda ağ genellikle kısa bir süre için kullanılamaz hale gelir. Zaman aşımı veya 503/502 yanıtında otomatik istek yeniden deneme ile bir interceptor uygulayın. dio_smart_retry paketinden RetryInterceptor kullanın veya denemeler arasında üstel geri alma ile özel bir interceptor yazın.