Retrofit کیا ہے، HTTP لائبریری اور ایپلیکیشنز میں استعمال

Retrofit کیا ہے؟

Retrofit ایک لائبریری ہے جو Android ایپلیکیشنز میں HTTP درخواستیں انجام دینے کے لیے Square کمپنی نے تیار کی ہے۔ یہ اینوٹیشنز والے Java انٹرفیسز کے ذریعے REST API کی وضاحت کا اعلانیہ انداز فراہم کرتی ہے، جس سے نیٹ ورک کمیونیکیشن کا کوڈ صاف اور قابلِ پیشگوئی بن جاتا ہے۔

Retrofit کا بنیادی خیال یہ ہے کہ ڈویلپر API کو میتھڈز اور اینوٹیشنز کے ساتھ ایک انٹرفیس کے طور پر بیان کرتا ہے، اور لائبریری خود اپنا نفاذ تیار کرتی ہے۔ یہ انداز اس بات کی ضمانت دیتا ہے کہ تمام اینڈ پوائنٹس ٹائپ شدہ ہیں، اور URL یا پیرامیٹرز میں غلطیاں رن ٹائم کے بجائے کمپائلیشن کے مرحلے پر معلوم ہو جاتی ہیں۔

Retrofit تمام مقبول HTTP میتھڈز اور ڈیٹا فارمیٹس کو سپورٹ کرتا ہے۔ یہ لائبریری Square اور کمیونٹی کی طرف سے فعال طور پر سپورٹ کی جاتی ہے: نئے ورژن باقاعدگی سے جاری ہوتے ہیں، اور موجودہ ورژن 2.11 میں Java 17 اور Kotlin 2.0 کی سپورٹ شامل ہے۔ Retrofit Android کے لیے سب سے مقبول HTTP کلائنٹ بنا ہوا ہے۔

Retrofit OkHttp کے اوپر کام کرتا ہے — جو Square کا ایک موثر HTTP کلائنٹ ہے۔ یہ جوڑا ٹرانسپورٹ پروٹوکول کی سطح پر کیشنگ، درخواستوں کا انٹرسیپشن اور کنکشنز کا انتظام یقینی بناتا ہے۔ لائبریری ہم وقت اور غیر متزامن دونوں کالز کو سپورٹ کرتی ہے۔

2013 میں پہلی ریلیز کے بعد سے Retrofit نے کئی بڑی اپ ڈیٹس حاصل کی ہیں۔ موجودہ Retrofit 2 پہلے ورژن کے تجربے کی بنیاد پر مکمل طور پر دوبارہ لکھا گیا ہے اور غیر متزامن عمل کے لیے کنورٹرز اور ایڈاپٹرز کا زیادہ لچکدار نظام پیش کرتا ہے۔

Retrofit کی آرکیٹیکچر ذمہ داریوں کی تقسیم کے اصول پر عمل کرتی ہے: انٹرفیس صرف API کا معاہدہ طے کرتا ہے، کنورٹرز سیریلائزیشن کے ذمہ دار ہیں، اور ایڈاپٹرز غیر متزامن عمل کو کنٹرول کرتے ہیں۔ یہ باقی کوڈ میں تبدیلی کیے بغیر کسی بھی کمپوننٹ کو تبدیل کرنے کی اجازت دیتا ہے۔ مثال کے طور پر، اینڈ پوائنٹ کی تعریفوں میں تبدیلی کیے بغیر Gson سے Moshi پر منتقل ہو سکتے ہیں۔

Retrofit کی اہم خصوصیات

Retrofit فنکشنز کا ایسا مجموعہ فراہم کرتا ہے جو موبائل ایپلیکیشنز میں نیٹ ورک کمیونیکیشن کے تقریباً تمام منظرناموں کا احاطہ کرتا ہے۔ کلیدی فائدہ — API کی وضاحت کا اعلانیہ انداز ہے۔

اینڈ پوائنٹس کی اعلانیہ اینوٹیشنز

اینوٹیشنز @GET, @POST, @PUT, @PATCH, @DELETE اور @HTTP براہ راست انٹرفیس میں HTTP میتھڈ اور URL ٹیمپلیٹ کی وضاحت کی اجازت دیتی ہیں۔ پاتھ پیرامیٹرز @Path کے ذریعے، query پیرامیٹرز @Query کے ذریعے اور درخواست کا باڈی @Body کے ذریعے طے کیا جاتا ہے۔ یہ انداز ایپلیکیشن کی API پرت کو مکمل طور پر ٹائپ شدہ بناتا ہے۔

سیریلائزیشن کے لیے کنورٹرز

کنورٹرز HTTP جوابات کو Java آبجیکٹس میں تبدیل کرتے ہیں اور اس کے برعکس۔ Retrofit Gson, Moshi, Jackson, Protobuf اور Wire کو سپورٹ کرتا ہے۔ ڈویلپر مطلوبہ کنورٹر کو Converter.Factory کے ذریعے شامل کرتا ہے، اور لائبریری اسے خود بخود تمام درخواستوں اور جوابات پر لاگو کرتی ہے۔

غیر متزامن عمل کے لیے ایڈاپٹرز

ایڈاپٹرز CallAdapter API میتھڈز کی واپسی کی قسم تبدیل کرنے کی اجازت دیتے ہیں۔ معیاری Call کے بجائے RxJava کے لیے Observable، Kotlin کوروٹینز کے لیے Deferred یا LiveData استعمال کیا جا سکتا ہے۔ یہ نیٹ ورک کی درخواستوں کو ایپلیکیشن کی منتخب آرکیٹیکچر کے ساتھ مربوط کرتا ہے۔

متحرک URL اور ہیڈرز

متحرک URL @Url اینوٹیشنز کے ذریعے طے کیے جاتے ہیں، جو رن ٹائم پر اینڈ پوائنٹ منتقل کرنے کی اجازت دیتے ہیں۔ ہیڈرز کو @Headers کے ذریعے مستقل یا @Header پیرامیٹر کے ذریعے متحرک طور پر بتایا جا سکتا ہے۔ تمام درخواستوں کے عالمی ہیڈرز کے لیے OkHttp انٹرسیپٹر استعمال ہوتا ہے، جو ہر خارجی درخواست میں ہیڈرز شامل کرتا ہے۔

Retrofit کیسے کام کرتا ہے؟

Retrofit تین مراحل میں کام کرتا ہے: API انٹرفیس کی وضاحت، Retrofit کا انسٹینس بنانا اور درخواست کا اجراء۔ لائبریری اینوٹیشنز اور کنورٹرز کی بنیاد پر رن ٹائم میں انٹرفیس کا نفاذ تیار کرتی ہے۔

درخواست کا لائف سائیکل

جب API میتھڈ کو کال کیا جاتا ہے، Retrofit اینوٹیشنز اور آرگیومینٹس کی بنیاد پر Request آبجیکٹ بناتا ہے۔ درخواست عمل کے لیے OkHttp کو دی جاتی ہے۔ جواب موصول ہونے کے بعد لائبریری اسے مطلوبہ قسم میں تبدیل کرنے کے لیے Converter.Factory کو دیتی ہے۔ CallAdapter نتیجہ کو غیر متزامن لفافے میں لپیٹتا ہے۔ ہر مرحلہ حسب ضرورت بنایا جا سکتا ہے۔

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val api = retrofit.create(ApiService::class.java)

Retrofit کی تنصیب اور ترتیب

تنصیب Retrofit کی Gradle کے ذریعے کی جاتی ہے — جو Android کی معیاری بلڈ سسٹم ہے۔ یہ لائبریری Maven Central کے ذریعے تقسیم ہوتی ہے اور پروجیکٹ کے build.gradle میں کئی ڈیپینڈنسیز شامل کرنے کا تقاضا کرتی ہے۔

ڈیپینڈنسیز شامل کرنا

build.gradle فائل (ماڈیول کی سطح) میں Retrofit، Gson کنورٹر اور OkHttp کے لیے ڈیپینڈنسیز شامل کریں۔ لائبریریوں کے ورژنز کو مرکزی انتظام کے لیے روٹ build.gradle میں متغیرات میں رکھنے کی سفارش کی جاتی ہے۔ Retrofit 2 کے لیے کم از کم Android API 21 درکار ہے۔

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Retrofit کا انسٹینس بنانا

انسٹینس Retrofit کا Builder کے ذریعے بنایا جاتا ہے۔ لازمی پیرامیٹرز: baseUrl اور ConverterFactory۔ زائد کنکشنز بننے سے بچنے کے لیے Retrofit اور OkHttpClient کے لیے سنگلٹن استعمال کرنے کی سفارش کی جاتی ہے۔ logging-interceptor شامل کرنے سے ڈیولپمنٹ کے دوران نیٹ ورک کی درخواستوں کی ڈیبگنگ آسان ہو جاتی ہے۔

Kotlin پروجیکٹس کے لیے API انٹرفیس میں Call اقسام کے بجائے suspend-فنکشنز استعمال کرنے کی سفارش کی جاتی ہے۔ یہ کوڈ کو آسان بناتا ہے اور کوروٹینز کی منظم ہم آہنگی استعمال کرنے کی اجازت دیتا ہے۔ Call سے suspend پر منتقل ہوتے وقت انٹرفیس میں واپسی کی قسم تبدیل کرنا کافی ہے — باقی کوڈ خود بخود ڈھل جاتا ہے۔

Retrofit استعمال کرنے کی مثالیں

مثالیں ذیل میں Android ایپلیکیشنز میں Retrofit کے ساتھ کام کے عام منظرناموں کو ظاہر کرتی ہیں: سادہ GET درخواست سے لے کر سرور پر فائل اپ لوڈ کرنے تک۔

query پیرامیٹرز کے ساتھ GET درخواست

کوئری سٹرنگ پیرامیٹرز کے ساتھ سادہ GET درخواست — ایک بنیادی آپریشن ہے۔ @Query اینوٹیشن پیرامیٹرز کو خود بخود URL میں شامل کرتی ہے، اور suspend-فنکشن مرکزی تھریڈ کو بلاک کیے بغیر کوروٹین سے درخواست کال کرنے کی اجازت دیتی ہے۔

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

JSON باڈی کے ساتھ POST درخواست

POST درخواست JSON باڈی کے ساتھ آبجیکٹ منتقل کرنے کے لیے @Body اینوٹیشن استعمال کرتی ہے۔ GsonConverterFactory خود بخود User آبجیکٹ کو JSON میں سیریلائز کرتا ہے۔ Kotlin کوروٹینز Callback انٹرفیسز کے بغیر پس منظر کے تھریڈ میں درخواست کا عمل یقینی بناتی ہیں۔

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "آنا ایوانووا", email = "anna@example.com")
val created = api.createUser(user)

Multipart کے ذریعے فائل اپ لوڈ

@Multipart اینوٹیشن @Part کے ساتھ سرور پر فائلیں اپ لوڈ کرنے کی اجازت دیتی ہے۔ Retrofit خود بخود مطلوبہ ہیڈرز کے ساتھ multipart درخواست بناتا ہے۔ OkHttp RequestBody کے ذریعے اپ لوڈ کی پیش رفت کا انتظام کرتا ہے، جس سے صارف کو انڈیکیٹر دکھایا جا سکتا ہے۔

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Retrofit میں غلطیوں کی ہینڈلنگ اور انٹرسیپٹرز

ہینڈلنگ Retrofit میں غلطیوں کی OkHttp اور Kotlin کوروٹینز کے میکانزم کے امتزاج پر مبنی ہے۔ OkHttp کے انٹرسیپٹرز درخواستوں کو لاگ کرنے، تصدیقی ہیڈرز شامل کرنے اور غلطیوں کو ایپلیکیشن کوڈ تک پہنچنے سے پہلے ہینڈل کرنے کی اجازت دیتے ہیں۔

مرکزی ہینڈلنگ کے لیے اکثر API کالز کے اوپر sealed class Result کی شکل میں ایک لفافہ بنایا جاتا ہے۔ ایسی کلاس کے دو وارث ہوتے ہیں: ڈیٹا کے ساتھ Success اور استثناء کے ساتھ Error۔ ViewModel متحد نتیجہ حاصل کرتا ہے اور ہر فنکشن میں غلطی کی ہینڈلنگ کوڈ کو دہرائے بغیر یوزر انٹرفیس کی متعلقہ حالت دکھا سکتا ہے۔

انٹرسیپٹرز Interceptor دو قسموں کے ہوتے ہیں: application انٹرسیپٹرز درخواست کو سرور پر بھیجنے سے پہلے تبدیل کرتے ہیں، جبکہ network انٹرسیپٹرز موصول ہونے کے بعد جواب کے ساتھ کام کرتے ہیں۔ مثال کے طور پر، انٹرسیپٹر 401 موصول ہونے پر خود بخود رسائی ٹوکن کو اپ ڈیٹ کر سکتا ہے اور ڈویلپر کی شرکت کے بغیر نئے ٹوکن کے ساتھ درخواست دہرا سکتا ہے۔

Interceptor کے ذریعے درخواستوں کا لاگنگ

لاگنگ انٹرسیپٹر HttpLoggingInterceptor نیٹ ورک کی درخواستوں کی ڈیبگنگ کے لیے ناگزیر ٹول ہے۔ یہ Logcat میں درخواست کا میتھڈ، URL، ہیڈرز، باڈی اور جواب کا کوڈ دکھاتا ہے۔ لاگنگ کی سطح ترتیب دی جا سکتی ہے: کم سے کم معلومات کے لیے BASIC، ہیڈرز کے لیے HEADERS یا مکمل مواد کے لیے BODY۔ پروڈکشن میں BASIC استعمال کرنے یا لاگنگ مکمل طور پر بند کرنے کی سفارش کی جاتی ہے۔

انٹرسیپٹرز Interceptor OkHttp میں دو اقسام میں تقسیم ہوتے ہیں: درخواست میں تبدیلی کے لیے application انٹرسیپٹرز اور خام نیٹ ورک ڈیٹا کے ساتھ کام کے لیے network انٹرسیپٹرز۔ لاگنگ انٹرسیپٹر خود بخود درخواست اور جواب کی تفصیلات Logcat میں دکھاتا ہے۔

ہینڈلنگ کوروٹین کی سطح پر غلطیوں کی suspend-فنکشن کی کال کے ارد گرد try-catch کے ذریعے کی جاتی ہے۔ Retrofit 4xx اور 5xx کوڈز کے لیے HttpException، نیٹ ورک نہ ہونے پر UnknownHostException اور ٹائم آؤٹ سے تجاوز پر SocketTimeoutException کی صورت میں غلطیاں لوٹاتا ہے۔ متحد ہینڈلنگ کے لیے sealed class Result استعمال کرنے کی سفارش کی جاتی ہے۔