Retrofit — ce este, bibliotecă HTTP și utilizare în aplicații

Ce este Retrofit?

Retrofit este o bibliotecă pentru efectuarea cererilor HTTP în aplicațiile Android, dezvoltată de compania Square. Oferă o abordare declarativă pentru definirea API-urilor REST prin interfețe Java cu adnotări, ceea ce face codul de comunicare în rețea curat și previzibil.

Ideea principală a Retrofit este că dezvoltatorul descrie API-ul ca o interfață cu metode și adnotări, iar biblioteca generează singură implementarea. Această abordare garantează că toate endpointurile sunt tipizate, iar erorile în URL sau parametri sunt detectate în faza de compilare, nu în timpul execuției.

Retrofit suportă toate metodele HTTP populare și formatele de date. Biblioteca este activ întreținută de Square și comunitate: versiunile noi sunt lansate regulat, iar versiunea curentă 2.11 include suport pentru Java 17 și Kotlin 2.0. Retrofit rămâne cel mai popular client HTTP pentru Android.

Retrofit funcționează pe baza OkHttp — un client HTTP eficient, tot de la Square. Această combinație asigură cache, interceptarea cererilor și gestionarea conexiunilor la nivelul protocolului de transport. Biblioteca suportă atât apeluri sincrone, cât și asincrone.

De la prima lansare în 2013, Retrofit a trecut prin câteva actualizări majore. Versiunea actuală Retrofit 2 a fost rescrisă complet ținând cont de experiența primei versiuni și oferă un sistem mai flexibil de convertoare și adaptoare pentru asincronism.

Arhitectura Retrofit respectă principiul separării responsabilităților: interfața definește doar contractul API, convertoarele se ocupă de serializare, iar adaptoarele gestionează asincronismul. Acest lucru permite înlocuirea oricărei componente fără a modifica restul codului. De exemplu, se poate trece de la Gson la Moshi fără a schimba definițiile endpointurilor.

Principalele capacități ale Retrofit

Retrofit oferă un set de funcții care acoperă practic toate scenariile de comunicare în rețea în aplicațiile mobile. Avantajul cheie este stilul declarativ de definire a API-ului.

Adnotări declarative ale endpointurilor

Adnotările @GET, @POST, @PUT, @PATCH, @DELETE și @HTTP permit definirea metodei HTTP și a șablonului URL direct în interfață. Parametrii de cale se setează prin @Path, parametrii de query prin @Query, iar corpul cererii prin @Body. Această abordare face stratul API al aplicației complet tipizat.

Convertoare pentru serializare

Convertoarele transformă răspunsurile HTTP în obiecte Java și invers. Retrofit suportă Gson, Moshi, Jackson, Protobuf și Wire. Dezvoltatorul conectează convertorul necesar prin Converter.Factory, iar biblioteca îl aplică automat la toate cererile și răspunsurile.

Adaptoare pentru asincronism

Adaptoarele CallAdapter permit schimbarea tipului valorii returnate a metodelor API. În loc de Call standard, se poate folosi Observable pentru RxJava, Deferred pentru corutine Kotlin sau LiveData. Aceasta integrează cererile de rețea cu arhitectura aleasă a aplicației.

URL-uri și headere dinamice

URL-urile dinamice se setează prin adnotarea @Url, permițând transmiterea endpointului în timpul execuției. Headerele pot fi specificate static prin @Headers sau dinamic prin parametrul @Header. Pentru headerele globale ale tuturor cererilor se folosește un interceptor OkHttp, care adaugă headere la fiecare cerere outgoing.

Cum funcționează Retrofit?

Retrofit funcționează în trei etape: definirea interfeței API, crearea instanței Retrofit și executarea cererii. Biblioteca generează implementarea interfeței în timpul execuției pe baza adnotărilor și convertoarelor.

Ciclul de viață al cererii

Când este apelată o metodă API, Retrofit creează un obiect Request pe baza adnotărilor și argumentelor. Cererea este transmisă către OkHttp pentru execuție. După primirea răspunsului, biblioteca îl trimite la Converter.Factory pentru transformarea în tipul necesar. CallAdapter împachetează rezultatul într-un înveliș asincron. Fiecare etapă poate fi personalizată.

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)

Instalarea și configurarea Retrofit

Instalarea Retrofit se face prin Gradle — sistemul standard de build Android. Biblioteca este distribuită prin Maven Central și necesită adăugarea mai multor dependențe în build.gradle al proiectului.

Adăugarea dependențelor

În fișierul build.gradle (la nivel de modul) adăugați dependențe pentru Retrofit, convertorul Gson și OkHttp. Versiunile bibliotecilor se recomandă a fi extrase în variabile în build.gradle-ul rădăcină pentru gestionarea centralizată. Retrofit 2 necesită minim 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"
}

Crearea instanței Retrofit

Instanța Retrofit se creează prin Builder. Parametrii obligatorii: baseUrl și ConverterFactory. Se recomandă utilizarea unui singleton pentru Retrofit și OkHttpClient pentru a evita crearea de conexiuni redundante. Adăugarea logging-interceptor simplifică depanarea cererilor de rețea în timpul dezvoltării.

Pentru proiectele Kotlin se recomandă utilizarea funcțiilor suspend în interfața API în locul tipurilor Call. Aceasta simplifică codul și permite utilizarea concurenței structurate a corutinelor. La trecerea de la Call la suspend este suficient să schimbați tipul returnat în interfață — restul codului se adaptează automat.

Exemple de utilizare Retrofit

Exemplele de mai jos demonstrează scenarii tipice de lucru cu Retrofit în aplicațiile Android: de la o simplă cerere GET până la încărcarea unui fișier pe server.

Cerere GET cu parametri query

O cerere GET simplă cu parametri de query — operația de bază. Adnotarea @Query adaugă parametrii automat în URL, iar funcția suspend permite apelarea cererii dintr-o corutină fără a bloca firul principal.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

Cerere POST cu corp JSON

Cererea POST cu corp JSON utilizează adnotarea @Body pentru transmiterea obiectului. GsonConverterFactory serializează automat obiectul User în JSON. Corutinele Kotlin asigură execuția cererii în fundal fără interfețe Callback.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "Anna Ivanova", email = "anna@example.com")
val created = api.createUser(user)

Încărcarea fișierului prin Multipart

Adnotarea @Multipart cu @Part permite încărcarea fișierelor pe server. Retrofit creează automat o cerere multipart cu headerele necesare. OkHttp gestionează progresul încărcării prin RequestBody, permițând afișarea unui indicator de progres utilizatorului.

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)

Gestionarea erorilor și interceptori în Retrofit

Gestionarea erorilor în Retrofit se bazează pe o combinație a mecanismelor OkHttp și corutinelor Kotlin. Interceptorii OkHttp permit logarea cererilor, adăugarea headerelor de autentificare și gestionarea erorilor înainte ca acestea să ajungă la codul aplicației.

Pentru gestionarea centralizată a erorilor se creează adesea un înveliș peste apelurile API sub forma unei sealed class Result. O astfel de clasă conține două subclase: Success cu datele și Error cu excepția. ViewModel primește un rezultat unificat și poate afișa starea corespunzătoare a interfeței utilizator fără a duplica codul de gestionare a erorilor în fiecare funcție.

Interceptorii sunt de două tipuri: interceptori de aplicație modifică cererea înainte de trimiterea către server, iar interceptori de rețea lucrează cu răspunsul după primire. De exemplu, un interceptors poate reîmprospăta automat tokenul de acces la primirea codului 401 și repeta cererea cu noul token fără implicarea dezvoltatorului.

Logarea cererilor prin Interceptor

Interceptorul de logare HttpLoggingInterceptor — un instrument indispensabil la depanarea cererilor de rețea. Acesta afișează în Logcat metoda cererii, URL-ul, headerele, corpul și codul de răspuns. Nivelul de logare poate fi configurat: BASIC pentru informații minime, HEADERS pentru headere sau BODY pentru conținut complet. În producție se recomandă utilizarea BASIC sau dezactivarea completă a logării.

Interceptorii în OkHttp se împart în două tipuri: interceptori de aplicație pentru modificarea cererii și interceptori de rețea pentru lucrul cu datele brute de rețea. Interceptorul de logare afișează automat detaliile cererii și răspunsului în Logcat.

Gestionarea erorilor la nivelul corutinelor se face prin try-catch în jurul apelului funcției suspend. Retrofit returnează erori sub formă de HttpException pentru codurile 4xx și 5xx, UnknownHostException în lipsa rețelei și SocketTimeoutException la depășirea timeout-ului. Se recomandă utilizarea sealed class Result pentru gestionarea unificată.