streamalism.org

1. Pregled

U ovom ćemo uputstvu pogledati HTTP knjižnicu goriva, što je, prema autorovim riječima, najlakša HTTP mrežna knjižnica za Kotlin / Android. Nadalje, knjižnica se može koristiti i na Javi.

Glavne značajke knjižnice uključuju:

• Podrška za osnovne HTTP glagole (GET, POST, DELETE, itd.) I asinkrone i zahtjeve za blokiranje
• Mogućnost preuzimanja i prijenosa datoteke (višedijelni / obrasci-podaci)
• Mogućnost upravljanja globalnom konfiguracijom
• Ugrađeni moduli za serializaciju objekata (Jackson, Gson, Mhosi, Forge)
• Podrška za Kotlinov modul suprograma i RxJava 2.x
• Jednostavno postavljanje uzorka dizajna usmjerivača

2. Ovisnosti

Knjižnica se sastoji od različitih modula, tako da lako možemo uključiti značajke koje su nam potrebne. Neki od njih uključuju:

• Modul za podršku RxJava i Kotlin's Coroutines
• Podrška modula za Android i Android LiveData Architecture Components
• Četiri modula od kojih možemo odabrati modul za serializaciju objekata koji ćemo koristiti - Gson, Jackson, Moshi ili Forge.

U ovom uputstvu usredotočit ćemo se na osnovni modul, module za Coroutines, RxJava i Gson modul za serializaciju:

 com.github.kittinunf.fuel gorivo $ {gorivo.verzija} com.github.kittinunf.fuel gorivo-gson $ {gorivo.verzija} com.github.kittinunf.fuel gorivo-rxjava $ {gorivo.verzija} com.github. kittinunf.fuel gorivo-korotaine $ {fuel.version} 

Najnovije verzije možete pronaći na JFrog Bintray.

3. Podnošenje zahtjeva

Da bi podnio zahtjev, gorivo nudi a Niz produženje. Uz to, kao alternativu, možemo koristiti i Gorivo klasa koja ima metodu za svaki HTTP glagol.

Gorivo podržava sve HTTP glagole, osim PATCH-a. Razlog je taj Goriva HttpClient je omot gotov java.net.HttpUrlConnection koji ne podržava PATCH.

Da bi uskočio problem, HttpClient pretvara PATCH zahtjeve u POST zahtjev i dodaje X-HTTP-Overdoid metode: PATCH zaglavlja, pa ćemo morati biti sigurni da su naši API-ji konfigurirani tako da prihvaćaju ovo zaglavlje prema zadanim postavkama.

Kako bismo objasnili značajke goriva, koristit ćemo httpbin.org, jednostavni HTTP zahtjev i uslugu odgovora, i JsonPlaceholder - lažni internetski API za testiranje i izradu prototipova.

3.1. GET Zahtjev

Počnimo stvarati jednostavan HTTP DOBITI zahtjev u async načinu:

"//httpbin.org/get".httpGet().response {zahtjev, odgovor, rezultat -> // rukovanje odgovorom}

Koristeći httpGet () preko Niz daje nam a Utrostručiti.

The Proizlaziti je struktura podataka funkcionalnog stila koja sadrži rezultat operacije (uspjeh ili neuspjeh). Ponovno ćemo posjetiti Proizlaziti struktura podataka u kasnijoj fazi.

Zahtjev možemo poslati i u načinu blokiranja:

val (zahtjev, odgovor, rezultat) = "//httpbin.org/get" .httpGet (). response ()

Imajte na umu da su vraćeni parametri isti kao i async verzija, ali u ovom je slučaju nit koja je poslala zahtjev blokirana.

Također, postoji mogućnost korištenja kodiranih parametara URL-a:

val (zahtjev, odgovor, rezultat) = "//jsonplaceholder.typicode.com/posts" .httpGet (listOf ("userId" do "1")). response () // riješiti //jsonplaceholder.typicode.com/ postova? userId = 1 

The httpGet () metoda (i ostale slične) mogu dobiti a Popis za kodiranje parametara URL-a.

3.2. POST zahtjev

POST zahtjeve možemo poslati na isti način kao i za GET, koristeći httpPost () ili pomoću objaviti () metoda Gorivo razred:

"//httpbin.org/post".httpPost (). response {zahtjev, odgovor, rezultat -> // rukovanje odgovorom}

val (zahtjev, odgovor, rezultat) = Fuel.post ("// httpbin.org/post") .response () 

Ako imamo tijelo, možemo ga provući tijelo() metoda u JSON formatu niza:

val bodyJson = "" "{" title ":" foo "," body ":" bar "," id ":" 1 "}" "" val (zahtjev, odgovor, rezultat) = Fuel.post ("// jsonplaceholder.typicode.com/posts ") .body (bodyJson) .response ()

3.3. Ostali glagoli

Kao i za GET i POST, postoji metoda za svaki od preostalih glagola:

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

Zapamti to Fuel.patch () će izvršiti POST zahtjev saX-HTTP-Nadjačavanje metode: PATCH Zaglavlje.

4. Konfiguracija

Knjižnica isporučuje jednokračni objekt - FuelManager.instance - za upravljanje globalnom konfiguracijom.

Konfigurirajmo osnovni put, neka zaglavlja i uobičajene parametre. Također, konfigurirajmo neke presretače.

4.1. BasePath

Koristeći basePath varijablu možemo postaviti zajednički put za sve zahtjeve.

FuelManager.instance.basePath = "//httpbin.org" val (zahtjev, odgovor, rezultat) = "/get".httpGet (). Response () // izvršit će GET //httpbin.org/get

4.2. Zaglavlja

Nadalje, možemo upravljati uobičajenim HTTP zaglavljima pomoću baseHeaders karta:

FuelManager.instance.baseHeaders = mapOf ("OS" u "Debian")

Na drugi način, ako želimo postaviti lokalno zaglavlje, možemo koristiti Zaglavlje() metoda na zahtjev:

val (zahtjev, odgovor, rezultat) = "/ get" .httpGet () .header (mapOf ("OS" to "Debian")) .response ()

4.3. Parame

Napokon, zajedničke parametre možemo postaviti i pomoću baseParams popis:

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

4.4. Druge opcije

Postoji mnogo više opcija kojima možemo upravljati Upravitelj gorivom:

• pohrana ključeva koji je null prema zadanim postavkama
• socketFactory koje će osigurati korisnik ili će biti izvedene iz pohrana ključeva ako nije null
• hostnameVerifier koja je prema zadanim postavkama postavljena na upotrebu one koju pruža HttpsURLConnection razred
• requestInterceptors i responseInterceptori
• pauza i timeoutRead za zahtjev

4.5. Presretači zahtjeva / odgovora

Što se tiče presretača, možemo dodati isporučene presretače zahtjeva / odgovora poput cUrlLoggingRequestInterceptors (), ili možemo definirati svoje:

FuelManager.instance.addRequestInterceptor (cUrlLoggingRequestInterceptor ()) 

FuelManager.instance.addRequestInterceptor (tokenInterceptor ()) fun tokenInterceptor () = {next: (Zahtjev) -> Zahtjev -> {req: Zahtjev -> req.header (mapOf ("Autorizacija" na "Donositelj AbCdEf123456")) sljedeći ( zahtjev)}}

5. Rukovanje odgovorima

Prethodno smo uveli funkcionalnu strukturu podataka - Proizlaziti - koji predstavlja rezultat operacije (uspjeh ili neuspjeh).

Raditi sa Proizlaziti je lako, to je klasa podataka koja može sadržavati odgovor u ByteArray, String, JSON, ili generički T objekt:

zabavan odgovor (rukovatelj: (Zahtjev, odgovor, rezultat) -> Jedinica) fun responseString (rukovatelj: (Zahtjev, odgovor, rezultat) -> Jedinica) zabavan odgovorJson (voditelj: (Zahtjev, odgovor, rezultat) -> Jedinica) fun responseObject (deserializator: ResponseDeserializable, rukovatelj: (Zahtjev, odgovor, rezultat) -> Jedinica) 

Dobijmo odgovor kao a Niz da to ilustriram:

val (zahtjev, odgovor, rezultat) = Fuel.post ("// httpbin.org/post") .responseString () val (korisni teret, pogreška) = rezultat // korisni teret je niz

Imajte na umu da odgovor u JSON formatu zahtijeva Android ovisnosti.

 com.github.kittinunf.fuel gorivo-android $ {gorivo.verzija} 

6. JSON serializacija / deserijalizacija

Fuel pruža ugrađenu podršku za deserializaciju odgovora pomoću četiri metode koje, ovisno o našim potrebama i odabranoj JSON biblioteci za raščlanjivanje, moramo implementirati:

javna zabava deserializirati (bajtovi: ByteArray): T? javna zabava deserializirati (inputStream: InputStream): T? javna zabava deserializirati (čitatelj: Čitatelj): T? javna zabava deserializirati (sadržaj: String): T?

Uključivanjem Gson modula možemo deserializirati i serializirati objekte:

klasa podataka Post (var userId: Int, var id: Int, var title: String, var body: String) {class Deserializer: ResponseDeserializable {nadjačati zabavu deserializirati (sadržaj: String): Array = Gson (). fromJson (content, Array :: class.java)}}

Objekte možemo deserializirati pomoću prilagođenog deserijalizatora:

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

Ili putem responseObject koji koristi interni Gson deserijalizator:

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

S druge strane, možemo serializirati pomoću Gson (). ToJson ():

val post = Post (1, 1, "Lorem", "Lorem Ipse dolor sit amet") val (zahtjev, odgovor, rezultat) = Fuel.post ("// jsonplaceholder.typicode.com/posts") .header (" Content-Type "to" application / json ") .body (Gson (). ToJson (post) .toString ())

Važno je postaviti Vrsta sadržaja, u suprotnom, poslužitelj može primiti objekt unutar drugog JSON objekta.

Na kraju, na sličan način, to možemo učiniti pomoću ovisnosti Jackson, Moshi ili Forge.

7. Preuzmite i prenesite datoteku

Biblioteka goriva uključuje sve potrebne značajke za preuzimanje i prijenos datoteka.

7.1. preuzimanje datoteka

Uz preuzimanje datoteka() metodom možemo jednostavno preuzeti datoteku i spremiti je u datoteku koju je vratio odredište() lambda:

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

Također možemo preuzeti datoteku s voditeljem napretka:

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

7.2. Učitaj

Na isti način, možemo poslati datoteku pomoću Učitaj() metoda, označavajući datoteku za prijenos s izvor() metoda:

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

Imajte na umu da Učitaj() prema zadanim postavkama koristi glagol POST. Ako želimo koristiti drugi HTTP glagol, možemo ga odrediti:

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

Štoviše, možemo prenijeti više datoteka pomoću izvori () metoda koja prihvaća popis datoteka:

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

I na kraju, možemo prenijeti blob podataka s Ulazni tok:

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

8. Podrška za RxJava i Coroutines

Gorivo pruža podršku za RxJavu i Coroutines, dva načina pisanja asyncrhonusa, neblokirajućeg koda.

RxJava je Java VM implementacija Reactive Extensions, knjižnica za sastavljanje asinkronih programa i programa temeljenih na događajima.

Proširuje obrazac Observer kako bi podržao sekvence podataka / događaja i dodaje operatore koji omogućuju deklarativno sastavljanje sekvenci bez brige o sinkronizaciji, sigurnosti niti i istodobnim strukturama podataka.

Kotlinove koroutine su poput laganih niti i kao takve mogu paralelno trčati, čekati jedni druge i komunicirati ... Najveća je razlika u tome što su koroutine vrlo jeftine; možemo ih stvoriti tisuće i platiti vrlo malo u smislu memorije.

8.1. RxJava

Da bi podržao RxJava 2.x, Fuel nudi šest proširenja:

Zabava Zahtjev.rx_response (): Pojedinačno<>> zabavan zahtjev.rx_responseString (charset: Charset): Single<>> Zabava Zahtjev.rx_responseObject (deserializable: Deserializable): Single<>> zahtjev za zabavu.rx_data (): Pojedinačno Zabava Zahtjev.rx_string (charset: Charset): Pojedinačno Zabava Zahtjev.rx_object (deserializable: Deserializable): Single

Imajte na umu da, za podršku svim različitim vrstama odgovora, svaka metoda vraća različitu Singl.

Lako možemo koristiti metode "Rx" pozivanjem one relevantnije preko a Zahtjev:

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

8.2. Koroutine

S modulom suprograma, Gorivo pruža funkcije produženja za umotavanje odgovora u koroutinu i rukovanje njegovim rezultatom.

Za upotrebu Coroutines-a dostupni su slični API-ji, npr responseString () postao awaitStringResponse ():

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

Također pruža korisne metode za rukovanje objektima koji nisu Niz ili ByteArray (awaitByteArrayResponse ()) koristeći awaitObject (), awaitObjectResult () ili awaitObjectResponse ():

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

Sjetite se da su Kotlinove Coroutines eksperimentalne, što znači da bi se mogle promijeniti u nadolazećim izdanjima.

9. API usmjeravanje

I na kraju, ali ne najmanje važno, za upravljanje mrežnim rutama, Fuel pruža podršku primjenom dizajna dizajna usmjerivača.

Pomoću uzorka usmjerivača možemo centralizirati upravljanje API-jem pomoću Usmjeravanje goriva sučelje, koje pruža kombinaciju metoda za postavljanje odgovarajućeg HTTP glagola, putanje, parametara i zaglavlja prema pozvanoj krajnjoj točki.

Sučelje definira pet svojstava pomoću kojih je moguće konfigurirati naš usmjerivač:

zapečaćena klasa PostRoutingAPI: FuelRouting {postovi klase (val userId: String, nadjačati val body: String?): PostRoutingAPI () komentari klase (val postId: String, override val body: String?): PostRoutingAPI () override val basePath = "/ /jsonplaceholder.typicode.com "override val metoda: Metoda 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"}} nadjačati val params: Lista? get () {return when (this) {is PostRoutingAPI.posts -> listOf ("userId" to this.userId) is PostRoutingAPI.comments -> listOf ("postId" to this.postId)}} nadjačati zaglavlja val: Map? get () {return null}}

Da bismo odabrali koji ćemo HTTP glagol koristiti metoda svojstvo, isto tako, možemo poništiti staza svojstvo, tako da odabere odgovarajući put.

Još više s parametarima svojstvo, imamo priliku postaviti parametre zahtjeva, a ako trebamo postaviti HTTP zaglavlja, možemo to učiniti nadjačavanjem odnosnog svojstva.

Stoga ga koristimo na isti način na koji smo ga koristili u svim tutorijalima s zahtjev() metoda:

Zahtjev za gorivom (PostRoutingAPI.posts ("1", null)) .responseObject (Post.Deserializer ()) {zahtjev, odgovor, rezultat -> // rukovanje odgovorom}

Fuel.request (PostRoutingAPI.comments ("1", null)) .responseString {zahtjev, odgovor, rezultat -> // obrada odgovora}

10. Zaključak

U ovom smo članku prikazali HTTP knjižnicu goriva za Kotlin i njegove korisnije značajke za bilo koji slučaj korištenja.

Knjižnica se neprestano razvija, stoga pogledajte njihov GitHub repo - kako biste pratili nove značajke.

Kao i obično, svi isječci koda spomenuti u vodiču mogu se naći u našem GitHub spremištu.