Retrofit: какво е това, особености на HTTP клиента за Android

Какво е Retrofit?

Retrofit — е библиотека за типизирано взаимодействие с REST API на платформата Android, разработена от компанията Square. Тя предоставя декларативен начин за описване на HTTP заявки чрез Java или Kotlin интерфейси с анотации, напълно освобождавайки разработчика от ръчното парсване на JSON и управлението на HTTP връзки.

Библиотеката се появи през 2013 г. като алтернатива на тромавите решения като AsyncTask и HttpURLConnection. До 2025 г. Retrofit остава де факто стандарт за мрежова комуникация в Android приложения благодарение на простотата и типовата безопасност. Според проучване на JetBrains Developer Ecosystem 2024, Retrofit се използва от над 65% от Android разработчиците в комерсиални проекти.

Ключова разлика между Retrofit и алтернативите — декларативният подход: разработчикът описва какво да прави (кой endpoint да извика, какви параметри да предаде), а не как да го направи (как да отвори връзката, как да чете InputStream, как да парсва JSON). Това намалява количеството boilerplate код с 60–70% в сравнение с ръчното използване на HttpURLConnection.

Как работи Retrofit

Принцип на работа на Retrofit се основава на динамични proxy Java. Когато разработчикът извика метод на интерфейс, маркиран с анотации, Retrofit чрез механизма Proxy.newProxyInstance прихваща извикването и го превръща в HTTP заявка. Целият процес се случва по време на изпълнение без генериране на код на етапа на компилация.

При създаване на инстанция Retrofit.Builder се посочва базовият URL и фабриката за конвертори. Builder конфигурира OkHttpClient — задава таймаути, интерцептори, пул от връзки и кеш. Методът create(Class) генерира имплементация на интерфейса, връщайки proxy обект, който може да се извиква като обикновен клас.

Веригата за изпълнение на заявка изглежда така: анотациите извличат 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 заглавките — статични или динамични.

Комбинирайки тези анотации, може да се опише всеки REST endpoint. Например, за 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

Нека разгледаме практически пример — интерфейс за GitHub API. Създава се 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 се конфигурират веднъж и се използват повторно чрез dependency injection.

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, което може да доведе до NPE при неочаквани null полета.

Алтернатива — 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 MB в OkHttpClient намалява трафика с 40–60% при повторни заявки на една и съща информация.

Създаване на Retrofit за всяка заявка — честа грешка на начинаещите. Retrofit.Builder е ресурсоемка операция, включваща генериране на proxy класове по време на изпълнение. Правилната практика — създаване на една инстанция на Retrofit и повторното ѝ използване чрез DI框架. Hilt, Koin или Dagger осигуряват singleton инстанция на Retrofit за цялото приложение, което спестява памет и ускорява заявките.

Игнориране на Interceptor за авторизация — четвъртият проблем. Вместо ръчно добавяне на заглавката Authorization във всяко извикване, конфигурирайте глобален Interceptor в OkHttpClient. Interceptor прихваща всяка заявка, добавя Bearer токен, а Authenticator обработва отговора 401, обновявайки токена и повтаряйки заявката автоматично. Това централизира логиката за удостоверяване.