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۔ Response میں 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-specific 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 میں سیریلائز کرتا ہے۔ ٹائپ شدہ DTOs کے لیے، 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 استعمال کریں یا کوششوں کے درمیان تیز رفتار بیک آف کے ساتھ اپنی مرضی کا انٹرسیپٹر لکھیں۔