Retrofit: Was es ist, Funktionen des Android HTTP-Clients

Was ist Retrofit?

Retrofit ist eine Bibliothek für die typisierte Interaktion mit REST-APIs auf der Android-Plattform, entwickelt von Square. Sie bietet eine deklarative Möglichkeit, HTTP-Anfragen über Java- oder Kotlin-Interfaces mit Annotationen zu beschreiben und macht manuelles JSON-Parsing und HTTP-Verbindungsverwaltung vollständig überflüssig.

Die Bibliothek erschien 2013 als Alternative zu umständlichen Lösungen wie AsyncTask und HttpURLConnection. Bis 2025 bleibt Retrofit der De-facto-Standard für die Netzwerkkommunikation in Android-Apps dank seiner Einfachheit und Typensicherheit. Laut der JetBrains Developer Ecosystem 2024-Umfrage verwenden über 65% der Android-Entwickler Retrofit in kommerziellen Projekten.

Der Hauptunterschied von Retrofit zu Alternativen ist der deklarative Ansatz: Der Entwickler beschreibt, was zu tun ist (welcher Endpunkt aufgerufen, welche Parameter übergeben werden), nicht wie es zu tun ist (wie eine Verbindung geöffnet, ein InputStream gelesen, JSON geparst wird). Dies reduziert Boilerplate-Code um 60–70% im Vergleich zur manuellen Verwendung von HttpURLConnection.

Wie Retrofit funktioniert

Das Funktionsprinzip von Retrofit basiert auf Java-Dynamic-Proxies. Wenn der Entwickler eine Methode eines annotierten Interfaces aufruft, fängt Retrofit den Aufruf über den Proxy.newProxyInstance-Mechanismus ab und wandelt ihn in eine HTTP-Anfrage um. Der gesamte Prozess läuft zur Laufzeit ohne Codegenerierung zur Kompilierzeit ab.

Beim Erstellen einer Retrofit.Builder-Instanz werden die Basis-URL und die Konverterfabrik angegeben. Der Builder konfiguriert OkHttpClient — setzt Timeouts, Interceptors, Verbindungspool und Cache. Die Methode create(Class) generiert die Implementierung des Interfaces und gibt ein Proxy-Objekt zurück, das wie eine normale Klasse aufgerufen werden kann.

Die Ausführungskette der Anfrage sieht so aus: Annotationen extrahieren die HTTP-Methode, Parameter werden in die URL oder den Anfragetext eingesetzt, der Konverter serialisiert den Text, OkHttp führt die Anfrage aus, der Konverter deserialisiert die Antwort, und das Ergebnis wird im angegebenen Typ zurückgegeben. Jede Stufe ist isoliert und kann durch eine benutzerdefinierte Implementierung ersetzt werden, z.B. OkHttpClient durch MockWebServer für Tests oder Austausch des Konverters bei API-Änderungen.

Eine wichtige Eigenschaft — Retrofit unterstützt keine Streaming-Datenübertragung direkt. Für Streaming wird OkHttp ResponseBody als Rückgabetyp der Interface-Methode verwendet. Retrofit verwaltet auch das Abbrechen von Anfragen nicht automatisch — zum Abbrechen muss ein Verweis auf Call gespeichert und cancel() aufgerufen werden. In Kotlin mit Suspend-Funktionen erfolgt das Abbrechen der Anfrage automatisch, wenn die übergeordnete Koroutine abgebrochen wird.

Lebenszyklus des Call-Objekts

Call<T> ist ein Objekt, das eine einzelne HTTP-Anfrage darstellt. Nach der Ausführung (execute oder enqueue) kann ein Call nicht wiederverwendet werden — für eine wiederholte Anfrage muss ein neues Call durch Aufruf der Interface-Methode erstellt werden. Dies verhindert das versehentliche zweimalige Senden derselben Anfrage, was zu doppelten Operationen auf dem Server führen könnte.

In Kotlin werden anstelle von Call Suspend-Funktionen verwendet, die den Lebenszyklus der Anfrage automatisch verwalten. Retrofit wechselt die Ausführung auf Dispatchers.IO und gibt das Ergebnis an die Koroutine zurück. Dies reduziert den Code um 30–40% im Vergleich zur Version mit Call und Callback.

Retrofit-Annotationen für HTTP-Methoden

Annotationen sind der Hauptmechanismus zur Konfiguration von HTTP-Anfragen in Retrofit. Jede Annotation entspricht einer standardmäßigen HTTP-Methode und akzeptiert einen relativen Pfad zum Endpunkt. Retrofit unterstützt GET, POST, PUT, DELETE, PATCH, HEAD und OPTIONS.

Anfrageparameter-Annotationen

@Path setzt einen Wert in ein URL-Segment ein: @Path("id") Int id ersetzt {id} im Pfad. @Query fügt einen Query-Parameter hinzu: @Query("page") Int page wird zu ?page=5. @Body übergibt ein Objekt im Anfragetext mit automatischer Serialisierung durch den ausgewählten Konverter. @Header und @Headers verwalten HTTP-Header — statisch oder dynamisch.

Durch Kombination dieser Annotationen kann jeder REST-Endpunkt beschrieben werden. Zum Beispiel für den Endpunkt POST /api/users/{id}/posts?limit=10 werden @POST, @Path für id, @Query für limit und @Body für das übergebene Objekt benötigt. Retrofit setzt automatisch eine korrekte HTTP-Anfrage zusammen. Zusätzlich werden @Url (dynamische URL), @Field (formularcodierter Text), @Part und @PartMap für Multipart-Anfragen mit Dateien unterstützt.

Retrofit-Codebeispiele in Kotlin

Betrachten wir ein praktisches Beispiel — ein Interface für die GitHub-API. Ein Kotlin-Interface wird mit einer Methode zum Abrufen der Repositorienliste erstellt. Die Datenklasse Repo beschreibt die JSON-Antwortstruktur.

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>
}

Nach der Beschreibung des Interfaces wird eine Retrofit-Instanz über Builder erstellt. Die Basis-URL, der Konverter und OkHttpClient werden einmal konfiguriert und über Dependency Injection wiederverwendet.

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)

Antwortverarbeitung mit Response-Wrapper

Für eine flexible Behandlung von HTTP-Statuscodes verwenden Sie den Response<T>-Wrapper. Er bietet Zugriff auf Antwortcode, Header und Text, ohne bei 4xx- und 5xx-Fehlern eine Exception auszulösen. Dies ermöglicht die Behandlung von 404 und 500 ohne 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()}")
}

Konverter und Serialisierung in Retrofit

Konverter sind Retrofit-Komponenten, die für die Umwandlung von Objekten in HTTP-Text und zurück verantwortlich sind. Retrofit bettet die Serialisierung nicht in den Kern ein — stattdessen verwendet es einen modularen Ansatz über Converter.Factory, der das Einbinden beliebiger Serialisierungsbibliotheken ermöglicht.

Der beliebteste Konverter ist GsonConverterFactory von Google, basierend auf der Gson-Bibliothek. Er funktioniert für die meisten Projekte, unterstützt benutzerdefinierte TypeAdapter und JsonDeserializer. Allerdings verwendet Gson Reflexion und respektiert Kotlins Nullsicherheit nicht, was bei unerwarteten Null-Feldern zu NPE führen kann.

Eine Alternative ist MoshiConverterFactory von Square: strenger mit Typen, mit besserer Kotlin-Unterstützung (Nullsicherheit, Standardwerte) und ohne Reflexion. Für reine Kotlin-Projekte ist Kotlinx Serialization Converter optimal, der mit @Serializable-Annotationen zur Kompilierzeit arbeitet. Er verwendet keine Reflexion, unterstützt sealed class, Standardwerte und Multiplattform.

Die Wahl des Konverters beeinflusst Leistung und Typensicherheit. Gson kann ohne benutzerdefinierte Konfiguration null in ein nicht-nullbares Kotlin-Feld deserialisieren und beim Zugriff NPE verursachen. Moshi löst dieses Problem durch die @Json(name)-Annotation und failOnUnknown. Kotlinx Serialization ist am sichersten — es generiert Code zur Kompilierzeit und eliminiert Laufzeit-Typfehler vollständig.

Häufige Fehler bei der Arbeit mit Retrofit

Fehlende HTTP-Fehlerbehandlung in Suspend-Funktionen ist das häufigste Problem. Wenn der Server 4xx oder 5xx zurückgibt, wirft Retrofit HttpException. Ohne try-catch stürzt die App ab. Die Verwendung von Response<T> als Rückgabetyp löst dieses Problem, da isSuccessful vor dem Zugriff auf den Body überprüft werden kann.

Falsche Cache-Konfiguration führt zu übermäßigem Traffic. Retrofit speichert Antworten nicht selbst zwischen — diese Aufgabe übernimmt OkHttpClient über Cache. Ohne Cache wird jede Anfrage vollständig ausgeführt, selbst wenn sich die Daten nicht geändert haben. Das Hinzufügen eines 10 MB großen Caches in OkHttpClient reduziert den Traffic bei wiederholten Anfragen derselben Informationen um 40–60%.

Retrofit für jede Anfrage zu erstellen ist ein häufiger Anfängerfehler. Retrofit.Builder ist eine ressourcenintensive Operation, die die Generierung von Proxy-Klassen zur Laufzeit umfasst. Die richtige Praxis ist, eine Retrofit-Instanz zu erstellen und sie über DI-Frameworks wiederzuverwenden. Hilt, Koin oder Dagger stellen eine Singleton-Retrofit-Instanz für die gesamte App bereit, sparen Speicher und beschleunigen Anfragen.

Interceptor für Authentifizierung ignorieren ist das vierte Problem. Statt manuell den Authorization-Header bei jedem Aufruf hinzuzufügen, konfigurieren Sie einen globalen Interceptor in OkHttpClient. Der Interceptor fängt jede Anfrage ab, fügt den Bearer-Token hinzu, und der Authenticator behandelt die 401-Antwort, erneuert den Token und wiederholt die Anfrage automatisch. Dies zentralisiert die Authentifizierungslogik.