streamalism.org

1. Uvod

HTTP protokol i API-ji izgrađeni na njemu od centralne su važnosti u programiranju danas.

Na JVM-u imamo nekoliko dostupnih opcija, od knjižnica niže do vrlo visoke razine, od uspostavljenih projekata do nove djece u bloku. Međutim, većina njih usmjerena je prvenstveno na Java programe.

U ovom članku, pogledat ćemo khttp, idiomatsku Kotlinovu knjižnicu za potrošnju resursa temeljenih na HTTP-u i API-ji.

2. Ovisnosti

Da bismo knjižnicu koristili u našem projektu, prvo je moramo dodati u ovisnosti:

 khttp khttp 0.1.0 

Budući da ovo još nije na Maven Central, također moramo omogućiti spremište JCenter:

 središnji //jcenter.bintray.com 

Verzija 0.1.0 trenutačna je u vrijeme pisanja ovog članka. Možemo, naravno, provjeriti JCenter za noviji.

3. Osnovna upotreba

Osnove HTTP protokola su jednostavne, iako fini detalji mogu biti prilično složeni. Stoga i khttp ima jednostavno sučelje.

Za svaku HTTP metodu možemo pronaći funkciju na razini paketa u khttp paket, kao što su dobiti, post i tako dalje.

Sve funkcije uzimaju isti skup argumenata i vraćaju a Odgovor objekt; Pojedinosti o njima vidjet ćemo u sljedećim odjeljcima.

Tijekom ovog članka koristit ćemo potpuno kvalificirani obrazac, na primjer, khttp.put. U našim projektima možemo, naravno, uvoziti i eventualno preimenovati te metode:

uvezi khttp.delete kao httpDelete

Napomena: dodali smo deklaracije tipa radi preglednosti kroz primjere koda jer bez IDE-a moglo bi ih biti teško slijediti.

4. Jednostavan zahtjev

Svaki HTTP zahtjev ima najmanje dvije potrebne komponente: metodu i URL. U khttp-u, metoda se određuje funkcijom koju pozivamo, kao što smo vidjeli u prethodnom odjeljku.

URL je jedini potreban argument za metodu; tako da lako možemo izvršiti jednostavan zahtjev:

khttp.get ("// httpbin.org/get")

U sljedećim odjeljcima razmotrit ćemo sve zahtjeve za uspješno dovršavanje.

4.1. Dodavanje parametara

Često moramo pružiti parametre upita uz osnovni URL, posebno za GET zahtjeve.

khttpove metode prihvaćaju a parametarima argument što je a Karta parova ključ / vrijednost koji će se uključiti u upit Niz:

khttp.get (url = "//httpbin.org/get", params = mapOf ("key1" to "value1", "keyn" to "valuen"))

Primijetite da smo koristili mapOf funkcija za konstrukciju a Karta u letu; rezultirajući URL zahtjeva bit će:

//httpbin.org/get?key1=value1&keyn=valuen

5. Tijelo zahtjeva

Još jedna uobičajena operacija koju često moramo izvesti je slanje podataka, obično kao korisni teret POST ili PUT zahtjeva.

U tu svrhu knjižnica nudi nekoliko mogućnosti koje ćemo ispitati u sljedećim odjeljcima.

5.1. Slanje JSON korisnog tereta

Možemo koristiti json argument za slanje JSON objekta ili niza. Može biti nekoliko različitih vrsta:

• A JSONObject ili JSONArray kako pruža biblioteka org.json
• A Karta, koji se pretvara u JSON objekt
• A Kolekcija, Iterativ ili niz, koji se transformira u JSON niz

Naš raniji GET primjer možemo lako pretvoriti u POST koji će poslati jednostavan JSON objekt:

khttp.post (url = "//httpbin.org/post", json = mapOf ("key1" to "value1", "keyn" to "valuen"))

Imajte na umu da je transformacija iz zbirki u JSON objekte plitka. Na primjer, a Popis od Karta'S se neće pretvoriti u JSON niz JSON objekata, već u niz nizova.

Za dubinsku pretvorbu trebala bi nam složenija JSON-ova biblioteka za mapiranje kao što je Jackson. Objekt za pretvorbu knjižnice namijenjen je samo jednostavnim slučajevima.

5.2. Slanje podataka obrasca (kodiran URL-om)

Za slanje podataka obrazaca (URL kodiran, kao u HTML obrascima) koristimo podaci rasprava s a Karta:

khttp.post (url = "//httpbin.org/post", data = mapOf ("key1" to "value1", "keyn" to "valuen"))

5.3. Učitavanje datoteka (višedijelni obrazac)

Možemo poslati jednu ili više datoteka kodiranih kao zahtjev za podacima iz više dijelova.

U tom slučaju koristimo datoteke argument:

khttp.post (url = "//httpbin.org/post", files = listOf (FileLike ("file1", "content1"), FileLike ("file2", File ("kitty.jpg"))))

Možemo vidjeti da khttp koristi a FileLike apstrakcija, koja je objekt s imenom i sadržajem. Sadržaj može biti niz, niz bajtova, a Datoteka, ili a Staza.

5.4. Slanje sirovog sadržaja

Ako nijedna od gore navedenih opcija nije prikladna, možemo koristiti InputStream za slanje neobrađenih podataka kao tijela HTTP zahtjeva:

khttp.post (url = "//httpbin.org/post", podaci = someInputStream)

U ovom ćemo slučaju najvjerojatnije morati ručno postaviti i neka zaglavlja, što ćemo opisati u kasnijem odjeljku.

6. Rukovanje odgovorom

Do sada smo vidjeli razne načine slanja podataka na poslužitelj. No, mnoge su HTTP operacije korisne i zbog podataka koje vraćaju.

Stoga se khttp temelji na blokiranju I / O-a sve funkcije koje odgovaraju HTTP metodama vraćaju a Odgovor objekt koji sadrži odgovor primljen od poslužitelja.

Ovaj objekt ima različita svojstva kojima možemo pristupiti, ovisno o vrsti sadržaja.

6.1. JSON odgovori

Ako znamo da je odgovor JSON objekt ili niz, možemo koristiti jsonObject i jsonArray Svojstva:

odgovor odgovora: odgovor = khttp.get ("// httpbin.org/get") val obj: JSONObject = response.jsonObject ispis (obj ["someProperty"])

6.2. Tekst ili binarni odgovori

Ako odgovor želimo čitati kao a Niz umjesto toga, možemo koristiti tekst svojstvo:

val poruka: String = response.text

Ili, ako ga želimo čitati kao binarne podatke (npr. Preuzimanje datoteke), koristimo sadržaj svojstvo:

val imageData: ByteArray = response.content

Napokon, možemo pristupiti i temeljnom InputStream:

val inputStream: InputStream = response.raw

7. Napredna upotreba

Pogledajmo i nekoliko naprednijih obrazaca korištenja koji su općenito korisni i koje još nismo obrađivali u prethodnim odjeljcima.

7.1. Rukovanje zaglavljima i kolačićima

Sve funkcije khttp uzimaju a zaglavlja argument što je a Karta imena i vrijednosti zaglavlja.

odgovor odgovora = khttp.get (url = "//httpbin.org/get", zaglavlja = mapOf ("zaglavlje1" do "1", "zaglavlje2" do "2"))

Slično za kolačiće:

odgovor odgovora = khttp.get (url = "//httpbin.org/get", kolačići = mapOf ("cookie1" do "1", "cookie2" do "2"))

Također možemo pristupiti zaglavljima i kolačićima koje je poslao poslužitelj u odgovoru:

val contentType: String = response.headers ["Content-Type"] val sessionID: String = response.cookies ["JSESSIONID"]

7.2. Rukovanje pogreškama

Postoje dvije vrste pogrešaka koje se mogu pojaviti u HTTP-u: odgovori na pogreške, poput 404 - Nije pronađeno, koji su dio protokola; i pogreške niske razine, poput "odbijena veza".

Prva vrsta ne rezultira izuzecima u bacanju khttp-a; umjesto toga, trebali bismo provjeriti Šifra statusa odgovora imovine:

val response = khttp.get (url = "//httpbin.org/nothing/to/see/here") if (response.statusCode == 200) {process (response)} else {handleError (response)}

Umjesto toga, pogreške niže razine rezultiraju izbacivanjem iznimaka iz temeljnog Java I / O podsustava, kao što je ConnectException.

7.3. Streaming odgovori

Ponekad poslužitelj može odgovoriti velikim dijelom sadržaja i / ili treba dugo vremena da odgovori. U tim ćemo slučajevima odgovor možda htjeti obraditi u komadima, umjesto da čekamo da završi i zauzme memoriju.

Ako želimo uputiti knjižnicu da nam odgovori na streaming, onda moramo proći pravi kao potok argument:

odgovor odgovora = khttp.get (url = "//httpbin.org", stream = true)

Zatim ga možemo obraditi u komadima:

response.contentIterator (chunkSize = 1024) .forEach {arr: ByteArray -> handleChunk (arr)}

7.4. Nestandardne metode

U malo vjerojatnom slučaju da trebamo koristiti HTTP metodu (ili glagol) koju khttp ne pruža izvorno - recimo, za neko proširenje HTTP protokola, poput WebDAV-a, i dalje smo pokriveni.

U stvari, sve funkcije u paketu khttp, koje odgovaraju HTTP metodama, implementirane su generički zahtjev funkcija koju i mi možemo koristiti:

khttp.request (method = "COPY", url = "//httpbin.org/get", headers = mapOf ("Odredište" do "/ copy-of-get"))

7.5. Druge značajke

Nismo dotakli sve značajke khttp-a. Na primjer, nismo razgovarali o vremenskim ograničenjima, preusmjeravanjima i povijesti ili asinkronim operacijama.

Službena dokumentacija konačni je izvor informacija o knjižnici i svim njezinim značajkama.

8. Zaključak

U ovom uputstvu vidjeli smo kako izrađivati ​​HTTP zahtjeve u Kotlinu pomoću idiomatske knjižnice khttp.

Provedba svih ovih primjera može se naći u projektu GitHub.