Dio: यह क्या है और Flutter के लिए HTTP क्लाइंट की विशेषताएं

Dio क्या है?

Dio Dart भाषा के लिए एक शक्तिशाली HTTP क्लाइंट लाइब्रेरी है, जो Flutter अनुप्रयोगों में सबसे व्यापक रूप से उपयोग की जाती है। Dio इंटरसेप्टर, वैश्विक कॉन्फ़िगरेशन, ट्रांसफॉर्मर, FormData, फ़ाइल अपलोड और लचीली टाइमआउट प्रबंधन के समर्थन के साथ एक समृद्ध API प्रदान करता है, जो इसे Flutter समुदाय में नेटवर्किंग के लिए प्राथमिक विकल्प बनाता है।

यह लाइब्रेरी Wenda Wang द्वारा 2018 में अंतर्निहित dart:io HttpClient के विकल्प के रूप में बनाई गई थी, जिसमें कई आधुनिक सुविधाओं का अभाव था: सभी अनुरोधों के लिए एकीकृत कॉन्फ़िगरेशन, इंटरसेप्टर और स्वचालित सीरियलाइज़ेशन। 2025 तक, Dio ने लोकप्रियता में Dart टीम के http पैकेज को पीछे छोड़ दिया, pub.dev के अनुसार Flutter इकोसिस्टम में HTTP क्लाइंट्स में पहला स्थान प्राप्त किया।

Dio तीन एडाप्टर का समर्थन करता है: DartNativeAdapter (Android, iOS, Desktop पर डिफ़ॉल्ट), BrowserAdapter (Web पर) और IOAdapter। एडाप्टर प्लेटफ़ॉर्म के आधार पर स्वचालित रूप से चुना जाता है। Dio सभी Flutter प्लेटफ़ॉर्म — Android, iOS, Web, macOS, Windows और Linux के लिए एक एकीकृत इंटरफ़ेस भी प्रदान करता है।

Dio कैसे काम करता है

Dio की आर्किटेक्चर हैंडलर चेन पर बनी है। प्रत्येक अनुरोध इंटरसेप्टर के अनुक्रम से गुज़रता है जो अनुरोध (InterceptorsWrapper.onRequest), प्रतिक्रिया (onResponse) को संशोधित कर सकते हैं या त्रुटि (onError) को संभाल सकते हैं। इंटरसेप्टर के बाद, अनुरोध ट्रांसफॉर्मर (Transformer) में जाता है, जो भेजने से पहले डेटा को रूपांतरित करते हैं।

Dio इंस्टेंस को BaseOptions ऑब्जेक्ट के माध्यम से कॉन्फ़िगर किया जाता है जिसमें बेस URL, डिफ़ॉल्ट हेडर, टाइमआउट, प्रतिक्रिया प्रकार (JSON, stream, plain), क्वेरी पैरामीटर और डेटा प्रारूप शामिल होते हैं। ये सेटिंग्स सभी अनुरोधों पर लागू होती हैं लेकिन किसी विशिष्ट अनुरोध में ओवरराइड की जा सकती हैं। BaseOptions पूरे एप्लिकेशन के लिए एक एकल कॉन्फ़िगरेशन बिंदु प्रदान करता है, जो एंडपॉइंट बदलाव या वैश्विक हेडर जोड़ने को सरल बनाता है।

Dio में प्रत्येक अनुरोध Response<T> लौटाता है, जहाँ T ट्रांसफॉर्मर प्रसंस्करण के बाद डेटा प्रकार है। डिफ़ॉल्ट रूप से, Dio स्वचालित रूप से JSON प्रतिक्रियाओं को Map<String, dynamic> में परिवर्तित करता है। टाइप की गई प्रतिक्रियाओं के लिए, Dio का उपयोग सीरियलाइज़ेशन पैकेज के साथ किया जाता है: json_serializable, freezed या built_value। प्रतिक्रिया में data, headers, statusCode, requestOptions और अतिरिक्त डेटा होता है।

Dio वैश्विक कॉन्फ़िगरेशन

मूल कॉन्फ़िगरेशन Dio(BaseOptions) के माध्यम से बनाया जाता है। सभी अनुरोधों के लिए baseUrl, connectTimeout और receiveTimeout, content-type और accept हेडर, साथ ही queryParameters सेट किए जा सकते हैं। ये सभी पैरामीटर प्रत्येक अनुरोध पर लागू होते हैं, कोड दोहराव को समाप्त करते हैं और नेटवर्क सेटिंग्स प्रबंधन को केंद्रीकृत करते हैं।

Dio दो सीरियलाइज़ेशन मोड का समर्थन करता है: डिफ़ॉल्ट रूप से JSON (responseType: ResponseType.json) और स्ट्रीमिंग (ResponseType.stream)। स्ट्रीम मोड में, Response.data एक ResponseBody लौटाता है जिसे भागों में पढ़ा जा सकता है। यह बड़े पेलोड फ़ाइलों के लिए सुविधाजनक है जब सब कुछ मेमोरी में लोड करना वांछनीय नहीं है। प्लेन मोड बिना स्वचालित JSON पार्सिंग के कच्चा स्ट्रिंग लौटाता है।

Dio इंटरसेप्टर

इंटरसेप्टर अनुरोधों, प्रतिक्रियाओं और त्रुटियों को इंटरसेप्ट और संशोधित करने के लिए Dio की मुख्य तंत्र है। वे OkHttp के Interceptor और Ktor के प्लगइन को पूरी तरह से बदल देते हैं, लेकिन Dart-विशिष्ट API और Future के माध्यम से एसिंक्रोनस समर्थन के साथ। इंटरसेप्टर को वैश्विक Dio कॉन्फ़िगरेशन और व्यक्तिगत अनुरोधों दोनों में जोड़ा जा सकता है।

LogInterceptor

अंतर्निहित LogInterceptor प्रत्येक अनुरोध को लॉग करता है: विधि, URL, हेडर, बॉडी और निष्पादन समय। इसके दो मोड हैं: कॉम्पैक्ट (प्रति अनुरोध एक पंक्ति) और पूर्ण (बॉडी के साथ पूरी जानकारी)। LogInterceptor विशेष रूप से विकास के दौरान उपयोगी है, लेकिन इसे सशर्त import या वैश्विक फ़्लैग के माध्यम से रिलीज़ बिल्ड में अक्षम करने की अनुशंसा की जाती है।

कस्टम इंटरसेप्टर InterceptorsWrapper क्लास के माध्यम से बनाए जाते हैं। एक, दो या तीनों विधियों (onRequest, onResponse, onError) को ओवरराइड किया जा सकता है। Dio इंटरसेप्टर को उनके इंटरसेप्टर सूची में जोड़ने के क्रम में सख्ती से निष्पादित करता है। यदि कोई इंटरसेप्टर handler.next() को कॉल नहीं करता है, तो श्रृंखला बाधित होती है और प्रतिक्रिया या त्रुटि एप्लिकेशन तक नहीं पहुँचती है।

Dio में प्रमाणीकरण के लिए, एक इंटरसेप्टर का उपयोग किया जाता है जो Authorization हेडर में Bearer टोकन जोड़ता है। यदि सर्वर 401 लौटाता है, तो onError में इंटरसेप्टर रिफ्रेश अनुरोध के माध्यम से टोकन को नवीनीकृत करने का प्रयास करता है और नए टोकन के साथ मूल अनुरोध को दोहराता है। इस पैटर्न को टोकन रिफ्रेश इंटरसेप्टर कहा जाता है और इसे response?.statusCode == 401 की जाँच करके DioException के माध्यम से कार्यान्वित किया जाता है।

Dio पुनः प्रयास तर्क के लिए dio_smart_retry पैकेज या कस्टम RetryInterceptor के माध्यम से अंतर्निहित समर्थन प्रदान करता है। मोबाइल एप्लिकेशन के लिए पुनः प्रयास महत्वपूर्ण है: जब कनेक्शन 2-3 सेकंड के लिए खो जाता है, तो Dio connectionTimeout या connectionError प्रकार के साथ DioException फेंकता है। RetryInterceptor इस अपवाद को पकड़ता है और एक्सपोनेंशियल बैकऑफ़ (1s, 2s, 4s) के साथ 3 बार तक अनुरोध दोहराता है, अस्थिर नेटवर्क स्थितियों में एप्लिकेशन विश्वसनीयता में सुधार करता है।

Dart में Dio कोड उदाहरण

आइए Dio के माध्यम से मूल GET अनुरोध देखें। BaseOptions के साथ एक इंस्टेंस बनाया जाता है, बेस URL और टाइमआउट सेट किए जाते हैं। अनुरोध get() विधि के माध्यम से निष्पादित किया जाता है, जो Map प्रारूप में डेटा के साथ Response लौटाता है।

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['लॉगिन'])

JSON बॉडी के साथ POST अनुरोध के लिए, एक Map ऑब्जेक्ट या कस्टम DTO पास किया जाता है। Dio स्वचालित रूप से jsonEncode के माध्यम से Map को JSON में सीरियलाइज़ करता है। टाइप किए गए DTO के लिए, queryParameters विकल्प, data फ़ील्ड या कस्टम 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['आईडी'])

प्रमाणीकरण इंटरसेप्टर जोड़ना

एक कस्टम इंटरसेप्टर प्रत्येक अनुरोध में Bearer टोकन जोड़ता है। onRequest विधि भेजने से पहले सक्रिय होती है, हेडर को संशोधित करती है। 401 प्रतिक्रिया पर, इंटरसेप्टर टोकन को रिफ्रेश कर सकता है और 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'))

Dio के माध्यम से फ़ाइल अपलोड और डाउनलोड

Dio सरल बनाता है FormData के माध्यम से फ़ाइल अपलोड। फ़ाइल भेजने के लिए, File, Bytes या AssetBundle से MultipartFile बनाया जाता है। FormData स्वचालित रूप से सही सीमा और एन्कोडिंग के साथ multipart/form-data हेडर सेट करता है। Dio onSendProgress के माध्यम से अपलोड प्रगति का समर्थन करता है।

फ़ाइल डाउनलोड के लिए, download() विधि का उपयोग किया जाता है, जो डेटा स्ट्रीम को सीधे फ़ाइल में सहेजती है। Dio Range हेडर के माध्यम से बाधित डाउनलोड को फिर से शुरू करने का समर्थन करता है, जो विशेष रूप से बड़ी फ़ाइलों के लिए उपयोगी है। डाउनलोड प्रगति onReceiveProgress के माध्यम से ट्रैक की जाती है, जिससे 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('अपलोड: $progress%')
    },
)

// फ़ाइल डाउनलोड
await dio.download(
    'https://example.com/file.zip',
    '/storage/emulated/0/Download/file.zip',
    onReceiveProgress: (received, total) {
        print('डाउनलोड: ${received / total * 100}%')
    },
)

Dio के साथ काम करते समय सामान्य गलतियाँ

गलत त्रुटि प्रबंधन सबसे आम समस्या है। Dio किसी भी समस्या के लिए DioException (पहले DioError) फेंकता है: नेटवर्क अनुपलब्धता, टाइमआउट, HTTP त्रुटियाँ 4xx/5xx। कई डेवलपर केवल सामान्य Exception को पकड़ते हैं, त्रुटि प्रकार और इसे विशेष रूप से संभालने की क्षमता के बारे में जानकारी खो देते हैं। विफलता का कारण निर्धारित करने के लिए DioException.type का उपयोग करें।

CancelToken को अनदेखा करना अनुरोध लीक की ओर ले जाता है। यदि कोई उपयोगकर्ता स्क्रीन छोड़ देता है जबकि अनुरोध अभी भी चल रहा है, तो Dio संसाधन बर्बाद करता है और नष्ट किए गए State को अपडेट करने का प्रयास कर सकता है। हमेशा प्रत्येक अनुरोध के लिए CancelToken बनाएँ और इसे dispose() में रद्द करें। CancelToken cancel प्रकार के साथ DioException उत्पन्न करता है, जिसे ठीक से संभाला जाना चाहिए।

अस्थायी विफलताओं के लिए पुनः प्रयास तर्क का अभाव। मोबाइल उपकरणों पर, नेटवर्क अक्सर थोड़े समय के लिए अनुपलब्ध होता है। टाइमआउट या 503/502 प्रतिक्रिया पर स्वचालित अनुरोध पुनः प्रयास के साथ एक इंटरसेप्टर लागू करें। dio_smart_retry पैकेज से RetryInterceptor का उपयोग करें या प्रयासों के बीच एक्सपोनेंशियल बैकऑफ़ के साथ एक कस्टम इंटरसेप्टर लिखें।