Retrofit — यह क्या है, HTTP लाइब्रेरी और अनुप्रयोगों में उपयोग

Retrofit क्या है?

Retrofit Android अनुप्रयोगों में HTTP अनुरोध करने के लिए एक लाइब्रेरी है, जिसे Square द्वारा विकसित किया गया है। यह Java इंटरफ़ेस और एनोटेशन के माध्यम से REST APIs को परिभाषित करने का एक घोषणात्मक दृष्टिकोण प्रदान करता है, जिससे नेटवर्क इंटरैक्शन कोड साफ और पूर्वानुमेय बनता है।

Retrofit का मुख्य विचार यह है कि डेवलपर API को एक इंटरफ़ेस के रूप में विधियों और एनोटेशन के साथ वर्णित करता है, और लाइब्रेरी स्वचालित रूप से कार्यान्वयन उत्पन्न करती है। यह दृष्टिकोण सुनिश्चित करता है कि सभी endpoints टाइप किए गए हैं, और URL या पैरामीटर में त्रुटियाँ रनटाइम के बजाय कंपाइल समय पर पाई जाती हैं।

Retrofit सभी लोकप्रिय HTTP विधियों और डेटा प्रारूपों का समर्थन करता है। लाइब्रेरी Square और समुदाय द्वारा सक्रिय रूप से अनुरक्षित है: नए रिलीज़ नियमित रूप से आते हैं, और वर्तमान संस्करण 2.11 में Java 17 और Kotlin 2.0 के लिए समर्थन शामिल है। Retrofit Android के लिए सबसे लोकप्रिय HTTP क्लाइंट बना हुआ है।

Retrofit OkHttp के ऊपर काम करता है — जो Square का एक कुशल HTTP क्लाइंट भी है। यह संयोजन कैशिंग, अनुरोध इंटरसेप्शन और ट्रांसपोर्ट प्रोटोकॉल स्तर पर कनेक्शन प्रबंधन प्रदान करता है। लाइब्रेरी सिंक्रोनस और एसिंक्रोनस दोनों कॉल का समर्थन करती है।

2013 में अपनी पहली रिलीज़ के बाद से, Retrofit कई प्रमुख अपडेट से गुज़रा है। वर्तमान संस्करण Retrofit 2 को पहले संस्करण के अनुभव के आधार पर पूरी तरह से फिर से लिखा गया है और यह एसिंक्रोनसी के लिए कन्वर्टर और एडेप्टर की एक अधिक लचीली प्रणाली प्रदान करता है।

Retrofit की आर्किटेक्चर जिम्मेदारियों के पृथक्करण के सिद्धांत का पालन करती है: इंटरफ़ेस केवल API अनुबंध को परिभाषित करता है, कन्वर्टर सीरियलाइज़ेशन संभालते हैं, और एडेप्टर एसिंक्रोनसी का प्रबंधन करते हैं। यह बाकी कोड को बदले बिना किसी भी घटक को बदलने की अनुमति देता है। उदाहरण के लिए, आप endpoint परिभाषाओं को बदले बिना Gson से Moshi पर स्विच कर सकते हैं।

Retrofit की मुख्य विशेषताएं

Retrofit सुविधाओं का एक सेट प्रदान करता है जो मोबाइल अनुप्रयोगों में लगभग सभी नेटवर्क इंटरैक्शन परिदृश्यों को कवर करता है। मुख्य लाभ API परिभाषा की घोषणात्मक शैली है।

घोषणात्मक endpoint एनोटेशन

एनोटेशन @GET, @POST, @PUT, @PATCH, @DELETE और @HTTP सीधे इंटरफ़ेस में HTTP विधि और URL टेम्पलेट निर्दिष्ट करने की अनुमति देते हैं। पथ पैरामीटर @Path के माध्यम से, क्वेरी पैरामीटर @Query के माध्यम से, और अनुरोध निकाय @Body के माध्यम से सेट किए जाते हैं। यह दृष्टिकोण एप्लिकेशन की API परत को पूरी तरह से टाइप किया हुआ बनाता है।

सीरियलाइज़ेशन के लिए कन्वर्टर

कन्वर्टर HTTP प्रतिक्रियाओं को Java ऑब्जेक्ट्स में और इसके विपरीत रूपांतरित करते हैं। Retrofit Gson, Moshi, Jackson, Protobuf और Wire का समर्थन करता है। डेवलपर Converter.Factory के माध्यम से आवश्यक कन्वर्टर को जोड़ता है, और लाइब्रेरी इसे सभी अनुरोधों और प्रतिक्रियाओं पर स्वचालित रूप से लागू करती है।

एसिंक्रोनसी के लिए एडेप्टर

एडेप्टर CallAdapter API विधियों के रिटर्न प्रकार को बदलने की अनुमति देते हैं। मानक Call के बजाय, RxJava के लिए Observable, Kotlin coroutines के लिए Deferred, या LiveData का उपयोग किया जा सकता है। यह नेटवर्क अनुरोधों को चुनी गई एप्लिकेशन आर्किटेक्चर के साथ एकीकृत करता है।

डायनामिक URL और हेडर

डायनामिक URL @Url एनोटेशन के माध्यम से सेट किए जाते हैं, जो रनटाइम पर endpoint पास करने की अनुमति देते हैं। हेडर को @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 प्रोजेक्ट्स के लिए, Call प्रकारों के बजाय API इंटरफ़ेस में suspend फ़ंक्शन का उपयोग करने की अनुशंसा की जाती है। यह कोड को सरल बनाता है और coroutines की संरचित समवर्तीता का उपयोग करने की अनुमति देता है। Call से suspend पर स्विच करते समय, केवल इंटरफ़ेस में रिटर्न प्रकार बदलना पर्याप्त है — बाकी कोड स्वचालित रूप से अनुकूलित हो जाता है।

Retrofit उपयोग के उदाहरण

नीचे दिए गए उदाहरण Android अनुप्रयोगों में Retrofit के साथ काम करने के विशिष्ट परिदृश्यों को दर्शाते हैं: एक साधारण GET अनुरोध से लेकर सर्वर पर फ़ाइल अपलोड करने तक।

क्वेरी पैरामीटर के साथ GET अनुरोध

क्वेरी स्ट्रिंग पैरामीटर के साथ एक सरल GET अनुरोध एक बुनियादी ऑपरेशन है। @Query एनोटेशन स्वचालित रूप से URL में पैरामीटर जोड़ता है, और suspend फ़ंक्शन मुख्य थ्रेड को ब्लॉक किए बिना coroutine से अनुरोध को कॉल करने की अनुमति देता है।

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 अनुरोध

JSON निकाय के साथ POST अनुरोध ऑब्जेक्ट पास करने के लिए @Body एनोटेशन का उपयोग करता है। GsonConverterFactory स्वचालित रूप से User ऑब्जेक्ट को JSON में सीरियलाइज़ करता है। Kotlin coroutines 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 coroutines के संयोजन पर बनाया गया है। OkHttp इंटरसेप्टर अनुरोधों को लॉग करने, प्रमाणीकरण हेडर जोड़ने और एप्लिकेशन कोड तक पहुँचने से पहले त्रुटियों को संभालने की अनुमति देते हैं।

केंद्रीकृत त्रुटि प्रबंधन के लिए, API कॉल के चारों ओर एक सील्ड क्लास Result के रूप में एक रैपर बनाया जाता है। ऐसी क्लास में दो उपवर्ग होते हैं: डेटा के साथ Success और अपवाद के साथ Error। ViewModel एक एकीकृत परिणाम प्राप्त करता है और प्रत्येक फ़ंक्शन में त्रुटि प्रबंधन कोड की नकल किए बिना संबंधित उपयोगकर्ता इंटरफ़ेस स्थिति प्रदर्शित कर सकता है।

इंटरसेप्टर दो प्रकार के होते हैं: एप्लिकेशन इंटरसेप्टर सर्वर पर भेजने से पहले अनुरोध को संशोधित करते हैं, और नेटवर्क इंटरसेप्टर प्राप्त करने के बाद प्रतिक्रिया के साथ काम करते हैं। उदाहरण के लिए, एक इंटरसेप्टर 401 प्राप्त करने पर स्वचालित रूप से एक्सेस टोकन को रीफ़्रेश कर सकता है और डेवलपर की भागीदारी के बिना नए टोकन के साथ अनुरोध को दोहरा सकता है।

Interceptor के माध्यम से अनुरोध लॉगिंग

लॉगिंग इंटरसेप्टर HttpLoggingInterceptor नेटवर्क अनुरोधों को डीबग करने के लिए एक अपरिहार्य उपकरण है। यह Logcat में अनुरोध विधि, URL, हेडर, निकाय और प्रतिक्रिया कोड आउटपुट करता है। लॉगिंग स्तर को कॉन्फ़िगर किया जा सकता है: न्यूनतम जानकारी के लिए BASIC, हेडर के लिए HEADERS, या पूर्ण सामग्री के लिए BODY। प्रोडक्शन में, BASIC का उपयोग करने या लॉगिंग को पूरी तरह से अक्षम करने की अनुशंसा की जाती है।

OkHttp में इंटरसेप्टर दो प्रकारों में विभाजित हैं: अनुरोध को संशोधित करने के लिए एप्लिकेशन इंटरसेप्टर और कच्चे नेटवर्क डेटा के साथ काम करने के लिए नेटवर्क इंटरसेप्टर। लॉगिंग इंटरसेप्टर स्वचालित रूप से Logcat में अनुरोध और प्रतिक्रिया विवरण आउटपुट करता है।

कोरूटीन स्तर पर त्रुटि प्रबंधन suspend फ़ंक्शन कॉल के चारों ओर try-catch के माध्यम से किया जाता है। Retrofit 4xx और 5xx कोड के लिए HttpException, नेटवर्क न होने पर UnknownHostException और टाइमआउट से अधिक होने पर SocketTimeoutException के रूप में त्रुटियाँ लौटाता है। एकीकृत प्रबंधन के लिए सील्ड क्लास Result का उपयोग करने की अनुशंसा की जाती है।