Retrofit — що це таке, HTTP-бібліотека та використання в додатках

Що таке Retrofit?

Retrofit — це бібліотека для виконання HTTP-запитів в Android-додатках, розроблена компанією Square. Вона надає декларативний підхід до визначення REST API через Java-інтерфейси з анотаціями, що робить код мережевої взаємодії чистим та передбачуваним.

Основна ідея Retrofit полягає в тому, що розробник описує API як інтерфейс з методами та анотаціями, а бібліотека самостійно генерує реалізацію. Такий підхід гарантує, що всі ендпоїнти типізовані, а помилки в URL або параметрах виявляються на етапі компіляції, а не під час виконання.

Retrofit підтримує всі популярні HTTP-методи та формати даних. Бібліотека активно підтримується Square та спільнотою: нові версії виходять регулярно, а поточна версія 2.11 включає підтримку Java 17 та Kotlin 2.0. Retrofit залишається найпопулярнішим HTTP-клієнтом для Android.

Retrofit працює поверх OkHttp — ефективного HTTP-клієнта також від Square. Така комбінація забезпечує кешування, перехоплення запитів та управління з'єднаннями на рівні транспортного протоколу. Бібліотека підтримує як синхронні, так і асинхронні виклики.

З моменту першого релізу в 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 можна використовувати 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 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-проектів рекомендується використовувати suspend-функції в інтерфейсі API замість Call-типів. Це спрощує код та дозволяє використовувати структуровану конкурентність корутин. При переході з Call на suspend достатньо змінити тип повернення в інтерфейсі — інший код адаптується автоматично.

Приклади використання Retrofit

Приклади нижче демонструють типові сценарії роботи з Retrofit в Android-додатках: від простого GET-запиту до завантаження файлу на сервер.

GET-запит з query-параметрами

Простий 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)

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 бувають двох типів: application-перехоплювачі модифікують запит до відправки на сервер, а network-перехоплювачі працюють з відповіддю після отримання. Наприклад, перехоплювач може автоматично оновлювати токен доступу при отриманні 401 та повторювати запит з новим токеном без участі розробника.

Логування запитів через Interceptor

Logging-перехоплювач HttpLoggingInterceptor — незамінний інструмент при налагодженні мережевих запитів. Він виводить в Logcat метод запиту, URL, заголовки, тіло та код відповіді. Рівень логування можна налаштувати: BASIC для мінімальної інформації, HEADERS для заголовків або BODY для повного вмісту. В продакшені рекомендується використовувати BASIC або вимикати логування повністю.

Перехоплювачі Interceptor в OkHttp діляться на два типи: application-перехоплювачі для модифікації запиту та network-перехоплювачі для роботи з сирими мережевими даними. Logging-перехоплювач автоматично виводить деталі запиту та відповіді в Logcat.

Обробка помилок на рівні корутин виконується через try-catch навколо виклику suspend-функції. Retrofit повертає помилки у вигляді HttpException для кодів 4xx та 5xx, UnknownHostException при відсутності мережі та SocketTimeoutException при перевищенні таймауту. Рекомендується використовувати sealed class Result для уніфікованої обробки.