Dio: bu nədir, Flutter üçün HTTP-klientinin xüsusiyyətləri

Dio nədir?

Dio — Dart dili üçün güclü HTTP-klient kitabxanasıdır, ən geniş Flutter tətbiqlərində istifadə olunur. Dio interceptorlar, qlobal konfiqurasiya, transformatorlar, FormData, fayl yükləmə və çevik vaxt limiti idarəetməsi ilə zəngin API təmin edir, bu da onu Flutter cəmiyyətində řəbəka əlaqəsi üçün əsas seçim edir.

Kitabxana Venda Vanq tərəfindən 2018-ci ildə daxili dart:io HttpClient-ə alternativ olaraq yaradılmışdır, çünki onda müasir imkanlar yox idi: bütün sorğular üçün vahid konfiqurasiya, interceptorlar və avtomatik serializasiya. 2025-ci ilə qədər Dio populyarlıq baxımından Dart komandasının http paketini ötürərək, pub.dev məlumatlarına görə Flutter ekosistemində HTTP-klientlər arasında birinci yeri tutdu.

Dio üç adapteri dəstəkləyir: DartNativeAdapter (Android, iOS, Desktop-da standart), BrowserAdapter (Web-də) və IOAdapter. Adapter platformadan asılı olaraq avtomatik seçilir. Dio həmçinin bütün Flutter platformaları üçün vahid interfeys təmin edir — Android, iOS, Web, macOS, Windows və Linux.

Dio necə işləyir

Dio arxitekturası handler zəncirinə (handler chain) əsaslanır. Hər bir sorğu interceptorlar ardıcıllığından keçir, onlar sorğu (InterceptorsWrapper.onRequest), cavabı (onResponse) dəyişdirə və ya xətanı (onError) idarə edə bilər. Interceptorlardan sonra sorğu göndərmədən əvvəl məlumatları çevirən transformatorlara (Transformer) daxil olur.

Dio nümunəsi BaseOptions obyekti vasitəsilə konfiqurasiya olunur, tərkibində əsas URL, standart başlıqlar, vaxt limitləri, cavab tipi (JSON, stream, plain), sorğu parametrləri və məlumat formatı var. Bu parametrlər bütün sorğulara tətbiq olunur, lakin konkret sorğuda dəyişdirilə bilər. BaseOptions bütün tətbiq üçün vahid konfiqurasiya nöqtəsi təmin edir, bu da API endpointinin dəyişdirilməsini və ya qlobal başlıqların əlavə edilməsini sadələşdirir.

Dio-da hər bir sorğu Response<T> qaytarır, burada T — transformatorlar tərəfindən emal edildikdən sonra məlumat tipidir. Standart olaraq Dio avtomatik olaraq JSON cavabını Map<String, dynamic>-ə çevirir. Tipləşdirilmiş cavablar üçün Dio serializasiya paketləri ilə birlikdə istifadə olunur: json_serializable, freezed və ya built_value. Response data, headers, statusCode, requestOptions və əlavə məlumatları ehtiva edir.

Dio-nun qlobal konfiqurasiyası

Əsas konfiqurasiya Dio(BaseOptions) vasitəsilə yaradılır. Bütün sorğular üçün baseUrl, connectTimeout və receiveTimeout, content-type və accept başlıqları, həmçinin queryParameters təyin edilə bilər. Bütün bu parametrlər hər bir sorğuya tətbiq olunur, bu da kodun təkrarlanmasını aradan qaldırır və řəbəka parametrlərinin idarə edilməsini mərkəzləşdirir.

Dio iki serializasiya rejimini dəstəkləyir: standart JSON (responseType: ResponseType.json) və axın (ResponseType.stream). Axın rejimində Response.data hissə-hissə oxuna bilən ResponseBody qaytarır. Bu, böyük yük faylları üçün əlverişlidir, tam yaddaşa yükləmə arzuolunmaz olduqda. Plain rejimi avtomatik JSON parsingsiz xam sətri qaytarır.

Dio interceptorları

Interceptorlar — Dio-nun sorğuların, cavabların və xətaların kəsişməsi və dəyişdirilməsi üçün əsas mexanizmidir. Onlar OkHttp-dən Interceptor və Ktor-dan plaginləri tamamilə əvəz edir, lakin Dart-spesifik API və Future vasitəsilə asinxron dəstəyi ilə. Interceptorlar həm Dio-nun qlobal konfiqurasiyasında, həm də ayrı-ayrı sorğular üçün əlavə edilə bilər.

LogInterceptor

Daxili LogInterceptor hər bir sorğunu qeyd edir: metod, URL, başlıqlar, məzmun və icra vaxtı. Onun iki rejimi var: compact (sorğu başına bir sətir) və full (məzmunla tam məlumat). LogInterceptor xüsusilə inkişaf zamanı faydalıdır, lakin onu şərti import və ya qlobal bayraq vasitəsilə release versiyalarında söndürmək tövsiyə olunur.

Fərdi interceptorlar InterceptorsWrapper sinfi vasitəsilə yaradılır. Bir, iki və ya hər üç metodu (onRequest, onResponse, onError) ləğv etmək olar. Dio interceptorları onların interceptorlar siyahısına əlavə edilmə ardıcıllığı ilə ciddi şəkildə icra edir. Əgər interceptor handler.next() çağırmazsa, zəncir kəsilir və cavab/xəta tətbiqə çatmır.

Dio-da avtorizasiya üçün Authorization başlığına Bearer token əlavə edən interceptor istifadə olunur. Server 401 qaytararsa, interceptor onError-də refresh sorğu vasitəsilə tokeni yeniləməyə çalışır və orijinal sorğunu yeni tokenlə təkrarlayır. Bu nümunə token refresh interceptor adlanır və response?.statusCode == 401 yoxlanılması ilə DioException vasitəsilə həyata keçirilir.

Dio təkrar cəhd məntiqi üçün daxili dəstəyi dio_smart_retry paketi və ya fərdi RetryInterceptor vasitəsilə təmin edir. Təkrar cəhd mobil tətbiqlər üçün vacibdir: 2–3 saniyə əlaqə itkisi zamanı Dio connectionTimeout və ya connectionError tipi ilə DioException atır. RetryInterceptor bu istisnanı tətbiq edir və sorğunu eksponensial gecikmə ilə (1s, 2s, 4s) 3 dəfəyə qədər təkrarlayır, bu da qeyri-sabit řəbəka şəraitində tətbiqin etibarlılığını artırır.

Dart-da Dio kod nümunələri

Əsas GET sorğusunu Dio vasitəsilə nəzərdən keçirək. BaseOptions ilə nümunə yaradılır, əsas URL və vaxt limitləri təyin edilir. Sorğu get() metodu vasitəsilə icra olunur, Map formatında məlumatlarla Response qaytarı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['daxil ol'])

JSON məzmunlu POST sorğusu üçün Map obyekti və ya fərdi DTO ötürülür. Dio avtomatik olaraq Map-ı jsonEncode vasitəsilə JSON-a serializasiya edir. Tipləşdirilmiş DTO üçün queryParameters, data sahəsi və ya fərdi Transformer istifadə olunur.

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

Avtorizasiya interceptorunun əlavə edilməsi

Fərdi interceptor hər sorğuya Bearer token əlavə edir. onRequest metodu göndərmədən əvvəl işləyir, başlıqları dəyişdirir. 401 cavabında interceptor tokeni yeniləyə və dio.fetch(requestOptions) metodu vasitəsilə sorğunu təkrarlaya bilər.

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 vasitəsilə faylların yüklənməsi və endirilməsi

Dio asanlaşdırır faylların FormData vasitəsilə yüklənməsini. Fayl göndərmək üçün File, Bytes və ya AssetBundle-dan MultipartFile yaradılır. FormData avtomatik olaraq düzgün sərhəd və kodlaşdırma ilə multipart/form-data başlığını təyin edir. Dio onSendProgress vasitəsilə yükləmə irəliləyişini dəstəkləyir.

Faylların endirilməsi üçün download() metodu istifadə olunur, o məlumat axınını birbaşa fayla yazır. Dio kəsilmiş yükləmələrin davam etdirilməsini (resume) Range başlığı vasitəsilə dəstəkləyir, bu xüsusilə böyük fayllar üçün faydalıdır. Endirmə irəliləyişi onReceiveProgress vasitəsilə izlənilir, UI-də yükləmə zolağının göstərilməsinə imkan verir.

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üklə: $progress%')
    },
)

// Faylın endirilməsi
await dio.download(
    'https://example.com/file.zip',
    '/storage/emulated/0/Download/file.zip',
    onReceiveProgress: (received, total) {
        print('Endir: ${received / total * 100}%')
    },
)

Dio ilə işləyərkən tipik səhvlər

Xətaların səhv işlənməsi — ən çox rast gəlinən problem. Dio hər hansı problemdə DioException (əvvəllər DioError) atır: şəbəkə olmaması, vaxt limiti, HTTP 4xx/5xx xətaları. Bir çox tərtibatçı yalnız ümumi Exception tutur, xəta növü və onun fərdi işlənməsi imkanı haqqında məlumatı itirir. DioException.type-dən nasazlığın səbəbini müəyyən etmək üçün istifadə edin.

CancelToken-in göz ardı edilməsi sorğu sızmasına gətirib çıxarır. İstifadəçi ekranı tərk edərsə, lakin sorğu icra olunmağa davam edərsə, Dio resursları sərf edir və məhv edilmiş State-i yeniləməyə cəhd edə bilər. Həmişə hər sorğu üçün CancelToken yaradın və onu dispose()-da ləğv edin. CancelToken ləğv tipi ilə DioException yaradır, onu düzgün idarə etmək lazımdır.

Təkrar cəhd məntiqinin olmaması müvəqqəti nasazlıqlar üçün. Mobil cihazlarda şəbəkə tez-tez qısa müddətə əlçatan olmur. Vaxt limiti və ya 503/502 cavabında avtomatik təkrarlanan interceptor tətbiq edin. dio_smart_retry paketindən RetryInterceptor istifadə edin və ya cəhdlər arasında eksponensial gecikmə ilə fərdi interceptor yazın.