streamalism.org

1. Prehľad

Retrofit je typovo bezpečný klient HTTP pre Android a Java - vyvinutý spoločnosťou Square (Dagger, Okhttp).

V tomto článku vysvetlíme, ako používať Retrofit, so zameraním na jeho najzaujímavejšie funkcie. Predovšetkým si povieme niečo o synchrónnom a asynchrónnom API, ako ho používať s autentifikáciou, protokolovaním a niekoľkými dobrými postupmi modelovania.

2. Príprava príkladu

Začneme pridaním knižnice Retrofit a prevodníka Gson:

 com.squareup.retrofit2 retrofit 2.3.0 com.squareup.retrofit2 converter-gson 2.3.0 

Najnovšie verzie nájdete v časti Retrofit a converter-gson v úložisku Maven Central.

3. Modelovanie API

Retrofit modely REST koncové body ako rozhrania Java, vďaka čomu sú veľmi ľahko pochopiteľné a ľahko použiteľné.

Budeme modelovať užívateľské API z GitHubu; toto má a ZÍSKAJTE koncový bod, ktorý vráti toto vo formáte JSON:

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

Retrofit funguje tak, že sa modeluje na základnej adrese URL a že rozhrania vracajú entity z koncového bodu REST.

Pre zjednodušenie si vezmeme malú časť JSON modelovaním nášho Používateľ trieda, ktorá bude brať hodnoty, keď ich dostaneme:

public class User {private String login; súkromné ​​dlhé ID; súkromná reťazcová adresa URL; // ... // štandardné getre a setre}

Vidíme, že pre tento príklad berieme iba podmnožinu vlastností. Retrofit sa nebude sťažovať na chýbajúce vlastnosti - pretože mapuje iba to, čo potrebujeme, nebude sa ani sťažovať, ak by sme pridali vlastnosti, ktoré nie sú v JSON.

Teraz môžeme prejsť na modelovanie rozhrania a vysvetliť niektoré anotácie Retrofit:

verejné rozhranie UserService {@GET ("/ users") verejná výzva getUsers (@Query ("per_page") int per_page, @Query ("page") int page); @GET ("/ users / {username}") public Call getUser (@Path ("username") String username); }

Metadáta poskytnuté s anotáciami sú dostatočné na to, aby nástroj vytvoril pracovné implementácie.

The @ ZÍSKAŤ anotácia informuje klienta, ktorú metódu HTTP má použiť a na ktorom prostriedku, napríklad zadaním základnej adresy URL „//api.github.com“ odošle žiadosť na adresu „//api.github.com/users“ .

Hlavné „/“ na našej relatívnej adrese URL povie Retrofitu, že ide o absolútnu cestu k hostiteľovi.

Ďalšia vec, ktorú treba poznamenať, je, že používame úplne voliteľné @Dopyt parametre, ktoré je možné odovzdať ako nulové, ak ich nepotrebujeme, sa nástroj postará o ignorovanie týchto parametrov, ak nemajú hodnoty.

A v neposlednom rade, @ Cesta umožníme určiť parameter cesty, ktorý sa umiestni namiesto značky, ktorú sme použili v ceste.

4. Synchrónne / asynchrónne API

Na zostavenie volania žiadosti HTTP je potrebné najskôr vytvoriť náš objekt Retrofit:

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

Retrofit poskytuje pohodlný nástroj na stavbu nášho požadovaného objektu. Potrebuje základnú adresu URL, ktorá sa bude používať pre každé servisné volanie a továreň na prevod - ktorá sa stará o analýzu údajov, ktoré odosielame, a tiež o odpovede, ktoré dostávame.

V tomto príklade použijeme GsonConverterFactory, ktorá bude mapovať naše údaje JSON na Používateľ triedy, ktorú sme definovali skôr.

Je dôležité si uvedomiť, že rôzne továrne slúžia na rôzne účely, takže majte na pamäti, že môžeme tiež použiť továrne na XML, proto-buffery alebo ich dokonca môžeme vytvoriť pre vlastný protokol. Zoznam už implementovaných tovární si môžeme pozrieť tu.

Posledná závislosť je OKHttpClient - čo je klient HTTP a HTTP / 2 pre aplikácie pre Android a Java. Toto sa postará o pripojenie k serveru a o zasielanie a načítanie informácií. Mohli by sme tiež pridať hlavičky a zachytávače pre každý hovor, ktoré uvidíme v našej sekcii overovania.

Teraz, keď máme objekt Retrofit, môžeme vytvoriť naše servisné volanie, poďme sa pozrieť na to, ako to urobiť synchrónnym spôsobom:

Služba UserService = retrofit.create (UserService.class); Volať callSync = service.getUser ("eugenp"); try {Response response = callSync.execute (); Užívateľ užívateľ = response.body (); } úlovok (výnimka okrem) {...}

Tu vidíme, ako sa Retrofit stará o konštrukciu nášho servisného rozhrania vložením kódu potrebného na odoslanie žiadosti na základe našich predchádzajúcich anotácií.

Potom dostaneme a Volaj objekt, ktorý sa používa na vykonanie žiadosti do GitHub API. Najdôležitejšia metóda je tu vykonať, ktorý sa používa na synchrónne uskutočnenie hovoru a pri prenose údajov zablokuje aktuálne vlákno.

Po úspešnom vykonaní hovoru môžeme pomocou nášho načítať telo odpovede - už na objekte používateľa GsonConverterFactory.

Uskutočnenie synchrónneho hovoru je veľmi jednoduché, zvyčajne však používame neblokujúcu asynchrónnu požiadavku:

Služba UserService = retrofit.create (UserService.class); Volať callAsync = service.getUser ("eugenp"); callAsync.enqueue (new Callback () {@Override public void onResponse (Call call, Response response) {User user = response.body ();} @Override public void onFailure (Call call, Throwable throwable) {System.out.println (hoditeľné);}});

Teraz namiesto metódy spustenia použijeme zaradiť do poradia metóda - ktorá trvá a Zavolaj späťrozhranie ako parameter na vybavenie úspechu alebo neúspechu požiadavky. Toto sa vykoná v samostatnom vlákne.

Po úspešnom ukončení hovoru môžeme telo získať rovnakým spôsobom, ako sme to robili predtým.

5. Vytvorenie opakovane použiteľného ServiceGenerator Trieda

Teraz, keď sme videli, ako postaviť náš objekt Retrofit a ako spotrebovať API, vidíme, že nechceme písať staviteľa znova a znova.

To, čo chceme, je opakovane použiteľná trieda, ktorá nám umožňuje vytvoriť tento objekt raz a znovu ho použiť po celú dobu životnosti našej aplikácie:

verejná trieda GitHubServiceGenerator {private static final String BASE_URL = "//api.github.com/"; private static Retrofit.Builder builder = new Retrofit.Builder () .baseUrl (BASE_URL) .addConverterFactory (GsonConverterFactory.create ()); private static Retrofit retrofit = builder.build (); súkromný statický OkHttpClient.Builder httpClient = nový OkHttpClient.Builder (); public static S createService (Class serviceClass) {return retrofit.create (serviceClass); }}

Celá logika vytvárania objektu Retrofit je teraz presunutá do tohto GitHubServiceGenerator triedy, čo z neho robí udržateľnú triedu klienta, ktorá zabráni opakovaniu kódu.

Tu je jednoduchý príklad použitia:

Služba UserService = GitHubServiceGenerator.createService (UserService.class);

Ak by sme napríklad mali vytvoriť a RepositoryService, mohli by sme túto triedu znovu použiť a zjednodušiť vytváranie.

V ďalšej časti, rozšírime ho a pridáme možnosti autentifikácie.

6. Autentifikácia

Väčšina rozhraní API má na zabezpečenie prístupu k nej určité overenie.

Berúc do úvahy našu predchádzajúcu triedu generátorov, pridáme metódu vytvorenia služby, ktorá vezme token JWT s Povolenie hlavička:

public static S createService (Class serviceClass, final String token) {if (token! = null) {httpClient.interceptors (). clear (); httpClient.addInterceptor (chain -> {Request original = chain.request (); Request request = original.newBuilder () .header ("Authorization", token) .build (); return chain.proceed (request);}); builder.client (httpClient.build ()); retrofit = builder.build (); } návrat retrofit.create (serviceClass); }

Ak chcete k našej žiadosti pridať hlavičku, musíme použiť schopnosti zachytávača z OkHttp; robíme to pomocou nášho predtým definovaného staviteľa a rekonštrukciou objektu Retrofit.

Všimnite si, že toto je jednoduchý príklad autentifikácie, ale s použitím zachytávačov môžeme použiť akékoľvek autentifikácie ako OAuth, užívateľ / heslo atď.

7. Protokolovanie

V tejto časti sa chystáme ďalej rozširovať GitHubServiceGenerator pre možnosti protokolovania, ktoré sú veľmi dôležité na účely ladenia v každom projekte.

Využijeme svoje predchádzajúce znalosti o interceptoroch, potrebujeme však ďalšiu závislosť, ktorou je HttpLoggingInterceptor od OkHttp, pridajme to k nášmu pom.xml:

 com.squareup.okhttp3 protokolovací zachytávač 3.9.0 

Teraz si rozšírme našu GitHubServiceGenerator trieda :

verejná trieda GitHubServiceGenerator {private static final String BASE_URL = "//api.github.com/"; private static Retrofit.Builder builder = new Retrofit.Builder () .baseUrl (BASE_URL) .addConverterFactory (GsonConverterFactory.create ()); private static Retrofit retrofit = builder.build (); private static OkHttpClient.Builder httpClient = nový OkHttpClient.Builder (); súkromné ​​statické protokolovanie HttpLoggingInterceptor = nový HttpLoggingInterceptor () .setLevel (HttpLoggingInterceptor.Level.BASIC); public static S createService (Class serviceClass) {if (! httpClient.interceptors (). contains (loging)) {httpClient.addInterceptor (loging); builder.client (httpClient.build ()); retrofit = builder.build (); } návrat retrofit.create (serviceClass); } public static S createService (Class serviceClass, final String token) {if (token! = null) {httpClient.interceptors (). clear (); httpClient.addInterceptor (chain -> {Request original = chain.request (); Request.Builder builder1 = original.newBuilder () .header ("Autorizácia", token); Žiadosť request = builder1.build (); vrátiť chain.proceed (žiadosť);}); builder.client (httpClient.build ()); retrofit = builder.build (); } návrat retrofit.create (serviceClass); }}

Toto je konečná podoba našej triedy, môžeme vidieť, ako sme pridali HttpLoggingInterceptor, a nastavili sme to na základné zaznamenávanie, ktoré bude zaznamenávať čas potrebný na vytvorenie žiadosti, koncový bod, stav každej žiadosti atď.

Je dôležité pozrieť sa na to, ako kontrolujeme, či existuje zachytávač, aby sme ho náhodou nepridali dvakrát.

8. Záver

V tomto rozsiahlom sprievodcovi sme sa pozreli na vynikajúcu knižnicu Retrofit so zameraním na jej Sync / Async API, niektoré osvedčené postupy modelovania, autentifikácie a protokolovania.

Knižnica môže byť použitá veľmi zložitým a užitočným spôsobom; pre prípad pokročilého použitia s RxJava si pozrite tento návod.

A ako vždy, zdrojový kód nájdete na GitHub.