Retrofit لـ Kotlin: دليل شامل مع أمثلة

ما هو Retrofit ولماذا نحتاجه؟

\n\n

Retrofit هو عميل HTTP آمن من حيث النوع (Type-safe) للغات Java و Kotlin، تم تطويره بواسطة شركة Square. وهي واحدة من أشهر المكتبات للعمل مع REST API في نظام Android البيئي. يسمح Retrofit للمطورين بتنفيذ طلبات HTTP إلى الخوادم البعيدة بسهولة وأناقة، مع تحويل استجابات JSON تلقائياً إلى كائنات Kotlin والعكس.

\n\n

لماذا نحتاج Retrofit؟

\n

\n
• تبسيط العمل مع API: بدلاً من كتابة كود ضخم باستخدام HttpURLConnection أو OkHttp، تقوم بتعريف واجهة مع تعليقات توضيحية (annotations)، ويقوم Retrofit بتوليد التنفيذ تلقائياً.
\n
• التسلسل/إلغاء التسلسل التلقائي: بفضل التكامل مع المحولات (Gson، Moshi، Kotlinx Serialization)، يقوم Retrofit بتحويل JSON تلقائياً إلى كائنات Kotlin.
\n
• دعم طرق HTTP المختلفة: GET، POST، PUT، DELETE، PATCH، HEAD و OPTIONS.
\n
• إدارة الرؤوس والمعاملات: إضافة رؤوس ديناميكية أو ثابتة، ومعاملات الاستعلام (query-parameters) ومعاملات المسار (path-parameters) بسهولة.
\n
• عدم التزامن: دعم coroutines في Kotlin (دوال suspend) وواجهات Callback.
\n
• التكامل مع OkHttp: يستخدم Retrofit OkHttp كمحرك HTTP، مما يتيح الوصول إلى إمكانيات قوية لاعتراض الطلبات (interceptors).
\n

\n\n

Retrofit مثالي لتطبيقات Android التي تتفاعل مع خدمات الويب RESTful: من تطبيقات الطقس البسيطة إلى شبكات التواصل الاجتماعي المعقدة.

\n\n

تثبيت Retrofit في مشروع Kotlin

\n\n

على عكس Python (حيث يُستخدم pip)، في مشاريع Kotlin/Android تتم إدارة التبعيات عبر Gradle. أضف الأسطر التالية إلى ملف build.gradle.kts (أو build.gradle) الخاص بالوحدة النمطية (عادةً app):

\n\n

// build.gradle.kts (Module :app)\ndependencies {\n    // مكتبة Retrofit الأساسية\n    implementation("com.squareup.retrofit2:retrofit:2.9.0")\n    \n    // محول للعمل مع JSON (Gson)\n    implementation("com.squareup.retrofit2:converter-gson:2.9.0")\n    \n    // محول بديل (Moshi)\n    // implementation("com.squareup.retrofit2:converter-moshi:2.9.0")\n    \n    // لدعم coroutines (دوال suspend)\n    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")\n    \n    // OkHttp (عادةً ما يكون مضمنًا، ولكن يمكن إضافته صراحةً)\n    implementation("com.squareup.okhttp3:okhttp:4.12.0")\n    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")\n}\n

\n\n

هام: بعد إضافة التبعيات، اضغط على "Sync Now" في Android Studio لتحميل المكتبات.

\n\n

بداية سريعة: مثال كود

\n\n

لنقم بإنشاء تطبيق بسيط يحصل على قائمة من المنشورات من JSONPlaceholder (API اختبارية مجانية).

\n\n

الخطوة 1: إنشاء data-class للاستجابة

\n\n

data class Post(\n    val userId: Int,\n    val id: Int,\n    val title: String,\n    val body: String\n)\n

\n\n

الخطوة 2: تعريف واجهة API

\n\n

interface ApiService {\n    @GET("posts")\n    suspend fun getPosts(): List<Post>\n    \n    @GET("posts/{id}")\n    suspend fun getPostById(@Path("id") postId: Int): Post\n}\n

\n\n

الخطوة 3: إنشاء عميل Retrofit

\n\n

object RetrofitClient {\n    private const val BASE_URL = "https://jsonplaceholder.typicode.com/"\n    \n    val instance: ApiService by lazy {\n        Retrofit.Builder()\n            .baseUrl(BASE_URL)\n            .addConverterFactory(GsonConverterFactory.create())\n            .build()\n            .create(ApiService::class.java)\n    }\n}\n

\n\n

الخطوة 4: الاستخدام في Activity أو ViewModel

\n\n

class MainActivity : AppCompatActivity() {\n    override fun onCreate(savedInstanceState: Bundle?) {\n