Retrofit — این چیست، کتابخانه HTTP و استفاده در برنامه‌ها

Retrofit چیست؟

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

ایده اصلی Retrofit این است که توسعه‌دهنده API را به عنوان یک رابط با متدها و حاشیه‌نویسی‌ها توصیف می‌کند و کتابخانه به طور خودکار پیاده‌سازی را تولید می‌کند. این رویکرد تضمین می‌کند که تمام نقاط پایانی تایپ شده هستند و خطاهای URL یا پارامترها در مرحله کامپایل شناسایی می‌شوند نه در زمان اجرا.

Retrofit از تمام روش‌های HTTP محبوب و فرمت‌های داده پشتیبانی می‌کند. کتابخانه توسط Square و جامعه فعالانه پشتیبانی می‌شود: نسخه‌های جدید به طور منظم منتشر می‌شوند و نسخه فعلی ۲.۱۱ شامل پشتیبانی از Java ۱۷ و Kotlin ۲.۰ است. Retrofit محبوب‌ترین کلاینت HTTP برای Android باقی می‌ماند.

Retrofit بر روی OkHttp کار می‌کند — یک کلاینت HTTP کارآمد که همچنین توسط Square ساخته شده است. این ترکیب کش کردن، رهگیری درخواست‌ها و مدیریت اتصالات را در سطح پروتکل انتقال فراهم می‌کند. کتابخانه از فراخوانی‌های همگام و ناهمگام پشتیبانی می‌کند.

از اولین انتشار در سال ۲۰۱۳, Retrofit چندین به‌روزرسانی عمده را پشت سر گذاشته است. نسخه فعلی Retrofit ۲ با در نظر گرفتن تجربه نسخه اول کاملاً بازنویسی شده است و سیستم انعطاف‌پذیرتری از مبدل‌ها و آداپترها را برای ناهمگامی ارائه می‌دهد.

معماری 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 استاندارد می‌توان از Observable برای RxJava, Deferred برای کوروتین‌های Kotlin یا 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 ۲ حداقل به Android API ۲۱ نیاز دارد.

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. توصیه می‌شود از Singleton برای Retrofit و OkHttpClient استفاده کنید تا از ایجاد اتصالات اضافی جلوگیری شود. افزودن logging-interceptor اشکال‌زدایی درخواست‌های شبکه را در طول توسعه ساده می‌کند.

برای پروژه‌های Kotlin توصیه می‌شود در رابط API به جای انواع Call از توابع suspend استفاده کنید. این کار کد را ساده می‌کند و امکان استفاده از هم‌روندی ساختاریافته کوروتین‌ها را فراهم می‌کند. هنگام مهاجرت از Call به suspend کافی است نوع بازگشتی در رابط را تغییر دهید — بقیه کد به طور خودکار تطبیق می‌یابد.

نمونه‌های استفاده از Retrofit

نمونه‌های زیر سناریوهای معمول کار با Retrofit در برنامه‌های Android را نشان می‌دهند: از درخواست GET ساده تا آپلود فایل بر روی سرور.

درخواست GET با پارامترهای query

یک درخواست GET ساده با پارامترهای رشته query — عملیات پایه. حاشیه‌نویسی @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)

درخواست POST با بدنه JSON

درخواست 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 دو نوع هستند: ره‌گیرنده‌های کاربردی درخواست را قبل از ارسال به سرور تغییر می‌دهند و ره‌گیرنده‌های شبکه پس از دریافت پاسخ کار می‌کنند. به عنوان مثال, یک ره‌گیرنده می‌تواند به طور خودکار توکن دسترسی را هنگام دریافت ۴۰۱ به‌روزرسانی کرده و درخواست را با توکن جدید بدون دخالت توسعه‌دهنده تکرار کند.

ثبت درخواست‌ها از طریق Interceptor

ره‌گیرنده ثبت HttpLoggingInterceptor — ابزاری ضروری برای اشکال‌زدایی درخواست‌های شبکه. این ابزار در Logcat متد درخواست, URL, هدرها, بدنه و کد پاسخ را نمایش می‌دهد. سطح ثبت را می‌توان پیکربندی کرد: BASIC برای اطلاعات حداقل, HEADERS برای هدرها یا BODY برای محتوای کامل. در تولید توصیه می‌شود از BASIC استفاده کنید یا ثبت را کاملاً غیرفعال کنید.

ره‌گیرنده‌های Interceptor در OkHttp به دو نوع تقسیم می‌شوند: ره‌گیرنده‌های کاربردی برای تغییر درخواست و ره‌گیرنده‌های شبکه برای کار با داده‌های خام شبکه. ره‌گیرنده ثبت به طور خودکار جزئیات درخواست و پاسخ را در Logcat نمایش می‌دهد.

مدیریت خطا در سطح کوروتین از طریق try-catch در اطراف فراخوانی تابع suspend انجام می‌شود. Retrofit خطاها را به صورت HttpException برای کدهای ۴xx و ۵xx, UnknownHostException در صورت نبود شبکه و SocketTimeoutException در صورت تجاوز از مهلت زمانی برمی‌گرداند. توصیه می‌شود از sealed class Result برای مدیریت یکپارچه استفاده کنید.