Advertisement
  1. Code
  2. Android SDK

Erste Schritte mit Retrofit 2 HTTP-Client

by
Read Time:14 minsLanguages:

German (Deutsch) translation by Federicco Ancie (you can also view the original English article)

Final product imageFinal product imageFinal product image
What You'll Be Creating

Was ist Nachrüstung?

Retrofit ist ein typsicherer HTTP-Client für Android und Java. Retrofit macht es einfach, sich mit einem REST-Webservice zu verbinden, indem die API in Java-Schnittstellen übersetzt wird. In diesem Tutorial zeige ich Ihnen, wie Sie eine der beliebtesten und am häufigsten empfohlenen HTTP-Bibliotheken für Android verwenden.

Diese leistungsstarke Bibliothek macht es einfach, JSON- oder XML-Daten zu konsumieren, die dann in Plain Old Java Objects (POJOs) geparst werden. GET-, POST-, PUT-, PATCH- und DELETE-Anforderungen können alle ausgeführt werden.

Wie die meisten Open-Source-Software wurde Retrofit auf einigen anderen leistungsstarken Bibliotheken und Tools aufgebaut. Hinter den Kulissen verwendet Retrofit OkHttp (vom gleichen Entwickler), um Netzwerkanfragen zu bearbeiten. Außerdem verfügt Retrofit über keinen integrierten JSON-Konverter zum Parsen von JSON- in Java-Objekte. Stattdessen wird die Unterstützung für die folgenden JSON-Konverterbibliotheken bereitgestellt, um dies zu handhaben:

  • Gson: com.squareup.retrofit:converter-gson
  • Jackson: com.squareup.retrofit:converter-jackson
  • Moshi: com.squareup.retrofit:converter-moshi
  • Protobuf: com.squareup.retrofit2:converter-protobuf
  • Wire: com.squareup.retrofit2:converter-wire

Und für XML unterstützt Retrofit:

  • Einfaches Framework: com.squareup.retrofit2:converter-simpleframework

Warum also Retrofit verwenden?

Die Entwicklung einer eigenen typsicheren HTTP-Bibliothek für die Schnittstelle zu einer REST-API kann eine echte Herausforderung sein: Sie müssen viele Funktionen wie Herstellen von Verbindungen, Caching, Wiederholen fehlgeschlagener Anforderungen, Threading, Antwortparsing, Fehlerbehandlung und mehr bewältigen. Retrofit hingegen ist sehr gut geplant, dokumentiert und getestet – eine kampferprobte Bibliothek, die Ihnen viel kostbare Zeit und Kopfschmerzen erspart.

In diesem Tutorial erkläre ich, wie man Retrofit 2 verwendet, um Netzwerkanfragen zu bearbeiten, indem ich eine einfache App erstelle, um aktuelle Antworten von der Stack Exchange API abzufragen. Wir führen GET-Anfragen durch, indem wir einen Endpunkt angeben – /answers, angehängt an die Basis-URL https://api.stackexchange.com/2.2/ –, dann die Ergebnisse abrufen und in einer Recycler-Ansicht anzeigen. Ich zeige Ihnen auch, wie Sie dies mit RxJava tun, um den Status- und Datenfluss einfach zu verwalten.

1. Erstellen Sie ein Android Studio-Projekt

Starten Sie Android Studio und erstellen Sie ein neues Projekt mit einer leeren Aktivität namens MainActivity.

Create a new empty activityCreate a new empty activityCreate a new empty activity

2. Abhängigkeiten erklären

Deklarieren Sie nach dem Erstellen eines neuen Projekts die folgenden Abhängigkeiten in Ihrer build.gradle. Zu den Abhängigkeiten gehören eine Recycler-Ansicht, die Retrofit-Bibliothek sowie die Gson-Bibliothek von Google zur Konvertierung von JSON in POJO (Plain Old Java Objects) sowie die Gson-Integration von Retrofit.

Vergessen Sie nicht, das Projekt zu synchronisieren, um diese Bibliotheken herunterzuladen.

3. Internetberechtigung hinzufügen

Um Netzwerkvorgänge durchzuführen, müssen wir die INTERNET-Berechtigung in das Anwendungsmanifest aufnehmen: AndroidManifest.xml.

4. Modelle automatisch generieren

Wir werden unsere Modelle automatisch aus unseren JSON-Antwortdaten erstellen, indem wir ein sehr nützliches Tool nutzen: jsonschema2pojo.

Holen Sie sich die JSON-Beispieldaten

Kopieren Sie https://api.stackexchange.com/2.2/answers?order=desc&sort=activity&site=stackoverflow und fügen Sie sie in die Adressleiste Ihres Browsers ein (oder Sie können Postman verwenden, wenn Sie mit diesem Tool vertraut sind). Drücken Sie dann die Eingabetaste – dies führt eine GET-Anfrage auf dem angegebenen Endpunkt aus. Als Antwort sehen Sie ein Array von JSON-Objekten. Der Screenshot unten ist die JSON-Antwort mit Postman.

API response to GET requestAPI response to GET requestAPI response to GET request

Kopieren Sie diese JSON-Antwort entweder von Ihrem Browser oder Postman.

Ordnen Sie die JSON-Daten Java zu

Rufen Sie nun jsonschema2pojo auf und fügen Sie die JSON-Antwort in das Eingabefeld ein.

Wählen Sie einen Quelltyp von JSON, einen Anmerkungsstil von Gson und deaktivieren Sie das Kontrollkästchen Zusätzliche Eigenschaften zulassen.

jsonschema2pojo interfacejsonschema2pojo interfacejsonschema2pojo interface

Klicken Sie dann auf die Schaltfläche Vorschau, um die Java-Objekte zu generieren.

jsonschema2pojo outputjsonschema2pojo outputjsonschema2pojo output

Sie fragen sich vielleicht, was die Annotationen @SerializedName und @Expose in diesem generierten Code bewirken. Keine Sorge, ich erkläre alles!

Die Annotation @SerializedName wird benötigt, damit Gson die JSON-Schlüssel unseren Feldern zuordnet. In Übereinstimmung mit der camelCase-Namenskonvention von Java für Klassenmembereigenschaften wird davon abgeraten, Unterstriche zum Trennen von Wörtern in einer Variablen zu verwenden. @SerializedName hilft bei der Übersetzung zwischen den beiden.

Im obigen Beispiel teilen wir Gson mit, dass unser JSON-Schlüssel quota_remaining dem Java-Feld quotaRemaining zugeordnet werden soll. Wenn diese beiden Werte gleich wären, d. h. wenn unser JSON-Schlüssel quotaRemaining genau wie das Java-Feld wäre, dann wäre die Annotation @SerializedName für das Feld nicht erforderlich, da Gson sie automatisch zuordnen würde.

Die Annotation @Expose gibt an, dass dieser Member für die JSON-Serialisierung oder -Deserialisierung verfügbar gemacht werden soll.

Datenmodelle in Android Studio importieren

Kehren wir nun zu Android Studio zurück. Erstellen Sie ein neues Unterpaket innerhalb des Hauptpakets und nennen Sie es data. Erstellen Sie innerhalb des neu erstellten Datenpakets ein weiteres Paket und nennen Sie es model. Erstellen Sie im Modellpaket eine neue Java-Klasse und nennen Sie sie Owner. Kopieren Sie nun die von jsonschema2pojo generierte Owner-Klasse und fügen Sie sie in die von Ihnen erstellte Owner-Klasse ein.

Machen Sie dasselbe für eine neue Item-Klasse, die aus jsonschema2pojo kopiert wurde.

Erstellen Sie schließlich eine Klasse namens SOAnswersResponse für die zurückgegebenen StackOverflow-Antworten. Den Code für diese Klasse finden Sie in jsonschema2pojo als Example. Stellen Sie sicher, dass Sie den Klassennamen überall auf SOAnswersResponse aktualisieren.

5. Erstellen der Retrofit-Instanz

Um mit Retrofit Netzwerkanforderungen an eine REST-API zu senden, müssen wir eine Instanz mit der Retrofit.Builder-Klasse erstellen und sie mit einer Basis-URL konfigurieren.

Erstellen Sie ein neues Unterpaketpaket innerhalb des data-Pakets und nennen Sie es remote. Erstellen Sie nun in remote eine Java-Klasse und nennen Sie sie RetrofitClient. Diese Klasse erstellt ein Singleton von Retrofit. Retrofit benötigt eine Basis-URL, um seine Instanz zu erstellen, daher übergeben wir beim Aufrufen von RetrofitClient.getClient(String baseUrl) eine URL. Diese URL wird dann verwendet, um die Instanz in Zeile 13 zu erstellen. Außerdem geben wir in Zeile 14 den von uns benötigten JSON-Konverter (Gson) an.

6. Erstellen der API-Schnittstelle

Erstellen Sie innerhalb des Remote-Pakets eine Schnittstelle und nennen Sie sie SOService. Diese Schnittstelle enthält Methoden, die wir verwenden werden, um HTTP-Anforderungen wie GET, POST, PUT, PATCH und DELETE auszuführen. Für dieses Tutorial werden wir eine GET-Anfrage ausführen.

Die Annotation @GET definiert explizit die GET-Anforderung, die ausgeführt wird, sobald die Methode aufgerufen wird. Jede Methode in dieser Schnittstelle muss eine HTTP-Annotation haben, die die Anforderungsmethode und die relative URL bereitstellt. Es stehen fünf integrierte Anmerkungen zur Verfügung: @GET, @POST, @PUT, @DELETE und @HEAD.

In der zweiten Methodendefinition haben wir einen Abfrageparameter hinzugefügt, damit wir die Daten vom Server filtern können. Retrofit hat die Annotation @Query("key"), die verwendet wird, anstatt sie im Endpunkt fest zu codieren. Der Schlüsselwert stellt den Parameternamen in der URL dar. Es wird der URL von Retrofit hinzugefügt. Wenn wir beispielsweise den Wert "android" als Argument an die Methode getAnswers(String tags) übergeben, lautet die vollständige URL:

Parameter der Schnittstellenmethoden können folgende Annotationen haben:

@Path Variablensubstitution für den API-Endpunkt
@Query gibt den Abfrageschlüsselnamen mit dem Wert des annotierten Parameters an
@Body Nutzlast für den POST-Aufruf
@Header spezifiziert den Header mit dem Wert des annotierten Parameters

7. Erstellen der API-Utilities

Jetzt erstellen Sie eine Dienstprogrammklasse. Wir nennen es ApiUtils. Diese Klasse hat die Basis-URL als statische Variable und stellt unserer Anwendung über die statische Methode getSOService() auch die SOService-Schnittstelle zur Verfügung.

8. Anzeige auf einem RecyclerView

Da die Ergebnisse in einer Recycler-Ansicht angezeigt werden, benötigen wir einen Adapter. Der folgende Codeausschnitt zeigt die AnswersAdapter-Klasse.

9. Ausführen der Anfrage

Innerhalb der Methode onCreate() der MainActivity initialisieren wir eine Instanz der SOService-Schnittstelle (Zeile 9), die Recycler-Ansicht und auch den Adapter. Schließlich rufen wir die Methode loadAnswers() auf.

Die Methode loadAnswers() stellt eine Netzwerkanfrage, indem sie enqueue() aufruft. Wenn die Antwort zurückkommt, hilft uns Retrofit, die JSON-Antwort auf eine Liste von Java-Objekten zu analysieren. (Dies wird durch die Verwendung von GsonConverter ermöglicht.)

10. enqueue() verstehen

enqueue() sendet die Anfrage asynchron und benachrichtigt Ihre App mit einem Rückruf, wenn eine Antwort zurückkommt. Da diese Anforderung asynchron ist, verarbeitet Retrofit sie in einem Hintergrundthread, damit der Haupt-UI-Thread nicht blockiert oder gestört wird.

Um enqueue() zu verwenden, müssen Sie zwei Callback-Methoden implementieren:

  • onResponse()
  • onFailure()

Als Antwort auf eine bestimmte Anforderung wird nur eine dieser Methoden aufgerufen.

  • onResponse(): wird für eine empfangene HTTP-Antwort aufgerufen. Diese Methode wird für eine Antwort aufgerufen, die auch dann korrekt verarbeitet werden kann, wenn der Server eine Fehlermeldung zurückgibt. Wenn Sie also einen Statuscode von 404 oder 500 erhalten, wird diese Methode trotzdem aufgerufen. Um den Statuscode zu erhalten, damit Sie darauf basierende Situationen handhaben können, können Sie die Methode response.code() verwenden. Sie können auch die Methode isSuccessful() verwenden, um herauszufinden, ob der Statuscode im Bereich von 200 bis 300 liegt und den Erfolg anzeigt.
  • onFailure(): wird aufgerufen, wenn eine Netzwerkausnahme bei der Kommunikation mit dem Server aufgetreten ist oder wenn eine unerwartete Ausnahme bei der Verarbeitung der Anfrage oder der Verarbeitung der Antwort aufgetreten ist.

Um eine synchrone Anfrage auszuführen, können Sie die Methode execute() verwenden. Beachten Sie, dass synchrone Methoden im Haupt-/UI-Thread jede Benutzeraktion blockieren. Führen Sie also keine synchronen Methoden im Haupt-/UI-Thread von Android aus! Führen Sie sie stattdessen in einem Hintergrundthread aus.

11. Testen der App

Sie können die App jetzt ausführen.

Sample results from StackOverflowSample results from StackOverflowSample results from StackOverflow

12. RxJava-Integration

Wenn Sie ein Fan von RxJava sind, können Sie Retrofit mit RxJava problemlos implementieren. In Retrofit 1 war es standardmäßig integriert, aber in Retrofit 2 müssen Sie einige zusätzliche Abhängigkeiten einbeziehen. Retrofit wird mit einem Standardadapter zum Call von Anrufinstanzen geliefert. Sie können also den Ausführungsmechanismus von Retrofit so ändern, dass er RxJava enthält, indem Sie den RxJava CallAdapter einbinden.

Schritt 1

Fügen Sie die Abhängigkeiten hinzu.

Schritt 2

Fügen Sie beim Erstellen einer Retrofit-Instanz den neuen CallAdapter RxJavaCallAdapterFactory.create() hinzu.

Schritt 3

Beim Stellen der Anfragen antwortet unser anonymer Abonnent auf den Stream des Observables, der Ereignisse ausgibt, in unserem Fall SOAnswersResponse. Die onNext-Methode wird dann aufgerufen, wenn unser Abonnent ein ausgegebenes Ereignis empfängt, das dann an unseren Adapter übergeben wird.

Sehen Sie sich Erste Schritte mit ReactiveX auf Android von Ashraff Hathibelagal an, um mehr über RxJava und RxAndroid zu erfahren.

Abschluss

In diesem Tutorial haben Sie Retrofit kennengelernt: warum und wie Sie es verwenden sollten. Ich habe auch erklärt, wie man die RxJava-Integration mit Retrofit hinzufügt. In meinem nächsten Beitrag zeige ich Ihnen, wie Sie POST, PUT und DELETE ausführen, wie Sie Form-Urlencoded Daten senden und wie Sie Anfragen abbrechen.

Weitere Informationen zu Retrofit finden Sie in der offiziellen Dokumentation. Sehen Sie sich in der Zwischenzeit einige unserer anderen Kurse und Tutorials zur Android-App-Entwicklung an.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.