Retrofit — was es ist, HTTP-Bibliothek und Verwendung in Anwendungen

Was ist Retrofit?

Retrofit ist eine Bibliothek zum Ausführen von HTTP-Anfragen in Android-Anwendungen, entwickelt von Square. Sie bietet einen deklarativen Ansatz zur Definition von REST-APIs durch Java-Schnittstellen mit Annotationen, wodurch der Netzwerkinteraktionscode sauber und vorhersagbar wird.

Die Kernidee von Retrofit ist, dass der Entwickler die API als Schnittstelle mit Methoden und Annotationen beschreibt und die Bibliothek automatisch die Implementierung generiert. Dieser Ansatz stellt sicher, dass alle Endpunkte typisiert sind und Fehler in URLs oder Parametern zur Kompilierzeit und nicht zur Laufzeit erkannt werden.

Retrofit unterstützt alle gängigen HTTP-Methoden und Datenformate. Die Bibliothek wird von Square und der Community aktiv gewartet: Neue Versionen erscheinen regelmäßig, und die aktuelle Version 2.11 enthält Unterstützung für Java 17 und Kotlin 2.0. Retrofit bleibt der beliebteste HTTP-Client für Android.

Retrofit arbeitet auf OkHttp — einem effizienten HTTP-Client, ebenfalls von Square. Diese Kombination bietet Caching, Anfrageninterception und Verbindungsverwaltung auf Transportprotokollebene. Die Bibliothek unterstützt sowohl synchrone als auch asynchrone Aufrufe.

Seit der ersten Veröffentlichung im Jahr 2013 hat Retrofit mehrere große Updates durchlaufen. Die aktuelle Version Retrofit 2 wurde basierend auf den Erfahrungen der ersten Version komplett neu geschrieben und bietet ein flexibleres System von Konvertern und Adaptern für Asynchronität.

Die Architektur von Retrofit folgt dem Prinzip der Trennung von Zuständigkeiten: Die Schnittstelle definiert nur den API-Vertrag, Konverter kümmert sich um die Serialisierung und Adapter verwalten die Asynchronität. Dadurch kann jede Komponente ausgetauscht werden, ohne den restlichen Code zu ändern. Beispielsweise kann von Gson zu Moshi gewechselt werden, ohne die Endpunktdefinitionen zu ändern.

Hauptfunktionen von Retrofit

Retrofit bietet eine Reihe von Funktionen, die nahezu alle Netzwerkinteraktionsszenarien in mobilen Anwendungen abdecken. Der Hauptvorteil ist der deklarative Stil der API-Definition.

Deklarative Endpunkt-Annotationen

Annotationen @GET, @POST, @PUT, @PATCH, @DELETE und @HTTP ermöglichen es, die HTTP-Methode und URL-Vorlage direkt in der Schnittstelle anzugeben. Pfadparameter werden über @Path, Abfrageparameter über @Query und der Anforderungskörper über @Body festgelegt. Dieser Ansatz macht die API-Schicht der Anwendung vollständig typisiert.

Konverter für Serialisierung

Konverter wandeln HTTP-Antworten in Java-Objekte um und umgekehrt. Retrofit unterstützt Gson, Moshi, Jackson, Protobuf und Wire. Der Entwickler verbindet den benötigten Konverter über Converter.Factory, und die Bibliothek wendet ihn automatisch auf alle Anfragen und Antworten an.

Adapter für Asynchronität

Adapter CallAdapter ermöglichen es, den Rückgabetyp von API-Methoden zu ändern. Statt des Standard-Call können Observable für RxJava, Deferred für Kotlin-Koroutinen oder LiveData verwendet werden. Dies integriert Netzwerkanfragen in die gewählte Anwendungsarchitektur.

Dynamische URLs und Header

Dynamische URLs werden über @Url-Annotationen festgelegt, wodurch der Endpunkt zur Laufzeit übergeben werden kann. Header können statisch über @Headers oder dynamisch über den @Header-Parameter angegeben werden. Für globale Header aller Anfragen wird ein OkHttp-Interceptor verwendet, der jeder ausgehenden Anfrage Header hinzufügt.

Wie funktioniert Retrofit?

Retrofit arbeitet in drei Phasen: Definieren der API-Schnittstelle, Erstellen einer Retrofit-Instanz und Ausführen der Anfrage. Die Bibliothek generiert die Implementierung der Schnittstelle zur Laufzeit basierend auf Annotationen und Konvertern.

Lebenszyklus einer Anfrage

Wenn eine API-Methode aufgerufen wird, erstellt Retrofit ein Request-Objekt basierend auf den Annotationen und Argumenten. Die Anfrage wird zur Ausführung an OkHttp übergeben. Nach Erhalt der Antwort übergibt die Bibliothek sie an Converter.Factory zur Umwandlung in den erforderlichen Typ. CallAdapter verpackt das Ergebnis in einen asynchronen Wrapper. Jede Phase kann angepasst werden.

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 und Einrichtung von Retrofit

Die Installation von Retrofit erfolgt über Gradle — das Standard-Build-System von Android. Die Bibliothek wird über Maven Central vertrieben und erfordert das Hinzufügen mehrerer Abhängigkeiten in der build.gradle des Projekts.

Abhängigkeiten hinzufügen

In der build.gradle-Datei (Modulebene) fügen Sie Abhängigkeiten für Retrofit, Gson-Konverter und OkHttp hinzu. Es wird empfohlen, die Bibliotheksversionen in der root build.gradle in Variablen auszulagern. Retrofit 2 erfordert mindestens 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"
}

Eine Retrofit-Instanz erstellen

Eine Retrofit-Instanz wird über Builder erstellt. Erforderliche Parameter: baseUrl und ConverterFactory. Es wird empfohlen, ein Singleton für Retrofit und OkHttpClient zu verwenden, um redundante Verbindungen zu vermeiden. Das Hinzufügen eines logging-Interceptors vereinfacht das Debuggen von Netzwerkanfragen während der Entwicklung.

Für Kotlin-Projekte wird empfohlen, in der API-Schnittstelle suspend-Funktionen anstelle von Call-Typen zu verwenden. Dies vereinfacht den Code und ermöglicht die Nutzung der strukturierten Nebenläufigkeit von Koroutinen. Beim Wechsel von Call zu suspend muss nur der Rückgabetyp in der Schnittstelle geändert werden — der restliche Code passt sich automatisch an.

Beispiele zur Verwendung von Retrofit

Die folgenden Beispiele zeigen typische Szenarien der Arbeit mit Retrofit in Android-Anwendungen: von einer einfachen GET-Anfrage bis zum Hochladen einer Datei auf den Server.

GET-Anfrage mit Abfrageparametern

Eine einfache GET-Anfrage mit Abfragezeichenfolgenparametern ist eine grundlegende Operation. Die @Query-Annotation fügt Parameter automatisch zur URL hinzu, und die suspend-Funktion ermöglicht es, die Anfrage aus einer Koroutine heraus aufzurufen, ohne den Hauptthread zu blockieren.

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-Anfrage mit JSON-Körper

Eine POST-Anfrage mit JSON-Körper verwendet die @Body-Annotation, um das Objekt zu übergeben. GsonConverterFactory serialisiert das User-Objekt automatisch in JSON. Kotlin-Koroutinen gewährleisten die Ausführung der Anfrage im Hintergrundthread ohne Callback-Schnittstellen.

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

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

Datei-Upload per Multipart

Die @Multipart-Annotation mit @Part ermöglicht das Hochladen von Dateien auf den Server. Retrofit bildet automatisch eine Multipart-Anfrage mit den erforderlichen Headern. OkHttp verwaltet den Upload-Fortschritt über RequestBody, sodass dem Benutzer ein Indikator angezeigt werden kann.

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)

Fehlerbehandlung und Interceptor in Retrofit

Die Fehlerbehandlung in Retrofit basiert auf einer Kombination von OkHttp-Mechanismen und Kotlin-Koroutinen. OkHttp-Interceptor ermöglichen das Protokollieren von Anfragen, das Hinzufügen von Authentifizierungs-Headern und das Behandeln von Fehlern, bevor sie den Anwendungscode erreichen.

Für die zentrale Fehlerbehandlung wird oft ein Wrapper um API-Aufrufe als sealed class Result erstellt. Eine solche Klasse hat zwei Unterklassen: Success mit Daten und Error mit einer Ausnahme. Das ViewModel erhält ein einheitliches Ergebnis und kann den entsprechenden Benutzeroberflächenstatus anzeigen, ohne den Fehlerbehandlungscode in jeder Funktion zu duplizieren.

Interceptor gibt es in zwei Typen: Anwendungs-Interceptor ändern die Anfrage vor dem Senden an den Server, und Netzwerk-Interceptor arbeiten mit der Antwort nach dem Empfang. Beispielsweise kann ein Interceptor beim Erhalt eines 401 automatisch das Zugriffstoken aktualisieren und die Anfrage mit dem neuen Token ohne Entwicklereingriff wiederholen.

Protokollierung von Anfragen über Interceptor

Der Logging-Interceptor HttpLoggingInterceptor ist ein unverzichtbares Werkzeug zum Debuggen von Netzwerkanfragen. Er gibt die Anfragemethode, URL, Header, Body und Antwortcode in Logcat aus. Der Protokollierungsgrad kann konfiguriert werden: BASIC für minimale Informationen, HEADERS für Header oder BODY für vollständigen Inhalt. In der Produktion wird empfohlen, BASIC zu verwenden oder die Protokollierung ganz zu deaktivieren.

Interceptor in OkHttp werden in zwei Typen unterteilt: Anwendungs-Interceptor zum Ändern der Anfrage und Netzwerk-Interceptor zum Arbeiten mit rohen Netzwerkdaten. Der Logging-Interceptor gibt automatisch Anfrage- und Antwortdetails in Logcat aus.

Die Fehlerbehandlung auf Koroutine-Ebene erfolgt über try-catch um den suspend-Funktionsaufruf. Retrofit gibt Fehler als HttpException für 4xx- und 5xx-Codes, UnknownHostException bei fehlendem Netzwerk und SocketTimeoutException bei Überschreitung des Timeouts zurück. Es wird empfohlen, eine sealed class Result für die einheitliche Behandlung zu verwenden.