Palivová HTTP knižnica s Kotlinom

1. Prehľad

V tomto výučbe sa pozrieme na knižnicu Fuel HTTP Library, čo je podľa slov autora najjednoduchšia sieťová knižnica HTTP pre Kotlin / Android. Knižnicu je možné ďalej používať aj v prostredí Java.

Medzi hlavné vlastnosti knižnice patria:

  • Podpora pre základné slovesá HTTP (GET, POST, DELETE atď.), Asynchrónne aj blokujúce
  • Schopnosť stiahnuť a nahrať súbor (multipart / form-data)
  • Možnosť spravovať globálnu konfiguráciu
  • Vstavané moduly serializácie objektov (Jackson, Gson, Mhosi, Forge)
  • Podpora pre modul Kotlin's coroutines a RxJava 2.x
  • Ľahko nastavíte návrhový vzor smerovača

2. Závislosti

Knižnica sa skladá z rôznych modulov, takže môžeme ľahko zahrnúť funkcie, ktoré potrebujeme. Niektoré z nich zahŕňajú:

  • Modul pre podporu RxJava a Kotlin's Coroutines
  • Modul pre podporu architektúry Android a Android LiveData
  • Štyri moduly, z ktorých si môžeme vybrať modul na serializáciu objektov, ktorý použijeme - Gson, Jackson, Moshi alebo Forge.

V tomto tutoriáli sa zameriame na hlavný modul, moduly pre Coroutines, RxJava a modul serializácie Gson:

 com.github.kittinunf.fuel fuel $ {fuel.version} com.github.kittinunf.fuel fuel-gson $ {fuel.version} com.github.kittinunf.fuel fuel-rxjava $ {fuel.version} com.github. kittinunf.fuel fuel-coroutines $ {fuel.version}

Najnovšie verzie nájdete na serveri JFrog Bintray.

3. Podávanie žiadostí

Na požiadanie spoločnosť Fuel poskytuje a String predĺženie. Okrem toho a ako alternatívu môžeme použiť Palivo trieda, ktorá má metódu pre každé sloveso HTTP.

Fuel podporuje všetky slovesá HTTP okrem PATCH. Dôvod je ten Palivo HttpClient je obal nad java.net.HttpUrlConnection ktorý nepodporuje PATCH.

Na pomoc pri riešení problému prevádza HttpClient požiadavky PATCH na požiadavku POST a pridá znak Prepísanie metódy X-HTTP: PATCH hlavičku, takže sa budeme musieť ubezpečiť, že naše API sú nakonfigurované tak, aby túto hlavičku štandardne akceptovali.

Aby sme vysvetlili funkcie Fuel, použijeme httpbin.org, jednoduchú službu HTTP request and response, a JsonPlaceholder - falošné online API pre testovanie a prototypovanie.

3.1. ZÍSKAJTE žiadosť

Začnime vytvárať jednoduchý protokol HTTP ZÍSKAJTE požiadavka v asynchronnom režime:

"//httpbin.org/get".httpGet().response {požiadavka, odpoveď, výsledok -> // spracovanie odpovede}

Použitím httpGet () cez String dáva nám Triple.

The Výsledok je dátová štruktúra vo funkčnom štýle, ktorá obsahuje výsledok operácie (úspech alebo neúspech). Znova sa vrátime Výsledok v neskoršej fáze.

Žiadosť môžeme podať aj v režime blokovania:

val (požiadavka, odpoveď, výsledok) = "//httpbin.org/get" .httpGet (). response ()

Upozorňujeme, že vrátené parametre sú rovnaké ako asynchronná verzia, ale v tomto prípade je vlákno, ktoré zadalo požiadavku, blokované.

Existuje tiež možnosť použiť kódované parametre adries URL:

val (požiadavka, odpoveď, výsledok) = "//jsonplaceholder.typicode.com/posts" .httpGet (listOf ("userId" až "1")). response () // riešenie //jsonplaceholder.typicode.com/ príspevky? userId = 1

The httpGet () metóda (a ďalšie podobné) môžu prijímať a Zoznam na kódovanie parametrov URL.

3.2. POST požiadavka

Požiadavky POST môžeme zadávať rovnakým spôsobom ako pri použití GET httpPost () alebo pomocou príspevok () metóda Palivo trieda:

"//httpbin.org/post".httpPost (). response {request, response, result -> // response handling}
val (požiadavka, odpoveď, výsledok) = Fuel.post ("// httpbin.org/post") .response ()

Ak máme telo, môžeme si ho prebrať telo () metóda vo formáte reťazca JSON:

val bodyJson = "" "{" title ":" foo "," body ":" bar "," id ":" 1 "}" "" val (požiadavka, odpoveď, výsledok) = Fuel.post ("// jsonplaceholder.typicode.com/posts ") .body (bodyJson) .response ()

3.3. Ostatné slovesá

Rovnako ako pre GET a POST existuje metóda pre každé zo zvyšných slovies:

Fuel.put ("// httpbin.org/put") Fuel.delete ("// httpbin.org/delete") Fuel.head ("// httpbin.org/get") Fuel.patch ("// httpbin .org / patch ")

Zapamätaj si to Fuel.patch () vykoná požiadavku POST s aPrepísanie metódy X-HTTP: PATCH hlavička.

4. Konfigurácia

Knižnica dodáva jediný objekt - Inštancia FuelManager - spravovať globálnu konfiguráciu.

Nakonfigurujme základnú cestu, nejaké hlavičky a bežné parametre. Konfigurujme tiež niektoré zachytávače.

4.1. BasePath

Použitím basePath premennú môžeme nastaviť spoločnú cestu pre všetky požiadavky.

FuelManager.instance.basePath = "//httpbin.org" val (požiadavka, odpoveď, výsledok) = "/get".httpGet (). Response () // vykoná GET //httpbin.org/get

4.2. Hlavičky

Ďalej môžeme spravovať bežné HTTP hlavičky pomocou záhlavia základne mapa:

FuelManager.instance.baseHeaders = mapOf ("OS" až "Debian")

Alternatívne, ak chceme nastaviť lokálnu hlavičku, môžeme použiť znak hlavička () metóda na požiadanie:

val (požiadavka, odpoveď, výsledok) = "/ dostať" .httpGet () .header (mapOf ("OS" na "Debian")) .response ()

4.3. Params

Nakoniec môžeme tiež nastaviť bežné parametre pomocou baseParams zoznam:

FuelManager.instance.baseParams = listOf ("foo" na "bar")

4.4. Ďalšie možnosti

Existuje oveľa viac možností, cez ktoré môžeme spravovať FuelManager:

  • sklad kľúčov ktorý je nulový predvolene
  • socketFactory ktoré poskytne používateľ alebo sa z nich odvodí sklad kľúčov ak nie je nulový
  • hostnameVerifier ktorá je predvolene nastavená na použitie tej, ktorú poskytuje HttpsURLConnection trieda
  • requestInterceptory a responseInterceptory
  • čas vypršal a časový limit na požiadanie

4.5. Zachytávače požiadavky / odpovede

Pokiaľ ide o zachytávače, môžeme pridať dodané zachytávače požiadaviek / odpovedí ako cUrlLoggingRequestInterceptors (), alebo môžeme definovať ten náš:

FuelManager.instance.addRequestInterceptor (cUrlLoggingRequestInterceptor ()) 
FuelManager.instance.addRequestInterceptor (tokenInterceptor ()) fun tokenInterceptor () = {next: (Request) -> Request -> {req: Request -> req.header (mapOf ("Authorization" to "Bearer AbCdEf123456")) next ( požiadavka)}}

5. Spracovanie odpovedí

Predtým sme zaviedli funkčnú dátovú štruktúru - Výsledok - ktorý predstavuje výsledok operácie (úspech alebo neúspech).

Pracujúci s Výsledok je ľahké, je to dátová trieda, ktorá môže obsahovať odpoveď v ByteArray, Reťazec, JSON, alebo generikum T objekt:

fun response (handler: (Request, Response, Result) -> Unit) fun responseString (handler: (Request, Response, Result) -> Unit) fun responseJson (handler: (Request, Response, Result) -> Unit) fun responseObject (deserializátor: ResponseDeserializable, obslužný program: (požiadavka, odpoveď, výsledok) -> jednotka)

Poďme dostať odpoveď ako a String na ilustráciu:

val (požiadavka, odpoveď, výsledok) = Fuel.post ("// httpbin.org/post") .responseString () val (užitočné zaťaženie, chyba) = výsledok // užitočné zaťaženie je reťazec

Upozorňujeme, že odpoveď vo formáte JSON vyžaduje závislosti od systému Android.

 com.github.kittinunf.fuel fuel-android $ {fuel.version}

6. JSON serializácia / deserializácia

Fuel poskytuje zabudovanú podporu pre deserializáciu odpovedí štyrmi metódami, ktoré v závislosti na našich potrebách a na knižnici analýzy JSON, ktorú si vyberieme, musíme implementovať:

verejná zábava deserializovať (bajty: ByteArray): T? verejná zábava deserializovať (inputStream: InputStream): T? verejná zábava deserializovať (čitateľ: čitateľ): T? verejná zábava deserializovať (obsah: Reťazec): T?

Zahrnutím modulu Gson môžeme deserializovať a serializovať objekty:

dátová trieda Post (var userId: Int, var id: Int, var title: String, var body: String) {class Deserializer: ResponseDeserializable {override fun deserialize (content: String): Array = Gson (). fromJson (content, Array :: class.java)}}

Objekty môžeme deserializovať pomocou vlastného deserializátora:

„//jsonplaceholder.typicode.com/posts“ .httpGet (). responseObject (Post.Deserializer ()) {_, _, result -> val postsArray = result.component1 ()}

Alebo pomocou responseObject, ktorý používa interný Gson deserializer:

"//jsonplaceholder.typicode.com/posts/1" .httpGet (). responseObject {_, _, result -> val post = result.component1 ()}

Na druhej strane môžeme serializovať pomocou Gson (). ToJson ():

val post = Post (1, 1, "Lorem", "Lorem Ipse dolor sit amet") val (požiadavka, odpoveď, výsledok) = Fuel.post ("// jsonplaceholder.typicode.com/posts") .header (" Typ obsahu „do“ aplikácie / json „) .body (Gson (). ToJson (príspevok) .toString ())

Je dôležité nastaviť Druh obsahu, inak môže server prijať objekt v rámci iného objektu JSON.

Nakoniec to podobným spôsobom môžeme urobiť pomocou závislostí Jackson, Moshi alebo Forge.

7. Stiahnite a nahrajte súbor

Knižnica Fuel obsahuje všetky potrebné funkcie na sťahovanie a nahrávanie súborov.

7.1. Stiahnuť ▼

Vďaka Stiahnuť ▼() metódou môžeme ľahko stiahnuť súbor a uložiť ho do súboru vráteného destinácia() lambda:

Fuel.download ("// httpbin.org/bytes/32768") .destination {response, url -> File.createTempFile ("temp", ".tmp")}

Môžeme tiež stiahnuť súbor s obslužnou rutinou postupu:

Fuel.download ("// httpbin.org/bytes/327680") .progress {readBytes, totalBytes -> val progress = readBytes.toFloat () / totalBytes.toFloat () // ...}

7.2. Nahrať

Rovnakym sposobom, môžeme nahrať súbor pomocou nahrať () metóda, označujúci súbor na nahranie pomocou zdroj () metóda:

Fuel.upload ("/ upload"). Source {request, url -> File.createTempFile ("temp", ".tmp")}

Poznač si to nahrať () predvolene používa sloveso POST. Ak chceme použiť iné sloveso HTTP, môžeme ho určiť:

Fuel.upload ("/ upload", Method.PUT) .source {request, url -> File.createTempFile ("temp", ".tmp")}

Okrem toho môžeme nahrať viac súborov pomocou zdroje () metóda, ktorá akceptuje zoznam súborov:

Fuel.upload ("/ post"). Sources {request, url -> listOf (File.createTempFile ("temp1", ".tmp"), File.createTempFile ("temp2", ".tmp"))}

Na záver môžeme nahrať blob dát z InputStream:

Fuel.upload ("/ post"). Blob {request, url -> Blob ("nazov.png", someObject.length, {someObject.getInputStream ()})}

8. Podpora RxJava a Coroutines

Fuel poskytuje podporu pre RxJava a Coroutines, dva spôsoby zápisu asyncrhonus, neblokujúci kód.

RxJava je implementácia Java VM pre Reactive Extensions, knižnicu pre tvorbu asynchrónnych programov a programov založených na udalostiach.

Rozširuje vzor Observer o podporu sekvencií údajov / udalostí a pridáva operátory, ktoré umožňujú deklaratívne skladanie sekvencií dohromady bez obáv o synchronizáciu, bezpečnosť vlákien a súčasné dátové štruktúry.

Kotlinove Coroutines sú ako ľahké vlákna a ako také môžu bežať paralelne, čakať na seba a komunikovať ... Najväčší rozdiel je v tom, že coututiny sú veľmi lacné; môžeme ich vytvoriť tisíce a zaplatiť veľmi málo za pamäť.

8.1. RxJava

Na podporu RxJava 2.x poskytuje Fuel šesť rozšírení:

zábava Request.rx_response (): slobodná<>> fun Request.rx_responseString (charset: Charset): Jeden<>> fun Request.rx_responseObject (deserializable: Deserializable): Single<>> fun Request.rx_data (): slobodný fun Request.rx_string (charset: Charset): Jeden zábava Request.rx_object (deserializable: Deserializable): slobodný

Upozorňujeme, že na podporu všetkých rôznych typov odpovedí vráti každá metóda iný Slobodný.

Metódy „Rx“ môžeme ľahko použiť tak, že vyvoláme tú relevantnejšiu z a Žiadosť:

 "//jsonplaceholder.typicode.com/posts?id=1" .httpGet (). rx_object (Post.Deserializer ()). subscribe {res, throwable -> val post = res.component1 ()}

8.2. Korutíny

S modulom coroutines, Palivo poskytuje rozširovacie funkcie na zabalenie odozvy do procesu a na zvládnutie jeho výsledku.

Pre použitie Coroutines sú k dispozícii podobné API, napr responseString () sa stal awaitStringResponse ():

runBlocking {Fuel.get ("// httpbin.org/get"). awaitStringResponse ()}

Poskytuje tiež užitočné metódy na zaobchádzanie s inými objektmi ako String alebo ByteArray (awaitByteArrayResponse ()) použitím awaitObject (), awaitObjectResult () alebo awaitObjectResponse ():

runBlocking {Fuel.get ("// jsonplaceholder.typicode.com/posts?id=1") .awaitObjectResult (Post.Deserializer ())}

Pamätajte, že Kotlinove Coroutiny sú experimentálne, čo znamená, že sa to v nasledujúcich vydaniach môže zmeniť.

9. Smerovanie API

V neposlednom rade, kvôli spracovaniu sieťových trás, poskytuje Fuel podporu implementáciou návrhového vzoru smerovača.

So vzorom smerovača môžeme centralizovať správu API pomocou FuelRouting rozhranie, ktoré poskytuje kombináciu metód pre nastavenie príslušného HTTP slovesa, cesty, parametrov a hlavičiek podľa volaného koncového bodu.

Rozhranie definuje päť vlastností, pomocou ktorých je možné nakonfigurovať náš smerovač:

zapečatená trieda PostRoutingAPI: FuelRouting {príspevky triedy (val userId: String, prepísať telo valca: String?): Komentáre k triede PostRoutingAPI () (val postId: String, prepísať telo valca: String?): PostRoutingAPI () prepísať val basePath = "/ /jsonplaceholder.typicode.com "override val method: Method get () {return when (this) {is PostRoutingAPI.posts -> Method.GET is PostRoutingAPI.comments -> Method.GET}} override val path: String get () {return when (this) {is PostRoutingAPI.posts -> "/ posts" is PostRoutingAPI.comments -> "/ comments"}} prepísať parametre val: Zoznam? get () {return when (this) {is PostRoutingAPI.posts -> listOf ("userId" to this.userId) is PostRoutingAPI.comments -> listOf ("postId" to this.postId)}} override val headers: Map? get () {return null}}

Aby sme si mohli zvoliť, ktoré sloveso HTTP použiť, máme metóda rovnako môžeme prepísať cesta majetku, aby ste si vybrali vhodnú cestu.

Ešte viac s params vlastnosť, máme možnosť nastaviť parametre požiadavky a ak potrebujeme nastaviť hlavičky HTTP, môžeme to urobiť prepísaním príslušnej vlastnosti.

Preto ho používame rovnakým spôsobom, aký sme mali v celom výučbe s programom požiadavka () metóda:

Fuel.request (PostRoutingAPI.posts ("1", null)) .responseObject (Post.Deserializer ()) {požiadavka, odpoveď, výsledok -> // spracovanie odpovede}
Fuel.request (PostRoutingAPI.comments ("1", null)) .responseString {požiadavka, odpoveď, výsledok -> // spracovanie odpovede}

10. Záver

V tomto článku sme si ukázali knižnicu Fuel HTTP Library pre Kotlin a jej užitočnejšie funkcie pre akýkoľvek prípad použitia.

Knižnica sa neustále vyvíja, preto si pozrite svoje repozitár GitHub - sledujte nové funkcie.

Ako obvykle, všetky útržky kódu uvedené v tejto príručke nájdete v našom úložisku GitHub.


Populárne Príspevky

Posledné príspevky

Copyright sk.streamalism.org 2024
$config[zx-auto] not found$config[zx-overlay] not found