Retrofit: ce este, caracteristicile clientului HTTP Android

Ce este Retrofit?

Retrofit — este o bibliotecă pentru interacțiunea tipizată cu REST API pe platforma Android, dezvoltată de compania Square. Oferă o modalitate declarativă de descriere a cererilor HTTP prin interfețe Java sau Kotlin cu adnotări, eliberând complet dezvoltatorul de parsarea manuală a JSON și gestionarea conexiunilor HTTP.

Biblioteca a apărut în 2013 ca alternativă la soluțiile greoaie precum AsyncTask și HttpURLConnection. Până în 2025, Retrofit rămâne standardul de facto pentru comunicarea în rețea în aplicațiile Android datorită simplității și siguranței tipurilor. Conform sondajului JetBrains Developer Ecosystem 2024, Retrofit este utilizat de peste 65% dintre dezvoltatorii Android în proiecte comerciale.

Diferența cheie dintre Retrofit și analogi — abordarea declarativă: dezvoltatorul descrie ce să facă (ce endpoint să apeleze, ce parametri să transmită), nu cum să facă (cum să deschidă conexiunea, cum să citească InputStream, cum să parseze JSON). Aceasta reduce cantitatea de cod boilerplate cu 60–70% în comparație cu utilizarea manuală a HttpURLConnection.

Cum funcționează Retrofit

Principiul de funcționare al Retrofit se bazează pe proxy-urile dinamice Java. Când dezvoltatorul apelează o metodă a interfeței marcată cu adnotări, Retrofit prin mecanismul Proxy.newProxyInstance interceptează apelul și îl transformă într-o cerere HTTP. Întregul proces are loc în runtime fără generarea de cod în faza de compilare.

La crearea instanței Retrofit.Builder se specifică URL-ul de bază și fabrica de convertoare. Builder configurează OkHttpClient — stabilește timeout-uri, interceptori, pool-ul de conexiuni și cache. Metoda create(Class) generează implementarea interfeței, returnând un obiect proxy care poate fi apelat ca o clasă obișnuită.

Lanțul de execuție a cererii arată astfel: adnotările extrag metoda HTTP, parametrii sunt înlocuiți în URL sau în corpul cererii, convertorul serializează corpul, OkHttp execută cererea, convertorul deserializează răspunsul, rezultatul este returnat în tipul specificat. Fiecare etapă este izolată și poate fi înlocuită cu o implementare personalizată, de exemplu înlocuirea OkHttpClient cu MockWebServer pentru testare sau schimbarea convertorului la schimbarea API.

O caracteristică importantă — Retrofit nu suportă direct transmiterea în flux a datelor. Pentru streaming se folosește OkHttp ResponseBody ca tip de returnare al metodei interfeței. Retrofit, de asemenea, nu gestionează automat anularea cererilor — pentru anulare trebuie să păstrați o referință la Call și să apelați cancel(). În Kotlin cu funcții suspend, anularea cererii are loc automat la anularea corutinei părinte.

Ciclul de viață al obiectului Call

Call<T> — este un obiect care reprezintă o singură cerere HTTP. După execuție (execute sau enqueue), Call nu poate fi reutilizat — pentru o cerere repetată trebuie creat un nou Call prin apelarea metodei interfeței. Acest lucru protejează împotriva trimiterii accidentale a aceleiași cereri de două ori, ceea ce ar putea duce la duplicarea operațiilor pe server.

În Kotlin, în loc de Call se folosesc funcțiile suspend, care gestionează automat ciclul de viață al cererii. Retrofit însuși comută execuția pe Dispatchers.IO și returnează rezultatul în corutină. Aceasta scurtează codul cu 30–40% în comparație cu versiunea pe Call și Callback.

Adnotări Retrofit pentru metode HTTP

Adnotările — sunt mecanismul principal de configurare a cererilor HTTP în Retrofit. Fiecare adnotare corespunde unei metode HTTP standard și acceptă o cale relativă până la endpoint. Retrofit suportă GET, POST, PUT, DELETE, PATCH, HEAD și OPTIONS.

Adnotări ale parametrilor cererii

@Path înlocuiește valoarea în segmentul URL: @Path(id) Int id înlocuiește {id} în cale. @Query adaugă un parametru query: @Query(page) Int page se transformă în ?page=5. @Body transmite obiectul în corpul cererii cu serializare automată prin convertorul selectat. @Header și @Headers gestionează anteturile HTTP — statice sau dinamice.

Combinând aceste adnotări, se poate descrie orice endpoint REST. De exemplu, pentru endpoint-ul POST /api/users/{id}/posts?limit=10 vor fi necesare @POST, @Path pentru id, @Query pentru limit și @Body pentru obiectul transmis. Retrofit va construi automat cererea HTTP corectă. Suplimentar, sunt suportate @Url (URL dinamic), @Field (corp form-encoded), @Part și @PartMap pentru cereri multipart cu fișiere.

Exemple de cod Retrofit în Kotlin

Să examinăm un exemplu practic — o interfață pentru API GitHub. Se creează o interfață Kotlin cu o metodă de obținere a listei de repository-uri. Data class Repo descrie structura răspunsului 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>
}

După descrierea interfeței, se creează o instanță Retrofit prin Builder. URL-ul de bază, convertorul și OkHttpClient se configurează o singură dată și se reutilizează prin injectarea dependențelor.

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)

Procesarea răspunsului cu învelitoarea Response

Pentru procesarea flexibilă a stărilor HTTP utilizați învelitoarea Response<T>. Oferă acces la codul răspunsului, anteturi și corp, fără a arunca excepții la erorile 4xx și 5xx. Permite procesarea 404 și 500 fără 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", "Eroare: ${response.code()}")
}

Convertoare și serializare în Retrofit

Convertoarele — sunt componente Retrofit responsabile pentru transformarea obiectelor în corp HTTP și invers. Retrofit nu încorporează serializarea în nucleu — în schimb, utilizează o abordare modulară prin Converter.Factory, permițând conectarea oricărei biblioteci de serializare.

Cel mai popular convertor — GsonConverterFactory de la Google pe baza bibliotecii Gson. Este potrivit pentru majoritatea proiectelor, suportă TypeAdapter și JsonDeserializer personalizate. Totuși, Gson folosește reflecția și nu ține cont de null safety Kotlin, ceea ce poate duce la NPE la câmpuri null neașteptate.

Alternativa — MoshiConverterFactory de la Square: mai strict cu tipurile, cu suport mai bun pentru Kotlin (null safety, default values) și fără reflecție. Pentru proiectele în Kotlin pur, optim este Kotlinx Serialization Converter, care funcționează pe adnotările @Serializable în faza de compilare. Nu folosește reflecția, suportă sealed class, default values și multi-platformă.

Alegerea convertorului influențează performanța și siguranța tipurilor. Gson fără configurare personalizată poate deserializa null într-un câmp non-null Kotlin, provocând NPE la accesare. Moshi rezolvă această problemă prin adnotarea @Json(name) și failOnUnknown. Kotlinx Serialization este cel mai sigur — generează cod în faza de compilare, eliminând complet erorile de tip în runtime.

Erori tipice la lucrul cu Retrofit

Lipsa procesării erorilor HTTP în funcțiile suspend — cea mai frecventă problemă. Dacă serverul returnează 4xx sau 5xx, Retrofit aruncă HttpException. Fără try-catch, aplicația se va închide brusc. Utilizarea Response<T> ca tip de returnare rezolvă această problemă, permițând verificarea isSuccessful înainte de accesarea body.

Configurarea incorectă a cache-ului duce la trafic excesiv. Retrofit nu stochează în cache răspunsurile singur — această sarcină este rezolvată de OkHttpClient prin Cache. Fără cache, fiecare cerere este executată complet, chiar și atunci când datele nu s-au schimbat. Adăugarea unui Cache de 10 MB în OkHttpClient reduce traficul cu 40–60% la cererile repetate ale aceleiași informații.

Crearea Retrofit pentru fiecare cerere — o greșeală frecventă a începătorilor. Retrofit.Builder este o operație costisitoare care include generarea claselor proxy în runtime. Practica corectă — crearea unei singure instanțe Retrofit și reutilizarea acesteia prin framework-uri DI. Hilt, Koin sau Dagger asigură o instanță singleton Retrofit pentru întreaga aplicație, economisind memorie și accelerând cererile.

Ignorarea Interceptor pentru autorizare — a patra problemă. În loc să adăugați manual antetul Authorization în fiecare apel, configurați un Interceptor global în OkHttpClient. Interceptor interceptează fiecare cerere, adaugă token-ul Bearer, iar Authenticator procesează răspunsul 401, reînnoind token-ul și repetând cererea automat. Aceasta centralizează logica de autentificare.