Retrofit — cos'è, libreria HTTP e utilizzo nelle applicazioni

Cos'è Retrofit?

Retrofit è una libreria per effettuare richieste HTTP in applicazioni Android, sviluppata da Square. Fornisce un approccio dichiarativo per definire API REST tramite interfacce Java con annotazioni, rendendo il codice di interazione di rete pulito e prevedibile.

L'idea centrale di Retrofit è che lo sviluppatore descrive l'API come un'interfaccia con metodi e annotazioni, e la libreria genera automaticamente l'implementazione. Questo approccio garantisce che tutti gli endpoint siano tipizzati e che gli errori negli URL o nei parametri vengano rilevati in fase di compilazione, non in fase di esecuzione.

Retrofit supporta tutti i metodi HTTP e formati di dati popolari. La libreria è attivamente mantenuta da Square e dalla comunità: le nuove versioni escono regolarmente e la versione attuale 2.11 include il supporto per Java 17 e Kotlin 2.0. Retrofit rimane il client HTTP più popolare per Android.

Retrofit funziona sopra OkHttp, un client HTTP efficiente anch'esso di Square. Questa combinazione fornisce caching, intercettazione delle richieste e gestione delle connessioni a livello di protocollo di trasporto. La libreria supporta chiamate sia sincrone che asincrone.

Dal suo primo rilascio nel 2013, Retrofit ha subito diversi importanti aggiornamenti. La versione attuale Retrofit 2 è stata completamente riscritta basandosi sull'esperienza della prima versione e offre un sistema più flessibile di convertitori e adattatori per l'asincronia.

L'architettura di Retrofit segue il principio di separazione delle responsabilità: l'interfaccia definisce solo il contratto API, i convertitori gestiscono la serializzazione e gli adattatori gestiscono l'asincronia. Ciò consente di sostituire qualsiasi componente senza modificare il resto del codice. Ad esempio, è possibile passare da Gson a Moshi senza modificare le definizioni degli endpoint.

Caratteristiche principali di Retrofit

Retrofit fornisce un insieme di funzionalità che coprono praticamente tutti gli scenari di interazione di rete nelle applicazioni mobili. Il vantaggio principale è lo stile dichiarativo della definizione dell'API.

Annotazioni dichiarative degli endpoint

Le annotazioni @GET, @POST, @PUT, @PATCH, @DELETE e @HTTP consentono di specificare il metodo HTTP e il modello URL direttamente nell'interfaccia. I parametri di percorso vengono impostati tramite @Path, i parametri di query tramite @Query e il corpo della richiesta tramite @Body. Questo approccio rende il livello API dell'applicazione completamente tipizzato.

Convertitori per la serializzazione

I convertitori trasformano le risposte HTTP in oggetti Java e viceversa. Retrofit supporta Gson, Moshi, Jackson, Protobuf e Wire. Lo sviluppatore collega il convertitore necessario tramite Converter.Factory e la libreria lo applica automaticamente a tutte le richieste e risposte.

Adattatori per l'asincronia

Gli adattatori CallAdapter consentono di modificare il tipo di ritorno dei metodi API. Invece del Call standard, è possibile utilizzare Observable per RxJava, Deferred per le coroutine Kotlin o LiveData. Ciò integra le richieste di rete con l'architettura applicativa scelta.

URL dinamici e intestazioni

Gli URL dinamici vengono impostati tramite l'annotazione @Url, consentendo di passare l'endpoint in fase di esecuzione. Le intestazioni possono essere specificate staticamente tramite @Headers o dinamicamente tramite il parametro @Header. Per le intestazioni globali su tutte le richieste, viene utilizzato un interceptor OkHttp che aggiunge intestazioni a ogni richiesta in uscita.

Come funziona Retrofit?

Retrofit funziona in tre fasi: definire l'interfaccia API, creare un'istanza Retrofit ed eseguire la richiesta. La libreria genera l'implementazione dell'interfaccia in fase di esecuzione basandosi sulle annotazioni e sui convertitori.

Ciclo di vita della richiesta

Quando viene chiamato un metodo API, Retrofit crea un oggetto Request basato sulle annotazioni e sugli argomenti. La richiesta viene passata a OkHttp per l'esecuzione. Dopo aver ricevuto la risposta, la libreria la passa a Converter.Factory per la trasformazione nel tipo richiesto. CallAdapter avvolge il risultato in un wrapper asincrono. Ogni fase può essere personalizzata.

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)

Installazione e configurazione di Retrofit

L'installazione di Retrofit viene eseguita tramite Gradle, il sistema di compilazione standard di Android. La libreria viene distribuita tramite Maven Central e richiede l'aggiunta di diverse dipendenze nel build.gradle del progetto.

Aggiunta delle dipendenze

Nel file build.gradle (a livello di modulo), aggiungi le dipendenze per Retrofit, il convertitore Gson e OkHttp. Si consiglia di estrarre le versioni delle librerie in variabili nel build.gradle radice per una gestione centralizzata. Retrofit 2 richiede almeno 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"
}

Creazione di un'istanza Retrofit

Un'istanza Retrofit viene creata tramite Builder. Parametri obbligatori: baseUrl e ConverterFactory. Si consiglia di utilizzare un singleton per Retrofit e OkHttpClient per evitare di creare connessioni ridondanti. L'aggiunta di un logging-interceptor semplifica il debug delle richieste di rete durante lo sviluppo.

Per i progetti Kotlin, si consiglia di utilizzare funzioni suspend nell'interfaccia API invece dei tipi Call. Ciò semplifica il codice e consente di utilizzare la concorrenza strutturata delle coroutine. Quando si passa da Call a suspend, è sufficiente modificare il tipo di ritorno nell'interfaccia — il resto del codice si adatta automaticamente.

Esempi di utilizzo di Retrofit

Gli esempi seguenti mostrano scenari tipici di lavoro con Retrofit nelle applicazioni Android: da una semplice richiesta GET al caricamento di un file sul server.

Richiesta GET con parametri di query

Una semplice richiesta GET con parametri di stringa di query è un'operazione di base. L'annotazione @Query aggiunge automaticamente i parametri all'URL e la funzione suspend consente di chiamare la richiesta da una coroutine senza bloccare il thread principale.

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

val users = api.getUsers(page = 1)

Richiesta POST con corpo JSON

Una richiesta POST con corpo JSON utilizza l'annotazione @Body per passare l'oggetto. GsonConverterFactory serializza automaticamente l'oggetto User in JSON. Le coroutine Kotlin garantiscono l'esecuzione della richiesta in un thread in background senza interfacce 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)

Caricamento file tramite Multipart

L'annotazione @Multipart con @Part consente di caricare file sul server. Retrofit forma automaticamente una richiesta multipart con le intestazioni necessarie. OkHttp gestisce l'avanzamento del caricamento tramite RequestBody, consentendo di visualizzare un indicatore all'utente.

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)

Gestione degli errori e interceptor in Retrofit

La gestione degli errori in Retrofit si basa su una combinazione di meccanismi OkHttp e coroutine Kotlin. Gli interceptor OkHttp consentono di registrare richieste, aggiungere intestazioni di autenticazione e gestire gli errori prima che raggiungano il codice applicativo.

Per una gestione centralizzata degli errori, viene spesso creato un wrapper intorno alle chiamate API come classe sealed Result. Tale classe ha due sottoclassi: Success con dati ed Error con un'eccezione. Il ViewModel riceve un risultato unificato e può visualizzare lo stato corrispondente dell'interfaccia utente senza duplicare il codice di gestione degli errori in ogni funzione.

Gli interceptor sono di due tipi: gli interceptor di applicazione modificano la richiesta prima dell'invio al server e gli interceptor di rete lavorano con la risposta dopo la ricezione. Ad esempio, un interceptor può aggiornare automaticamente il token di accesso alla ricezione di un 401 e ripetere la richiesta con il nuovo token senza intervento dello sviluppatore.

Registrazione delle richieste tramite Interceptor

L'interceptor di registrazione HttpLoggingInterceptor è uno strumento indispensabile per il debug delle richieste di rete. Invia in Logcat il metodo della richiesta, URL, intestazioni, corpo e codice di risposta. Il livello di registrazione può essere configurato: BASIC per informazioni minime, HEADERS per le intestazioni o BODY per il contenuto completo. In produzione, si consiglia di utilizzare BASIC o disabilitare completamente la registrazione.

Gli interceptor in OkHttp si dividono in due tipi: interceptor di applicazione per modificare la richiesta e interceptor di rete per lavorare con i dati di rete grezzi. L'interceptor di registrazione invia automaticamente i dettagli della richiesta e della risposta in Logcat.

La gestione degli errori a livello di coroutine viene eseguita tramite try-catch intorno alla chiamata della funzione suspend. Retrofit restituisce errori come HttpException per i codici 4xx e 5xx, UnknownHostException in assenza di rete e SocketTimeoutException in caso di superamento del timeout. Si consiglia di utilizzare una classe sealed Result per la gestione unificata.