streamalism.org

1. Áttekintés

Az Retrofit egy típusbiztonságos HTTP kliens Androidra és Java-ra - amelyet Square (Dagger, Okhttp) fejlesztett ki.

Ebben a cikkben elmagyarázzuk az Retrofit használatát, különös tekintettel a legérdekesebb szolgáltatásaira. Különösen megvitatjuk a szinkron és aszinkron API-t, hogyan kell használni hitelesítéssel, naplózással és néhány jó modellezési gyakorlattal.

2. A példa beállítása

Először hozzáadjuk a Retrofit könyvtárat és a Gson átalakítót:

 com.squareup.retrofit2 utólagos 2.3.0 com.squareup.retrofit2 átalakító-gson 2.3.0 

A legújabb verziók megtekintéséhez tekintse meg a Maven Central adattár Retrofit és converter-gson oldalait.

3. API modellezés

Az utólagos felszerelés a REST végpontokat Java interfészként modellezi, ami nagyon egyszerűvé teszi azok megértését és fogyasztását.

Modellezzük a felhasználói API-t a GitHub-ból; ennek van egy KAP ezt JSON formátumban visszaadó végpont:

{login: "mojombo", id: 1, url: "//api.github.com/users/mojombo", ...}

Az utólagos felszerelés úgy működik, hogy modellez egy alap URL-t, és azáltal, hogy interfészek adják vissza az entitásokat a REST végpontról.

Az egyszerűség kedvéért a JSON kis részét el fogjuk venni a mi modellezésünkkel Felhasználó osztály, amely akkor veszi az értékeket, amikor megkaptuk őket:

public class Felhasználó {private String login; privát hosszú id; privát karakterlánc URL; // ... // standard szerez egy beállítót}

Láthatjuk, hogy ehhez a példához csak a tulajdonságok egy részhalmazát vesszük. Az utólagos felszerelés nem fog panaszkodni a hiányzó tulajdonságokra - mivel csak azt térképezi fel, amire szükségünk van, nem is lesz panasz, ha olyan tulajdonságokat adunk hozzá, amelyek nincsenek a JSON-ban.

Most áttérhetünk az interfész modellezésére, és elmagyarázhatjuk az Retrofit kommentárok néhányat:

nyilvános felület UserService {@GET ("/ users") nyilvános felhívás getUsers (@Query ("per_page") int per_page, @Query ("page") int oldal); @GET ("/ users / {felhasználónév}") public getUser (@Path ("felhasználónév") karakterlánc felhasználónév); }

A kommentárokkal ellátott metaadatok elegendőek ahhoz, hogy az eszköz működő megvalósításokat generáljon.

A @KAP az annotáció megmondja az ügyfélnek, hogy mely HTTP-módszert és melyik erőforrást használja, így például a „//api.github.com” alap URL-címmel megadja a kérést a „//api.github.com/users” címre .

A vezető „/” a relatív URL-nkon elmondja az Utánépítésnek, hogy ez egy abszolút út a gazdán.

Egy másik dolog, amit meg kell jegyezni, hogy teljesen opcionálisat használunk @Lekérdezés paraméterek, amelyeket nullként adhatunk át, ha nincs szükségünk rájuk, az eszköz gondoskodik ezeknek a paramétereknek a figyelmen kívül hagyásáról, ha nincsenek értékeik.

És végül de nem utolsó sorban, @Pálya megadhatunk egy elérési út paramétert, amelyet az útvonalban használt jelölés helyett helyezünk el.

4. Szinkron / aszinkron API

A HTTP kéréshívás összeállításához először fel kell építenünk az Utánépítés objektumot:

OkHttpClient.Builder httpClient = új OkHttpClient.Builder (); Retrofit retrofit = new Retrofit.Builder () .baseUrl ("// api.github.com/") .addConverterFactory (GsonConverterFactory.create ()) .client (httpClient.build ()) .build ();

Az utólagos felszerelés kényelmes építőt nyújt a szükséges objektum megépítéséhez. Szüksége van az alap URL-re, amelyet minden szervizhíváshoz használni fog, és egy átalakító gyárhoz - amely gondoskodik az általunk küldött adatok elemzéséről és a kapott válaszokról is.

Ebben a példában a GsonConverterFactory, amely a JSON adatainkat a Felhasználó osztály, amelyet korábban definiáltunk.

Fontos megjegyezni, hogy a különböző gyárak különböző célokat szolgálnak, ezért ne feledje, hogy gyárakat is használhatunk XML-hez, proto-pufferekhez, vagy akár létrehozhatunk is egy egyedi protokollhoz. A már megvalósított gyárak listáját itt tekinthetjük meg.

Az utolsó függőség az OKHttpClient - amely HTTP és HTTP / 2 kliens Android és Java alkalmazásokhoz. Ez gondoskodni fog a szerverhez való csatlakozásról, valamint az információk küldéséről és visszakereséséről. Minden híváshoz hozzáadhatunk fejléceket és lehallgatókat is, amelyeket a hitelesítési szakaszunkban látni fogunk.

Most, hogy megvan a Retrofit objektum, elkészíthetjük a szervizhívásunkat, nézzük meg, hogyan lehet ezt szinkron módon megtenni:

UserService szolgáltatás = retrofit.create (UserService.class); Hívja a callSync = service.getUser ("eugenp") parancsot; próbáld meg a {Response response = callSync.execute () -t; Felhasználói felhasználó = response.body (); } fogás (ex kivétel) {...}

Itt láthatjuk, hogy a Retrofit gondoskodik-e szolgáltatási felületünk felépítéséről a korábbi feljegyzések alapján a kérelem benyújtásához szükséges kód beadásával.

Ezt követően kapunk egy Hívás objektum, amelyet a GitHub API kérésének végrehajtására használnak. A legfontosabb módszer itt az végrehajtani, amely egy hívás szinkron végrehajtására szolgál, és az adatok átvitele közben blokkolja az aktuális szálat.

A hívás sikeres végrehajtása után a válasz testét - már egy felhasználói objektumon - lekérhetjük a nekünk GsonConverterFactory.

Szinkron hívás kezdeményezése nagyon egyszerű, de általában nem blokkoló aszinkron kérést használunk:

UserService szolgáltatás = retrofit.create (UserService.class); Hívja a callAsync = service.getUser ("eugenp") parancsot; callAsync.enqueue (új Callback () {@Orride public void onResponse (Call call, Response response) {User user = response.body ();} @Orride public void onFailure (Call call, Throwable dobható) {System.out.println (dobható);}});

Most az execute metódus helyett a enqueue módszer - amely a Visszahívinterfész mint paraméter a kérelem sikerének vagy sikertelenségének kezelésére. Ne feledje, hogy ez külön szálon fog végrehajtani.

Miután a hívás sikeresen befejeződött, a testet ugyanúgy visszakereshetjük, mint korábban.

5. Újrafelhasználható készítés ServiceGenerator Osztály

Most, hogy láttuk, hogyan állítsuk elő a Retrofit objektumunkat és hogyan használjunk API-t, láthatjuk, hogy nem akarjuk tovább és újra írni az építőt.

Egy újrafelhasználható osztályra vágyunk, amely lehetővé teszi számunkra, hogy ezt az objektumot egyszer létrehozzuk és újra felhasználhassuk alkalmazásunk élettartama alatt:

public class GitHubServiceGenerator {private static final String BASE_URL = "//api.github.com/"; privát statikus Retrofit.Builder builder = új Retrofit.Builder () .baseUrl (BASE_URL) .addConverterFactory (GsonConverterFactory.create ()); privát statikus Retrofit utólagos felszerelés = builder.build (); privát statikus OkHttpClient.Builder httpClient = új OkHttpClient.Builder (); public static S createService (Class serviceClass) {return retrofit.create (serviceClass); }}

A Retrofit objektum létrehozásának minden logikája most erre lett áthelyezve GitHubServiceGenerator osztály, ez fenntartható kliens osztálygá teszi, amely megakadályozza a kód megismétlését.

Íme egy egyszerű példa a használatára:

UserService szolgáltatás = GitHubServiceGenerator.createService (UserService.class);

Ha például létrehoznánk a RepositoryService, újra felhasználhatnánk ezt az osztályt, és egyszerűsíthetnénk az alkotást.

A következő részben, kibővítjük és hozzáadunk hitelesítési képességeket.

6. Hitelesítés

A legtöbb API rendelkezik bizonyos hitelesítéssel a hozzáférés biztonságához.

Figyelembe véve az előző generátor osztályunkat, hozzáadunk egy létrehozási szolgáltatási módszert, amely egy JWT tokent vesz fel a Engedélyezés fejléc :

public static S createService (Class serviceClass, final String token) {if (token! = null) {httpClient.interceptors (). clear (); httpClient.addInterceptor (lánc -> {Request original = chain.request (); Request request = original.newBuilder () .header ("Engedélyezés", token) .build (); return chain.proceed (kérelem);}); builder.client (httpClient.build ()); utólagos = építő.építés (); } return retrofit.create (serviceClass); }

Fejléc hozzáadásához kérésünkhöz ki kell használnunk a OkHttp; ezt a korábban definiált készítőnkkel és az Újratervezés objektum rekonstruálásával végezzük.

Vegye figyelembe, hogy ez egy egyszerű hitelesítési példa, de elfogók használatával bármilyen hitelesítést használhatunk, például OAuth-t, felhasználót / jelszót stb.

7. Naplózás

Ebben a szakaszban tovább bővítjük GitHubServiceGenerator naplózási képességekhez, amelyek minden projekt hibakeresési céljai szempontjából nagyon fontosak.

Fel fogjuk használni az elfogókról szóló korábbi ismereteinket, de szükségünk van egy további függőségre, amely az HttpLoggingInterceptor az OkHttp-ről, tegyük hozzá a sajátunkhoz pom.xml:

 com.squareup.okhttp3 naplózó-elfogó 3.9.0 

Most nyújtsuk ki GitHubServiceGenerator osztály :

public class GitHubServiceGenerator {private static final String BASE_URL = "//api.github.com/"; privát statikus Retrofit.Builder builder = új Retrofit.Builder () .baseUrl (BASE_URL) .addConverterFactory (GsonConverterFactory.create ()); privát statikus utólagos felszerelés = építő.építés (); privát statikus OkHttpClient.Builder httpClient = új OkHttpClient.Builder (); privát statikus HttpLoggingInterceptor naplózás = new HttpLoggingInterceptor () .setLevel (HttpLoggingInterceptor.Level.BASIC); public static S createService (Class serviceClass) {if (! httpClient.interceptors (). tartalmaz (naplózást)) {httpClient.addInterceptor (naplózás); builder.client (httpClient.build ()); utólagos felszerelés = builder.build (); } return retrofit.create (serviceClass); } public static S createService (Class serviceClass, final String token) {if (token! = null) {httpClient.interceptors (). clear (); httpClient.addInterceptor (lánc -> {Request original = chain.request (); Request.Builder builder1 = original.newBuilder () .header ("Engedélyezés", token); Request request = builder1.build (); return chain.proceed (kérés); }); builder.client (httpClient.build ()); utólagos felszerelés = builder.build (); } return retrofit.create (serviceClass); }}

Ez az osztályunk utolsó formája, láthatjuk, hogyan adtuk hozzá a HttpLoggingInterceptor, és beállítottuk az alapnaplózáshoz, amely naplózza a kérés elkészítéséhez szükséges időt, a végpontot, minden kérés állapotát stb.

Fontos, hogy megnézzük, hogyan ellenőrizzük, hogy létezik-e elfogó, ezért nem véletlenül adjuk hozzá kétszer.

8. Következtetés

Ebben a kiterjedt útmutatóban megnéztük a kiváló Retrofit könyvtárat, összpontosítva a Sync / Async API-ra, a modellezés, a hitelesítés és a naplózás néhány bevált gyakorlatára.

A könyvtár nagyon összetett és hasznos módon használható; az RxJava speciális használatához kérjük, nézze meg ezt az oktatóanyagot.

És mint mindig, a forráskód megtalálható a GitHubon.