Retrofit: چیست، ویژگی‌های HTTP-کلاینت Android

Retrofit چیست؟

Retrofit — کتابخانه‌ای برای تعامل تایپ‌شده با REST API در پلتفرم Android است که توسط شرکت Square توسعه یافته است. این کتابخانه روشی اعلامی برای توصیف درخواست‌های HTTP از طریق رابط‌های Java یا Kotlin با حاشیه‌نویسی‌ها فراهم می‌کند و برنامه‌نویس را کاملاً از تجزیه دستی JSON و مدیریت اتصالات HTTP بی‌نیاز می‌کند.

این کتابخانه در سال 2013 به عنوان جایگزینی برای راه‌حل‌های حجیم مانند AsyncTask و HttpURLConnection ظهور کرد. تا سال 2025، Retrofit به دلیل سادگی و ایمنی نوع به استاندارد دوفاکتو برای ارتباطات شبکه‌ای در برنامه‌های Android تبدیل شده است. طبق نظرسنجی JetBrains Developer Ecosystem 2024، بیش از 65% توسعه‌دهندگان Android در پروژه‌های تجاری از Retrofit استفاده می‌کنند.

تفاوت کلیدی Retrofit با مشابه‌هایش — رویکرد اعلامی: توسعه‌دهنده توصیف می‌کند چه کاری انجام دهد (کدام endpoint را فراخوانی کند، چه پارامترهایی را ارسال کند)، نه اینکه چگونه انجام دهد (چگونه اتصال را باز کند، چگونه InputStream را بخواند، چگونه JSON را تجزیه کند). این مقدار کد الگو را 60–70% در مقایسه با استفاده دستی از HttpURLConnection کاهش می‌دهد.

Retrofit چگونه کار می‌کند

اصل کار Retrofit بر اساس پروکسی‌های پویای Java است. وقتی توسعه‌دهنده متدی از رابط را که با حاشیه‌نویسی‌ها مشخص شده فراخوانی می‌کند، Retrofit از طریق مکانیزم Proxy.newProxyInstance فراخوانی را رهگیری و به درخواست HTTP تبدیل می‌کند. کل فرآیند در زمان اجرا بدون تولید کد در مرحله کامپایل انجام می‌شود.

هنگام ایجاد نمونه Retrofit.Builder، URL پایه و کارخانه مبدل مشخص می‌شود. Builder OkHttpClient را پیکربندی می‌کند — تایم‌اوت‌ها، رهگیرها، استخر اتصالات و حافظه نهان را تنظیم می‌کند. متد create(Class) پیاده‌سازی رابط را تولید می‌کند و یک شیء پروکسی برمی‌گرداند که می‌توان مانند یک کلاس معمولی از آن استفاده کرد.

زنجیره اجرای درخواست به این صورت است: حاشیه‌نویسی‌ها متد HTTP را استخراج می‌کنند، پارامترها در URL یا بدنه درخواست جایگزین می‌شوند، مبدل بدنه را سریال‌سازی می‌کند، OkHttp درخواست را اجرا می‌کند، مبدل پاسخ را دیسریال‌سازی می‌کند، نتیجه در نوع مشخص شده برگردانده می‌شود. هر مرحله ایزوله است و می‌تواند با پیاده‌سازی سفارشی جایگزین شود، مثلاً جایگزینی OkHttpClient با MockWebServer برای تست یا تغییر مبدل هنگام تغییر API.

ویژگی مهم — Retrofit به طور مستقیم از انتقال جریانی داده پشتیبانی نمی‌کند. برای جریان‌سازی از OkHttp ResponseBody به عنوان نوع بازگشتی متد رابط استفاده می‌شود. Retrofit همچنین لغو درخواست‌ها را به طور خودکار مدیریت نمی‌کند — برای لغو باید ارجاعی به Call ذخیره کرده و cancel() را فراخوانی کنید. در Kotlin با توابع suspend، لغو درخواست به طور خودکار هنگام لغو کوروتین والد انجام می‌شود.

چرخه حیات شیء Call

Call<T> — شیئی است که یک درخواست HTTP را نشان می‌دهد. پس از اجرا (execute یا enqueue)، Call قابل استفاده مجدد نیست — برای درخواست مجدد باید یک Call جدید از طریق فراخوانی متد رابط ایجاد کنید. این کار از ارسال تصادفی یک درخواست دو بار محافظت می‌کند که می‌تواند منجر به تکرار عملیات در سرور شود.

در Kotlin به جای Call از توابع suspend استفاده می‌شود که به طور خودکار چرخه حیات درخواست را مدیریت می‌کنند. Retrofit خود اجرا را به Dispatchers.IO تغییر می‌دهد و نتیجه را به کوروتین برمی‌گرداند. این کار کد را 30–40% در مقایسه با نسخه Call و Callback کاهش می‌دهد.

حاشیه‌نویسی‌های Retrofit برای متدهای HTTP

حاشیه‌نویسی‌ها — مکانیزم اصلی پیکربندی درخواست‌های HTTP در Retrofit هستند. هر حاشیه‌نویسی با یک متد HTTP استاندارد مطابقت دارد و مسیر نسبی تا endpoint را می‌پذیرد. Retrofit از GET, POST, PUT, DELETE, PATCH, HEAD و OPTIONS پشتیبانی می‌کند.

حاشیه‌نویسی پارامترهای درخواست

@Path مقدار را در بخش URL جایگزین می‌کند: @Path(id) Int id {id} را در مسیر جایگزین می‌کند. @Query پارامتر query را اضافه می‌کند: @Query(page) Int page به ?page=5 تبدیل می‌شود. @Body شیء را در بدنه درخواست با سریال‌سازی خودکار از طریق مبدل انتخاب‌شده ارسال می‌کند. @Header و @Headers هدرهای HTTP — ایستا یا پویا — را مدیریت می‌کنند.

با ترکیب این حاشیه‌نویسی‌ها می‌توان هر endpoint REST را توصیف کرد. مثلاً برای endpoint POST /api/users/{id}/posts?limit=10 به @POST، @Path برای id، @Query برای limit و @Body برای شیء ارسالی نیاز است. Retrofit به طور خودکار درخواست HTTP صحیح را می‌سازد. علاوه بر این، @Url (URL پویا)، @Field (بدنه form-encoded)، @Part و @PartMap برای درخواست‌های multipart با فایل‌ها پشتیبانی می‌شوند.

نمونه کد Retrofit در Kotlin

بیایید یک مثال عملی را بررسی کنیم — رابطی برای API GitHub. یک رابط Kotlin با متد دریافت لیست مخازن ایجاد می‌شود. Data class Repo ساختار پاسخ JSON را توصیف می‌کند.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

پس از توصیف رابط، یک نمونه Retrofit از طریق Builder ایجاد می‌شود. URL پایه، مبدل و OkHttpClient یک بار پیکربندی شده و از طریق تزریق وابستگی مجدداً استفاده می‌شوند.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

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

پردازش پاسخ با پوشش Response

برای پردازش منعطف وضعیت‌های HTTP از پوشش Response<T> استفاده کنید. این پوشش به کد پاسخ، هدرها و بدنه دسترسی می‌دهد و در خطاهای 4xx و 5xx استثنا پرتاب نمی‌کند. این امکان پردازش 404 و 500 را بدون try-catch فراهم می‌کند.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "خطا: ${response.code()}")
}

مبدل‌ها و سریال‌سازی در Retrofit

مبدل‌ها — اجزای Retrofit هستند که مسئول تبدیل اشیاء به بدنه HTTP و بالعکس می‌باشند. Retrofit سریال‌سازی را در هسته خود جاسازی نمی‌کند — در عوض از رویکرد ماژولار از طریق Converter.Factory استفاده می‌کند که امکان اتصال هر کتابخانه سریال‌سازی را فراهم می‌کند.

محبوب‌ترین مبدل — GsonConverterFactory از Google بر پایه کتابخانه Gson. برای اکثر پروژه‌ها مناسب است، از TypeAdapter و JsonDeserializer سفارشی پشتیبانی می‌کند. با این حال Gson از بازتاب استفاده می‌کند و null safety Kotlin را در نظر نمی‌گیرد که می‌تواند در فیلدهای null غیرمنتظره به NPE منجر شود.

جایگزین — MoshiConverterFactory از Square: سخت‌گیرتر نسبت به انواع، با پشتیبانی بهتر از Kotlin (null safety, default values) و بدون بازتاب. برای پروژه‌های خالص Kotlin بهینه — Kotlinx Serialization Converter که روی حاشیه‌نویسی‌های @Serializable در مرحله کامپایل کار می‌کند. از بازتاب استفاده نمی‌کند، از sealed class، default values و چندسکویی پشتیبانی می‌کند.

انتخاب مبدل بر عملکرد و ایمنی انواع تأثیر می‌گذارد. Gson بدون پیکربندی سفارشی می‌تواند null را در فیلد non-null Kotlin دیسریال‌سازی کند و در هنگام دسترسی باعث NPE شود. Moshi این مشکل را از طریق حاشیه‌نویسی @Json(name) و failOnUnknown حل می‌کند. Kotlinx Serialization امن‌ترین است — کد را در مرحله کامپایل تولید می‌کند و خطاهای نوع در زمان اجرا را کاملاً حذف می‌کند.

خطاهای رایج هنگام کار با Retrofit

عدم پردازش خطاهای HTTP در توابع suspend — رایج‌ترین مشکل. اگر سرور 4xx یا 5xx برگرداند، Retrofit HttpException پرتاب می‌کند. بدون try-catch برنامه به طور ناگهانی خاتمه می‌یابد. استفاده از Response<T> به عنوان نوع بازگشتی این مشکل را حل می‌کند و امکان بررسی isSuccessful را قبل از دسترسی به body فراهم می‌کند.

پیکربندی نادرست حافظه نهان منجر به ترافیک اضافی می‌شود. Retrofit پاسخ‌ها را به طور مستقل ذخیره نمی‌کند — این وظیفه توسط OkHttpClient از طریق Cache انجام می‌شود. بدون حافظه نهان، هر درخواست به طور کامل اجرا می‌شود، حتی زمانی که داده تغییر نکرده است. افزودن Cache به اندازه 10 مگابایت در OkHttpClient ترافیک را 40–60% در درخواست‌های تکراری اطلاعات مشابه کاهش می‌دهد.

ایجاد Retrofit برای هر درخواست — اشتباه رایج مبتدیان. Retrofit.Builder عملیات پرمصرفی است که شامل تولید کلاس‌های پروکسی در زمان اجرا می‌شود. روش صحیح — ایجاد یک نمونه Retrofit و استفاده مجدد از آن از طریق فریمورک‌های DI است. Hilt، Koin یا Dagger یک نمونه singleton از Retrofit را برای کل برنامه فراهم می‌کنند که حافظه را ذخیره کرده و درخواست‌ها را سریع‌تر می‌کند.

نادیده گرفتن Interceptor برای احراز هویت — مشکل چهارم. به جای افزودن دستی هدر Authorization در هر فراخوانی، یک Interceptor سراسری در OkHttpClient پیکربندی کنید. Interceptor هر درخواست را رهگیری کرده و توکن Bearer را اضافه می‌کند، و Authenticator پاسخ 401 را پردازش کرده، توکن را به‌روزرسانی و درخواست را به طور خودکار تکرار می‌کند. این کار منطق احراز هویت را متمرکز می‌کند.