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

Логване на заявки чрез Interceptor

Прихващач за логване HttpLoggingInterceptor — незаменим инструмент при отстраняване на грешки в мрежови заявки. Той показва в Logcat метода на заявката, URL, заглавия, тяло и код на отговора. Нивото на логване може да се конфигурира: BASIC за минимална информация, HEADERS за заглавия или BODY за пълно съдържание. В продукция се препоръчва BASIC или пълно изключване на логването.

Прихващачите Interceptor в OkHttp се делят на два типа: прихващачи на приложението за модифициране на заявката и мрежови прихващачи за работа с сурови мрежови данни. Прихващачът за логване автоматично показва детайли на заявката и отговора в Logcat.

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