Retrofit: cos'è, caratteristiche del client HTTP Android

Cos'è Retrofit?

Retrofit è una libreria per l'interazione tipizzata con API REST sulla piattaforma Android, sviluppata da Square. Fornisce un modo dichiarativo per descrivere richieste HTTP attraverso interfacce Java o Kotlin con annotazioni, eliminando completamente la necessità di analisi manuale del JSON e gestione delle connessioni HTTP.

La libreria è apparsa nel 2013 come alternativa a soluzioni complesse come AsyncTask e HttpURLConnection. Nel 2025, Retrofit rimane lo standard de facto per la comunicazione di rete nelle applicazioni Android grazie alla sua semplicità e sicurezza dei tipi. Secondo il sondaggio JetBrains Developer Ecosystem 2024, oltre il 65% degli sviluppatori Android utilizza Retrofit in progetti commerciali.

La differenza principale di Retrofit rispetto alle alternative è l'approccio dichiarativo: lo sviluppatore descrive cosa fare (quale endpoint chiamare, quali parametri passare) anziché come farlo (come aprire una connessione, come leggere un InputStream, come analizzare JSON). Ciò riduce il codice boilerplate del 60–70% rispetto all'uso manuale di HttpURLConnection.

Come funziona Retrofit

Il principio di funzionamento di Retrofit si basa sui proxy dinamici Java. Quando lo sviluppatore chiama un metodo di un'interfaccia annotata, Retrofit intercetta la chiamata tramite il meccanismo Proxy.newProxyInstance e la converte in una richiesta HTTP. L'intero processo avviene a runtime senza generazione di codice in fase di compilazione.

Quando si crea un'istanza di Retrofit.Builder, vengono specificati l'URL di base e la fabbrica di convertitori. Il Builder configura OkHttpClient — imposta timeout, intercettori, pool di connessioni e cache. Il metodo create(Class) genera l'implementazione dell'interfaccia, restituendo un oggetto proxy che può essere chiamato come una classe normale.

La catena di esecuzione della richiesta è la seguente: le annotazioni estraggono il metodo HTTP, i parametri vengono sostituiti nell'URL o nel corpo della richiesta, il convertitore serializza il corpo, OkHttp esegue la richiesta, il convertitore deserializza la risposta e il risultato viene restituito nel tipo specificato. Ogni fase è isolata e può essere sostituita con un'implementazione personalizzata, ad esempio sostituire OkHttpClient con MockWebServer per i test o cambiare convertitore quando si modifica l'API.

Una caratteristica importante — Retrofit non supporta la trasmissione di dati in streaming direttamente. Per lo streaming, si utilizza OkHttp ResponseBody come tipo di ritorno del metodo dell'interfaccia. Retrofit non gestisce nemmeno l'annullamento delle richieste automaticamente — per annullare è necessario mantenere un riferimento a Call e chiamare cancel(). In Kotlin con funzioni suspend, l'annullamento della richiesta avviene automaticamente quando la coroutine padre viene annullata.

Ciclo di vita dell'oggetto Call

Call<T> è un oggetto che rappresenta una singola richiesta HTTP. Dopo l'esecuzione (execute o enqueue), un Call non può essere riutilizzato — per una richiesta ripetuta è necessario creare un nuovo Call chiamando il metodo dell'interfaccia. Ciò impedisce l'invio accidentale della stessa richiesta due volte, che potrebbe causare operazioni duplicate sul server.

In Kotlin, invece di Call, vengono utilizzate funzioni suspend, che gestiscono automaticamente il ciclo di vita della richiesta. Retrofit passa l'esecuzione a Dispatchers.IO e restituisce il risultato alla coroutine. Ciò riduce il codice del 30–40% rispetto alla versione con Call e Callback.

Annotazioni Retrofit per metodi HTTP

Le annotazioni sono il meccanismo principale di configurazione delle richieste HTTP in Retrofit. Ogni annotazione corrisponde a un metodo HTTP standard e accetta un percorso relativo all'endpoint. Retrofit supporta GET, POST, PUT, DELETE, PATCH, HEAD e OPTIONS.

Annotazioni dei parametri di richiesta

@Path sostituisce un valore in un segmento di URL: @Path("id") Int id sostituisce {id} nel percorso. @Query aggiunge un parametro di query: @Query("page") Int page diventa ?page=5. @Body passa un oggetto nel corpo della richiesta con serializzazione automatica tramite il convertitore selezionato. @Header e @Headers gestiscono le intestazioni HTTP — statiche o dinamiche.

Combinando queste annotazioni, è possibile descrivere qualsiasi endpoint REST. Ad esempio, per l'endpoint POST /api/users/{id}/posts?limit=10 sono necessari @POST, @Path per id, @Query per limit e @Body per l'oggetto passato. Retrofit assemblerà automaticamente una richiesta HTTP corretta. Inoltre sono supportati @Url (URL dinamico), @Field (corpo codificato in modulo), @Part e @PartMap per richieste multipart con file.

Esempi di codice Retrofit in Kotlin

Consideriamo un esempio pratico — un'interfaccia per l'API di GitHub. Viene creata un'interfaccia Kotlin con un metodo per ottenere l'elenco dei repository. La classe dati Repo descrive la struttura della risposta 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>
}

Dopo aver descritto l'interfaccia, viene creata un'istanza di Retrofit tramite Builder. L'URL di base, il convertitore e OkHttpClient vengono configurati una volta e riutilizzati tramite 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)

Gestione della risposta con wrapper Response

Per una gestione flessibile dei codici di stato HTTP, utilizzare il wrapper Response<T>. Fornisce accesso al codice di risposta, alle intestazioni e al corpo senza lanciare eccezioni sugli errori 4xx e 5xx. Ciò consente di gestire 404 e 500 senza 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", "Error: ${response.code()}")
}

Convertitori e serializzazione in Retrofit

I convertitori sono componenti di Retrofit responsabili della conversione di oggetti in corpo HTTP e viceversa. Retrofit non incorpora la serializzazione nel suo nucleo — utilizza invece un approccio modulare tramite Converter.Factory, consentendo di collegare qualsiasi libreria di serializzazione.

Il convertitore più popolare è GsonConverterFactory di Google basato sulla libreria Gson. Funziona per la maggior parte dei progetti, supporta TypeAdapter e JsonDeserializer personalizzati. Tuttavia, Gson utilizza la riflessione e non rispetta la null safety di Kotlin, il che può portare a NPE su campi null imprevisti.

Un'alternativa è MoshiConverterFactory di Square: più rigoroso con i tipi, con un migliore supporto Kotlin (null safety, valori predefiniti) e senza riflessione. Per progetti in Kotlin puro, l'ideale è Kotlinx Serialization Converter, che funziona con annotazioni @Serializable in fase di compilazione. Non utilizza riflessione, supporta sealed class, valori predefiniti e multipiattaforma.

La scelta del convertitore influisce su prestazioni e sicurezza dei tipi. Gson senza configurazione personalizzata può deserializzare null in un campo non null di Kotlin, causando NPE all'accesso. Moshi risolve questo problema tramite l'annotazione @Json(name) e failOnUnknown. Kotlinx Serialization è il più sicuro — genera codice in fase di compilazione, eliminando completamente gli errori di tipo a runtime.

Errori comuni quando si lavora con Retrofit

La mancanza di gestione degli errori HTTP nelle funzioni suspend è il problema più comune. Se il server restituisce 4xx o 5xx, Retrofit lancia HttpException. Senza try-catch, l'applicazione si blocca. Utilizzare Response<T> come tipo di ritorno risolve questo problema, consentendo di verificare isSuccessful prima di accedere al body.

Una configurazione errata della cache porta a traffico eccessivo. Retrofit non memorizza nella cache le risposte da solo — questo compito è svolto da OkHttpClient tramite Cache. Senza cache, ogni richiesta viene eseguita completamente, anche quando i dati non sono cambiati. Aggiungere una cache di 10 MB in OkHttpClient riduce il traffico del 40–60% nelle richieste ripetute delle stesse informazioni.

Creare Retrofit per ogni richiesta è un errore comune dei principianti. Retrofit.Builder è un'operazione dispendiosa che include la generazione di classi proxy a runtime. La buona pratica è creare una singola istanza di Retrofit e riutilizzarla tramite framework DI. Hilt, Koin o Dagger forniscono un'istanza singleton di Retrofit per l'intera applicazione, risparmiando memoria e accelerando le richieste.

Ignorare Interceptor per l'autorizzazione è il quarto problema. Invece di aggiungere manualmente l'intestazione Authorization a ogni chiamata, configurare un Interceptor globale in OkHttpClient. L'Interceptor intercetta ogni richiesta, aggiunge il token Bearer, e Authenticator gestisce la risposta 401, rinnovando il token e ripetendo automaticamente la richiesta. Ciò centralizza la logica di autenticazione.