HTTP-anmodninger med Kotlin og khttp

1. Introduktion

HTTP-protokollen og API'erne bygget på den er af central betydning i programmeringen i disse dage.

På JVM har vi flere tilgængelige muligheder, fra lavere niveau til meget højt niveau biblioteker, fra etablerede projekter til nye børn på blokken. De fleste af dem er dog primært målrettet mod Java-programmer.

I denne artikel vi skal se på khttp, et idiomatisk Kotlin-bibliotek til forbrug af HTTP-baserede ressourcer og API'er.

2. Afhængigheder

For at kunne bruge biblioteket i vores projekt skal vi først tilføje det til vores afhængigheder:

 khttp khttp 0.1.0 

Da dette endnu ikke er på Maven Central, skal vi også aktivere JCenter-arkivet:

 central //jcenter.bintray.com 

Version 0.1.0 er den aktuelle i skrivende stund. Vi kan selvfølgelig kontrollere JCenter for en nyere.

3. Grundlæggende anvendelse

Grundlæggende i HTTP-protokollen er enkel, selvom de fine detaljer kan være ret komplicerede. Derfor har khttp også en simpel grænseflade.

For hver HTTP-metode kan vi finde en pakke-niveau-funktion i khttp pakke, såsom få, stolpe og så videre.

Funktionerne tager alle det samme sæt argumenter og returnerer a Respons objekt; Vi vil se detaljerne om disse i de følgende afsnit.

I løbet af denne artikel bruger vi den fuldt kvalificerede formular, for eksempel khttp.put. I vores projekter kan vi selvfølgelig importere og muligvis omdøbe disse metoder:

importer khttp.delete som httpDelete

Bemærk: Vi har tilføjet typedeklarationer for klarhed i hele kodeeksemplerne for uden IDE kunne de være svære at følge.

4. En simpel anmodning

Hver HTTP-anmodning har mindst to nødvendige komponenter: en metode og en URL. I khttp bestemmes metoden af ​​den funktion, vi påberåber os, som vi har set i det foregående afsnit.

URL'en er det eneste krævede argument for metoden; så vi kan nemt udføre en simpel anmodning:

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

I de følgende afsnit overvejer vi alle anmodninger om at gennemføre med succes.

4.1. Tilføjelse af parametre

Vi er ofte nødt til at angive forespørgselsparametre ud over basis-URL'en, især til GET-anmodninger.

khttps metoder accepterer a params argument hvilket er en Kort af nøgleværdipar, der skal medtages i forespørgslen Snor:

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

Bemærk, at vi har brugt mapOf funktion til at konstruere en Kort i farten den resulterende anmodnings-URL vil være:

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

5. Et anmodningsorgan

En anden almindelig handling, som vi ofte skal udføre, er at sende data, typisk som nyttelasten for en POST- eller PUT-anmodning.

Til dette tilbyder biblioteket flere muligheder, som vi vil undersøge i de følgende sektioner.

5.1. Afsendelse af en JSON-nyttelast

Vi kan bruge json argument for at sende et JSON-objekt eller array. Det kan være af flere forskellige typer:

  • EN JSONObjekt eller JSONArray som leveret af org.json-biblioteket
  • EN Kort, som omdannes til et JSON-objekt
  • EN Kollektion, Iterabel eller array, som omdannes til et JSON-array

Vi kan let omdanne vores tidligere GET-eksempel til en POST, der sender et simpelt JSON-objekt:

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

Bemærk, at transformationen fra samlinger til JSON-objekter er lav. F.eks Liste af Kort'S konverteres ikke til et JSON-array med JSON-objekter, men snarere til et array af strenge.

For dyb konvertering har vi brug for et mere komplekst JSON-kortlægningsbibliotek som Jackson. Bibliotekets konverteringsfacilitet er kun beregnet til enkle sager.

5.2. Afsendelse af formulardata (URL-kodet)

For at sende formulardata (URL-kodet, som i HTML-formularer) bruger vi data argument med en Kort:

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

5.3. Upload af filer (formular med flere dele)

Vi kan sende en eller flere filer kodet som en anmodning om datadata i flere dele.

I så fald bruger vi filer argument:

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

Vi kan se, at khttp bruger en FileLike abstraktion, som er et objekt med et navn og et indhold. Indholdet kan være en streng, et byte-array, en Fil, eller a Sti.

5.4. Afsendelse af rå indhold

Hvis ingen af ​​ovenstående muligheder er egnede, kan vi bruge en InputStream at sende rådata som kroppen af ​​en HTTP-anmodning:

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

I dette tilfælde skal vi sandsynligvis også manuelt indstille nogle overskrifter, som vi vil dække i et senere afsnit.

6. Håndtering af svaret

Indtil videre har vi set forskellige måder at sende data til en server på. Men mange HTTP-operationer er nyttige på grund af de data, de også returnerer.

khttp er derfor baseret på blokering af I / O alle funktioner, der svarer til HTTP-metoder, returnerer a Respons objekt indeholdende svar modtaget fra serveren.

Dette objekt har forskellige egenskaber, som vi kan få adgang til, afhængigt af typen af ​​indhold.

6.1. JSON-svar

Hvis vi kender svaret til at være et JSON-objekt eller array, kan vi bruge jsonObject og jsonArray ejendomme:

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

6.2. Tekst eller binære svar

Hvis vi vil læse svaret som en Snor i stedet kan vi bruge tekst ejendom:

val meddelelse: String = respons.text

Eller hvis vi vil læse det som binære data (f.eks. En fildownload) bruger vi indhold ejendom:

val imageData: ByteArray = respons.content

Endelig kan vi også få adgang til det underliggende InputStream:

val inputStream: InputStream = respons.raw

7. Avanceret brug

Lad os også se på et par mere avancerede brugsmønstre, der generelt er nyttige, og som vi endnu ikke har behandlet i de foregående afsnit.

7.1. Håndtering af overskrifter og cookies

Alle khttp-funktioner tager en overskrifter argument hvilket er en Kort af headernavne og værdier.

val respons = khttp.get (url = "//httpbin.org/get", headers = mapOf ("header1" til "1", "header2" til "2"))

Tilsvarende for cookies:

val respons = khttp.get (url = "//httpbin.org/get", cookies = mapOf ("cookie1" til "1", "cookie2" til "2"))

Vi kan også få adgang til overskrifter og cookies sendt af serveren i svaret:

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

7.2. Håndtering af fejl

Der er to typer fejl, der kan opstå i HTTP: fejlsvar, såsom 404 - Ikke fundet, som er en del af protokollen; og fejl på lavt niveau, såsom "forbindelse nægtet".

Den første slags resulterer ikke i khttp-kaste undtagelser; i stedet, vi skal kontrollere Svar statusKode ejendom:

val respons = khttp.get (url = "//httpbin.org/nothing/to/see/here") hvis (respons.statusCode == 200) {proces (respons)} ellers {handleError (respons)}

Fejl på lavere niveau medfører i stedet undtagelser fra det underliggende Java I / O-undersystem, f.eks ConnectException.

7.3. Streaming-svar

Nogle gange kan serveren svare med et stort stykke indhold og / eller tage lang tid at svare. I disse tilfælde vil vi måske behandle svaret i bidder i stedet for at vente på, at det er færdigt og optager hukommelse.

Hvis vi vil instruere biblioteket om at give os et streaming-svar, skal vi videregive det rigtigt som den strøm argument:

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

Derefter kan vi behandle det i bidder:

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

7.4. Ikke-standardmetoder

I det usandsynlige tilfælde, at vi har brug for en HTTP-metode (eller verb), som khttp ikke leverer indbygget - sig, for en eller anden udvidelse af HTTP-protokollen, som WebDAV - er vi stadig dækket.

Faktisk implementeres alle funktioner i khttp-pakken, der svarer til HTTP-metoder, ved hjælp af en generisk anmodning funktion, som vi også kan bruge:

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

7.5. Andre funktioner

Vi har ikke rørt alle funktionerne i khttp. For eksempel har vi ikke diskuteret timeouts, omdirigeringer og historie eller asynkrone operationer.

Den officielle dokumentation er den ultimative kilde til information om biblioteket og alle dets funktioner.

8. Konklusion

I denne vejledning har vi set, hvordan man laver HTTP-anmodninger i Kotlin med det idiomatiske bibliotek khttp.

Implementeringen af ​​alle disse eksempler findes i GitHub-projektet.


$config[zx-auto] not found$config[zx-overlay] not found