Ръководство за Унирест

1. Общ преглед

Unirest е лека HTTP клиентска библиотека от Mashape. Заедно с Java, той е достъпен и за Node.js, .Net, Python, Ruby и др.

Преди да влезем, имайте предвид, че ще използваме mocky.io за всички наши HTTP заявки тук.

2. Настройка на Maven

За да започнем, нека първо добавим необходимите зависимости:

 com.mashape.unirest unirest-java 1.4.9 

Вижте най-новата версия тук.

3. Прости заявки

Нека изпратим проста HTTP заявка, за да разберем семантиката на рамката:

@Test public void shouldReturnStatusOkay() { HttpResponse jsonResponse = Unirest.get("//www.mocky.io/v2/5a9ce37b3100004f00ab5154") .header("accept", "application/json").queryString("apiKey", "123") .asJson(); assertNotNull(jsonResponse.getBody()); assertEquals(200, jsonResponse.getStatus()); }

Забележете, че API е плавен, ефективен и доста лесен за четене.

Предаваме заглавки и параметри с API на header () и fields () .

И заявката се извиква при извикване на метода asJson () ; тук имаме и други опции, като asBinary (), asString () и asObject ().

За да предадем множество заглавки или полета, можем да създадем карта и да ги предадем съответно на .headers (заглавки на карти) и .fields (полета на картата) :

@Test public void shouldReturnStatusAccepted() { Map headers = new HashMap(); headers.put("accept", "application/json"); headers.put("Authorization", "Bearer 5a9ce37b3100004f00ab5154"); Map fields = new HashMap(); fields.put("name", "Sam Baeldung"); fields.put("id", "PSP123"); HttpResponse jsonResponse = Unirest.put("//www.mocky.io/v2/5a9ce7853100002a00ab515e") .headers(headers).fields(fields) .asJson(); assertNotNull(jsonResponse.getBody()); assertEquals(202, jsonResponse.getStatus()); }

3.1. Предаване на параметри на заявката

За да предадем данни като низ за заявка , ще използваме метода queryString () :

HttpResponse jsonResponse = Unirest.get("//www.mocky.io/v2/5a9ce37b3100004f00ab5154") .queryString("apiKey", "123")

3.2. Използване на параметри на пътя

За предаване на всякакви параметри на URL, можем да използваме метода routeParam () :

HttpResponse jsonResponse = Unirest.get("//www.mocky.io/v2/5a9ce37b3100004f00ab5154/{userId}") .routeParam("userId", "123")

Името на заместител на параметъра трябва да бъде същото като първия аргумент на метода.

3.3. Заявки с тяло

Ако нашата заявка изисква низ / JSON тяло, ние го предаваме, използвайки метода body () :

@Test public void givenRequestBodyWhenCreatedThenCorrect() { HttpResponse jsonResponse = Unirest.post("//www.mocky.io/v2/5a9ce7663100006800ab515d") .body("{\"name\":\"Sam Baeldung\", \"city\":\"viena\"}") .asJson(); assertEquals(201, jsonResponse.getStatus()); }

3.4. Съпоставяне на обекти

За да използваме asObject () или body () в заявката, трябва да дефинираме нашия обект за картографиране. За улеснение ще използваме картографирането на обекти на Джаксън.

Нека първо добавим следните зависимости към pom.xml :

 com.fasterxml.jackson.core jackson-databind 2.9.4 

Винаги използвайте най-новата версия на Maven Central.

Сега нека конфигурираме нашия картограф:

Unirest.setObjectMapper(new ObjectMapper() { com.fasterxml.jackson.databind.ObjectMapper mapper = new com.fasterxml.jackson.databind.ObjectMapper(); public String writeValue(Object value) { return mapper.writeValueAsString(value); } public  T readValue(String value, Class valueType) { return mapper.readValue(value, valueType); } });

Обърнете внимание, че setObjectMapper () трябва да се извиква само веднъж, за задаване на mapper; след като екземплярът на mapper бъде зададен, той ще се използва за всички заявки и отговори.

Нека сега тестваме новата функционалност, използвайки персонализиран обект Article :

@Test public void givenArticleWhenCreatedThenCorrect() { Article article = new Article("ID1213", "Guide to Rest", "baeldung"); HttpResponse jsonResponse = Unirest.post("//www.mocky.io/v2/5a9ce7663100006800ab515d") .body(article) .asJson(); assertEquals(201, jsonResponse.getStatus()); }

4. Методи за заявка

Подобно на всеки HTTP клиент, рамката предоставя отделни методи за всеки HTTP глагол:

ПОЩА:

Unirest.post("//www.mocky.io/v2/5a9ce7663100006800ab515d")

СЛАГАМ:

Unirest.put("//www.mocky.io/v2/5a9ce7663100006800ab515d")

ВЗЕМЕТЕ:

Unirest.get("//www.mocky.io/v2/5a9ce7663100006800ab515d")

ИЗТРИЙ:

Unirest.delete("//www.mocky.io/v2/5a9ce7663100006800ab515d")

КРЪПКА:

Unirest.patch("//www.mocky.io/v2/5a9ce7663100006800ab515d")

НАСТРОИКИ:

Unirest.options("//www.mocky.io/v2/5a9ce7663100006800ab515d")

5. Методи за отговор

След като получим отговора, нека проверим кода на състоянието и съобщението за състоянието:

//... jsonResponse.getStatus() //...

Извличане на заглавките:

//... jsonResponse.getHeaders(); //...

Вземете тялото на отговора:

//... jsonResponse.getBody(); jsonResponse.getRawBody(); //...

Забележете, че getRawBody () връща поток от неразбитото тяло на отговора, докато getBody () връща анализираното тяло, като използва обектното картографиране, дефинирано в по-ранния раздел.

6. Обработка на асинхронни заявки

Unirest също има способността да обработва асинхронни заявки - използвайки java.util.concurrent.Future и методи за обратно извикване:

@Test public void whenAysncRequestShouldReturnOk() { Future
    
      future = Unirest.post( "//www.mocky.io/v2/5a9ce37b3100004f00ab5154?mocky-delay=10000ms") .header("accept", "application/json") .asJsonAsync(new Callback() { public void failed(UnirestException e) { // Do something if the request failed } public void completed(HttpResponse response) { // Do something if the request is successful } public void cancelled() { // Do something if the request is cancelled } }); assertEquals(200, future.get().getStatus()); }
    

The com.mashape.unirest.http.async.Callback interface provides three methods, failed(), cancelled() and completed().

Override the methods to perform the necessary operations depending on the response.

7. File Uploads

To upload or send a file as a part of the request, pass a java.io.File object as a field with name file:

@Test public void givenFileWhenUploadedThenCorrect() { HttpResponse jsonResponse = Unirest.post( "//www.mocky.io/v2/5a9ce7663100006800ab515d") .field("file", new File("/path/to/file")) .asJson(); assertEquals(201, jsonResponse.getStatus()); }

We can also use ByteStream:

@Test public void givenByteStreamWhenUploadedThenCorrect() { try (InputStream inputStream = new FileInputStream( new File("/path/to/file/artcile.txt"))) { byte[] bytes = new byte[inputStream.available()]; inputStream.read(bytes); HttpResponse jsonResponse = Unirest.post( "//www.mocky.io/v2/5a9ce7663100006800ab515d") .field("file", bytes, "article.txt") .asJson(); assertEquals(201, jsonResponse.getStatus()); } }

Or use the input stream directly, adding the ContentType.APPLICATION_OCTET_STREAM as the second argument in the fields() method:

@Test public void givenInputStreamWhenUploadedThenCorrect() { try (InputStream inputStream = new FileInputStream( new File("/path/to/file/artcile.txt"))) { HttpResponse jsonResponse = Unirest.post( "//www.mocky.io/v2/5a9ce7663100006800ab515d") .field("file", inputStream, ContentType.APPLICATION_OCTET_STREAM, "article.txt").asJson(); assertEquals(201, jsonResponse.getStatus()); } }

8. Unirest Configurations

The framework also supports typical configurations of an HTTP client like connection pooling, timeouts, global headers etc.

Let's set the number of connections and number maximum connections per route:

Unirest.setConcurrency(20, 5);

Configure connection and socket timeouts :

Unirest.setTimeouts(20000, 15000);

Note that the time values are in milliseconds.

Now let's set HTTP headers for all our requests:

Unirest.setDefaultHeader("X-app-name", "baeldung-unirest"); Unirest.setDefaultHeader("X-request-id", "100004f00ab5");

We can clear the global headers anytime:

Unirest.clearDefaultHeaders();

At some point, we might need to make requests through a proxy server:

Unirest.setProxy(new HttpHost("localhost", 8080));

One important aspect to be aware of is closing or exiting the application gracefully. Unirest spawns a background event loop to handle the operations, we need to shut down that loop before exiting our application:

Unirest.shutdown();

9. Conclusion

In this tutorial, we focused on the lightweight HTTP client framework – Unirest. We worked with some simple examples, both in a synchronous but also async modes.

Finally, we also used several advanced configurations – such as connection pooling, proxy settings etc.

Както обикновено, изходният код е достъпен в GitHub.