streamalism.org

1. Úvod

Protokol HTTP a na ňom postavené API majú v dnešnej dobe pri programovaní ústredný význam.

Na JVM máme niekoľko dostupných možností, od knižníc na nižšej až po veľmi vysokú úroveň, od zavedených projektov po nové deti v rade. Väčšina z nich je však zameraná predovšetkým na programy Java.

V tomto článku ideme sa pozrieť na khttp, idiomatickú knižnicu Kotlin na konzumáciu zdrojov založených na protokole HTTP a API.

2. Závislosti

Aby sme mohli knižnicu používať v našom projekte, najskôr si ju musíme pridať do našich závislostí:

 khttp khttp 0.1.0 

Pretože to ešte nie je na Maven Central, musíme povoliť aj úložisko JCenter:

 central //jcenter.bintray.com 

Verzia 0.1.0 je aktuálna v čase písania článku. Môžeme samozrejme skontrolovať, či je v JCenter novší.

3. Základné použitie

Základy protokolu HTTP sú jednoduché, aj keď jemné podrobnosti môžu byť dosť komplikované. Preto má khttp tiež jednoduché rozhranie.

Pre každú metódu HTTP nájdeme v balíku funkciu na úrovni balíka khttp balíček, ako napr dostať, príspevok a tak ďalej.

Všetky funkcie majú rovnakú sadu argumentov a vracajú a Odozva predmet; ich podrobnosti uvidíme v nasledujúcich častiach.

V priebehu tohto článku použijeme plne kvalifikovaný formulár, napríklad khttp.put. V našich projektoch môžeme tieto metódy samozrejme importovať a prípadne premenovať:

importovať khttp.delete ako httpDelete

Poznámka: Do príkladov kódu sme kvôli prehľadnosti pridali deklarácie typov pretože bez IDE by sa dali ťažko sledovať.

4. Jednoduchá požiadavka

Každá požiadavka HTTP má najmenej dve povinné komponenty: metódu a adresu URL. V khttp je metóda určená funkciou, ktorú vyvoláme, ako sme videli v predchádzajúcej časti.

URL je jediný požadovaný argument pre metódu; takže môžeme ľahko vykonať jednoduchú požiadavku:

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

V nasledujúcich častiach zvážime všetky žiadosti o úspešné dokončenie.

4.1. Pridávanie parametrov

Okrem základnej adresy URL musíme často poskytovať aj parametre dotazu, najmä pre požiadavky GET.

khttpove metódy akceptujú a params argument čo je a Mapa párov kľúč - hodnota, ktoré sa majú zahrnúť do dotazu Reťazec:

khttp.get (url = "//httpbin.org/get", params = mapOf ("kľúč1" až "hodnota1", "keyn" až "valuen"))

Všimnite si, že sme použili mapOf funkcia na zostrojenie a Mapa za chodu; výsledná adresa URL žiadosti bude:

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

5. Žiadajúci orgán

Ďalšou bežnou operáciou, ktorú často musíme vykonať, je odosielanie údajov, zvyčajne ako užitočné zaťaženie požiadavky POST alebo PUT.

Knižnica ponúka niekoľko možností, ktoré preskúmame v nasledujúcich častiach.

5.1. Posiela sa užitočné zaťaženie JSON

Môžeme použiť json argument na odoslanie objektu alebo poľa JSON. Môže to byť niekoľko rôznych typov:

• A JSONObject alebo JSONArray ako poskytuje knižnica org.json
• A Mapa, ktorý sa transformuje na objekt JSON
• A Zbierka, Iterable alebo pole, ktoré sa transformuje na pole JSON

Náš predchádzajúci príklad GET môžeme ľahko zmeniť na POST, ktorý odošle jednoduchý objekt JSON:

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

Upozorňujeme, že transformácia zo zbierok na objekty JSON je plytká. Napríklad a Zoznam z MapaKonvertované nebudú na pole JSON objektov JSON, ale skôr na pole reťazcov.

Pre hlbokú konverziu by sme potrebovali zložitejšiu mapovaciu knižnicu JSON, napríklad Jackson. Konverzná funkcia knižnice je určená len pre jednoduché prípady.

5.2. Odosielanie údajov formulára (kódované URL)

Na odosielanie údajov formulárov (s kódovaním URL, ako vo formulároch HTML) používame údaje argument s a Mapa:

khttp.post (url = "//httpbin.org/post", data = mapOf ("kľúč1" až "hodnota1", "keyn" až "valuen"))

5.3. Načítanie súborov (viacdielny formulár)

Môžeme poslať jeden alebo viac súborov kódovaných ako požiadavka na údaje vo forme viacdielneho formulára.

V takom prípade použijeme súbory argument:

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

Vidíme, že khttp používa a FileLike abstrakcia, čo je objekt s menom a obsahom. Obsahom môže byť reťazec, bajtové pole, a Súbor, alebo a Cesta.

5.4. Posiela sa nespracovaný obsah

Ak žiadna z vyššie uvedených možností nie je vhodná, môžeme použiť InputStream na odoslanie nespracovaných údajov ako tela požiadavky HTTP:

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

V takom prípade budeme s najväčšou pravdepodobnosťou musieť ručne nastaviť aj niektoré hlavičky, ktorým sa budeme venovať v ďalšej časti.

6. Vybavenie odpovede

Doteraz sme videli rôzne spôsoby odosielania údajov na server. Ale veľa operácií HTTP je užitočných aj kvôli údajom, ktoré vracajú.

khttp je preto založený na blokovaní I / O všetky funkcie zodpovedajúce metódam HTTP vracajú a Odozva objekt obsahujúca odpoveď prijatú zo servera.

Tento objekt má rôzne vlastnosti, ku ktorým máme prístup, v závislosti od typu obsahu.

6.1. Odpovede JSON

Ak vieme, že odpoveďou je objekt alebo pole JSON, môžeme použiť jsonObject a jsonArray vlastnosti:

odpoveď val: Response = khttp.get ("// httpbin.org/get") val obj: JSONObject = response.jsonObject print (obj ["someProperty"])

6.2. Textové alebo binárne odpovede

Ak si chceme odpoveď prečítať ako a String namiesto toho môžeme použiť text nehnuteľnosť:

správa val: String = response.text

Alebo ak ich chceme načítať ako binárne údaje (napr. Stiahnutie súboru), použijeme obsah nehnuteľnosť:

val imageData: ByteArray = response.content

Nakoniec môžeme pristupovať aj k podkladovým InputStream:

val inputStream: InputStream = response.raw

7. Pokročilé použitie

Poďme sa tiež pozrieť na niekoľko pokročilejších spôsobov používania, ktoré sú všeobecne užitočné, a ktoré sme v predchádzajúcich častiach ešte nespracovali.

7.1. Zaobchádzanie s hlavičkami a cookies

Všetky funkcie khttp majú a hlavičky argument čo je a Mapa mien a hodnôt hlavičiek.

val response = khttp.get (url = "//httpbin.org/get", headers = mapOf ("header1" až "1", „header2" až „2"))

Podobne pre cookies:

val response = khttp.get (url = "//httpbin.org/get", cookies = mapOf ("cookie1" až "1", "cookie2" až "2"))

Môžeme tiež získať prístup k hlavičkám a súborom cookie odoslaným serverom v odpovedi:

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

7.2. Riešenie chýb

V protokole HTTP môžu vzniknúť dva typy chýb: chybové reakcie, napríklad 404 - nenájdené, ktoré sú súčasťou protokolu; a chyby na nízkej úrovni, napríklad „pripojenie odmietnuté“.

Prvý druh nemá za následok hádzanie výnimiek khttp; namiesto toho mali by sme skontrolovať Status odpovede Kód nehnuteľnosť:

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

Chyby nižšej úrovne namiesto toho vedú k vyvolávaniu výnimiek zo základného subsystému Java I / O, ako je napr ConnectException.

7.3. Streamovacie odpovede

Server môže niekedy odpovedať veľkým obsahom alebo odpovedať môže trvať dlho. V týchto prípadoch možno budeme chcieť reakciu spracovať po častiach, namiesto toho, aby sme čakali na dokončenie a zaberanie pamäte.

Ak chceme dať knižnici pokyn, aby nám poskytla streamovanú odpoveď, musíme prejsť pravda ako Prúd argument:

val response = khttp.get (url = "//httpbin.org", stream = true)

Potom to môžeme spracovať po častiach:

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

7.4. Neštandardné metódy

V nepravdepodobnom prípade, že budeme musieť použiť metódu HTTP (alebo sloveso), ktorú khttp natívne neposkytuje - povedzme pri niektorých rozšíreniach protokolu HTTP, napríklad WebDAV, sme stále zahrnutí.

V skutočnosti sú všetky funkcie v balíku khttp, ktoré zodpovedajú metódam HTTP, implementované pomocou generického žiadosť funkciu, ktorú môžeme tiež použiť:

khttp.request (method = "COPY", url = "//httpbin.org/get", headers = mapOf ("Destination" to "/ copy-of-get"))

7.5. Ďalšie funkcie

Nedotkli sme sa všetkých funkcií khttp. Nerozprávali sme sa napríklad o časových limitoch, presmerovaniach a histórii ani o asynchrónnych operáciách.

Oficiálna dokumentácia je hlavným zdrojom informácií o knižnici a všetkých jej vlastnostiach.

8. Záver

V tomto tutoriáli sme videli, ako robiť požiadavky HTTP v Kotline s idiomatickou knižnicou khttp.

Implementáciu všetkých týchto príkladov možno nájsť v projekte GitHub.