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 для унифицированной обработки.