Retrofit — vad är det, HTTP-bibliotek och användning i applikationer

Vad är Retrofit?

Retrofit är ett bibliotek för att utföra HTTP-förfrågningar i Android-applikationer, utvecklat av företaget Square. Det erbjuder ett deklarativt tillvägagångssätt för att definiera REST API genom Java-gränssnitt med annoteringar, vilket gör nätverkskommunikationskoden ren och förutsägbar.

Huvudidén med Retrofit är att utvecklaren beskriver API:et som ett gränssnitt med metoder och annoteringar, och biblioteket genererar själv implementeringen. Detta tillvägagångssätt garanterar att alla endpoints är typade och att fel i URL eller parametrar upptäcks vid kompilering, inte under körning.

Retrofit stöder alla populära HTTP-metoder och dataformat. Biblioteket underhålls aktivt av Square och communityn: nya versioner släpps regelbundet och den aktuella versionen 2.11 inkluderar stöd för Java 17 och Kotlin 2.0. Retrofit förblir den mest populära HTTP-klienten för Android.

Retrofit fungerar ovanpå OkHttp — en effektiv HTTP-klient även från Square. Denna kombination ger cachning, avlyssning av förfrågningar och anslutningshantering på transportprotokollnivå. Biblioteket stöder både synkrona och asynkrona anrop.

Sedan den första releasen 2013 har Retrofit genomgått flera stora uppdateringar. Den nuvarande versionen Retrofit 2 har skrivits om helt med erfarenhet från första versionen och erbjuder ett mer flexibelt system av omvandlare och adaptrar för asynkronicitet.

Arkitekturen i Retrofit följer principen om separation av ansvar: gränssnittet definierar bara API-kontraktet, omvandlarna ansvarar för serialisering och adaptrarna hanterar asynkronicitet. Detta gör det möjligt att byta ut vilken komponent som helst utan att ändra resten av koden. Till exempel kan man gå från Gson till Moshi utan att ändra endpointdefinitionerna.

Huvudfunktioner i Retrofit

Retrofit erbjuder en uppsättning funktioner som täcker i stort sett alla scenarier för nätverkskommunikation i mobila applikationer. Den största fördelen är den deklarativa stilen för API-definition.

Deklarativa annoteringar av endpoints

Annoteringar @GET, @POST, @PUT, @PATCH, @DELETE och @HTTP gör det möjligt att definiera HTTP-metoden och URL-mallen direkt i gränssnittet. Sökvägsparametrar ställs in via @Path, frågeparametrar via @Query och förfrågningskroppen via @Body. Detta tillvägagångssätt gör applikationens API-lager helt typat.

Omvandlare för serialisering

Omvandlare omvandlar HTTP-svar till Java-objekt och vice versa. Retrofit stöder Gson, Moshi, Jackson, Protobuf och Wire. Utvecklaren ansluter den önskade omvandlaren via Converter.Factory och biblioteket tillämpar den automatiskt på alla förfrågningar och svar.

Adaptrar för asynkronicitet

Adaptrar CallAdapter gör det möjligt att ändra returtypen för API-metoder. Istället för standard Call kan man använda Observable för RxJava, Deferred för Kotlin-korutiner eller LiveData. Detta integrerar nätverksförfrågningar med den valda applikationsarkitekturen.

Dynamiska URL:er och rubriker

Dynamiska URL:er ställs in via @Url-annoteringen, vilket gör det möjligt att skicka endpointen under körning. Rubriker kan anges statiskt via @Headers eller dynamiskt via @Header-parametern. För globala rubriker för alla förfrågningar används en OkHttp-interceptor som lägger till rubriker till varje utgående förfrågan.

Hur fungerar Retrofit?

Retrofit fungerar i tre steg: definiera API-gränssnittet, skapa en Retrofit-instans och utföra förfrågan. Biblioteket genererar implementeringen av gränssnittet under körning baserat på annoteringar och omvandlare.

Livscykel för en förfrågan

När en API-metod anropas skapar Retrofit ett Request-objekt baserat på annoteringar och argument. Förfrågan skickas till OkHttp för exekvering. Efter att svaret tagits emot skickar biblioteket det till Converter.Factory för omvandling till rätt typ. CallAdapter lindar in resultatet i ett asynkront omslag. Varje steg kan anpassas.

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)

Installation och konfiguration av Retrofit

Installation av Retrofit sker via Gradle — Androids standardbyggsystem. Biblioteket distribueras via Maven Central och kräver tillägg av flera beroenden i projektets build.gradle.

Lägga till beroenden

I filen build.gradle (på modulnivå) lägg till beroenden för Retrofit, Gson-omvandlaren och OkHttp. Biblioteksversioner rekommenderas att extraheras till variabler i rotens build.gradle för centraliserad hantering. Retrofit 2 kräver minst 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"
}

Skapa en Retrofit-instans

Retrofit-instansen skapas via Builder. Obligatoriska parametrar: baseUrl och ConverterFactory. Det rekommenderas att använda singleton för Retrofit och OkHttpClient för att undvika att skapa överflödiga anslutningar. Att lägga till en logging-interceptor förenklar felsökning av nätverksförfrågningar under utveckling.

För Kotlin-projekt rekommenderas att använda suspend-funktioner i API-gränssnittet istället för Call-typer. Detta förenklar koden och möjliggör användning av strukturerad samtidighet med korutiner. Vid övergång från Call till suspend räcker det att ändra returtypen i gränssnittet — resten av koden anpassar sig automatiskt.

Exempel på Retrofit-användning

Exempel nedan visar typiska scenarier för arbete med Retrofit i Android-applikationer: från en enkel GET-förfrågan till att ladda upp en fil till servern.

GET-förfrågan med frågeparametrar

En enkel GET-förfrågan med frågeparametrar — grundoperationen. @Query-annoteringen lägger automatiskt till parametrar i URL:en och suspend-funktionen gör det möjligt att anropa förfrågan från en korutin utan att blockera huvudtråden.

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-förfrågan med JSON-kropp

POST-förfrågan med JSON-kropp använder @Body-annoteringen för att skicka objektet. GsonConverterFactory serialiserar automatiskt User-objektet till JSON. Kotlin-korutiner säkerställer att förfrågan utförs i bakgrunden utan Callback-gränssnitt.

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)

Filuppladdning via Multipart

@Multipart-annoteringen med @Part gör det möjligt att ladda upp filer till servern. Retrofit skapar automatiskt en multipart-förfrågan med nödvändiga rubriker. OkHttp hanterar uppladdningsförloppet via RequestBody, vilket gör det möjligt att visa en förloppsindikator för användaren.

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)

Felhantering och interceptors i Retrofit

Felhantering i Retrofit bygger på en kombination av OkHttp-mekanismer och Kotlin-korutiner. OkHttp-interceptors möjliggör loggning av förfrågningar, tillägg av autentiseringsrubriker och hantering av fel innan de når applikationskoden.

För centraliserad felhantering skapas ofta ett omslag runt API-anrop i form av en sealed class Result. En sådan klass innehåller två underklasser: Success med data och Error med undantag. ViewModel får ett enhetligt resultat och kan visa motsvarande tillstånd i användargränssnittet utan att duplicera felhanteringskod i varje funktion.

Interceptors är av två typer: applikationsinterceptors modifierar förfrågan innan den skickas till servern och nätverksinterceptors arbetar med svaret efter mottagning. Till exempel kan en interceptor automatiskt uppdatera access-token vid mottagande av 401 och upprepa förfrågan med den nya token utan utvecklarens inblandning.

Loggning av förfrågningar via Interceptor

Loggningsinterceptor HttpLoggingInterceptor — ett oumbärligt verktyg vid felsökning av nätverksförfrågningar. Den visar i Logcat förfrågans metod, URL, rubriker, kropp och svarskod. Loggningsnivån kan konfigureras: BASIC för minimal information, HEADERS för rubriker eller BODY för fullständigt innehåll. I produktion rekommenderas BASIC eller att helt stänga av loggning.

Interceptors i OkHttp delas in i två typer: applikationsinterceptors för att modifiera förfrågan och nätverksinterceptors för att arbeta med rå nätverksdata. Loggningsinterceptorn visar automatiskt förfråge- och svarsdetaljer i Logcat.

Felhantering på korutinnivå görs via try-catch runt anropet av en suspend-funktion. Retrofit returnerar fel som HttpException för koder 4xx och 5xx, UnknownHostException vid nätverksbrist och SocketTimeoutException vid överskriden timeout. Rekommenderat att använda sealed class Result för enhetlig hantering.