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 за унификовану обраду.