UniRest 使用手册

UniRest是什么？

Unirest 是一套跨语言轻量级HTTP开发库，由Kong团队维护，此团队同时维护着另一个著名开源网关项目API Gateway Kong.

MAVEN安装

<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-java</artifactId>
    <version>3.5.00</version>
</dependency>

<!-- 需要作为独立jar文件引用时(包含隐式依赖) -->
<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-java</artifactId>
    <version>3.5.00</version>
    <classifier>standalone</classifier>
</dependency>

请求

使用JAVA语言，创建一个Unirest请求相当方便，一个常见的POST请求如下：

HttpResponse<JsonNode> response =Unirest.post("http://httpbin.org/post")
      .header("accept", "application/json")
      .queryString("apiKey", "123")
      .field("parameter", "value")
      .field("foo", "bar")
      .asJson();

路由参数

如果需要在URL中加入动态路由参数，可以先在URL中通过一个占位符标记参数位置，之后通过routeParam方法，动态指定参数值，如下所示：

Unirest.get("http://httpbin.org/{fruit}")
     .routeParam("fruit", "apple")
     .asString();

占位符的格式为{自定义名称}，在示例中，{占位符}会被替换为 apple，并且所有占位符会自动使用
URL-Encoded转义。

查询参数

请求路径附带的参数可以通过如下方式逐个添加：

Unirest.get("http://httpbin.org")
                .queryString("fruit", "apple")
                .queryString("droid", "R2D2")
                .asString();

// 请求路径 "http://httpbin.org?fruit=apple&droid=R2D2"

queryString 方法也支持通过数组，或Map传递参数

Unirest.get("http://httpbin.org")
        .queryString("fruit", Arrays.asList("apple", "orange"))
        .queryString(ImmutableMap.of("droid", "R2D2", "beatle", "Ringo"))
        .asString();

 // 请求路径 "http://httpbin.org?fruit=apple&fruit=orange&droid=R2D2&beatle=Ringo"

请求头

请求头通过header方法，添加：

Unirest.get("http://httpbin.org")
            .header("Accept", "application/json")
            .header("x-custom-header", "hello")
            .asString();

Basic Authentication 认证

Unirest提供了一个方便的方法实现 Basic Authentication 认证，Unirest 会自动处理Base64编码部分，此认证建议使用HTTPS。

Unirest.get("http://httpbin.org")
            .basicAuth("user", "password1!")
            .asString();

// 请求头 "Authorization: Basic dXNlcjpwYXNzd29yZDEh"

请求体

请求体通过body方法指定，除非特别指定，否则请求头中 Content-Type 统一设置为：text/plain; charset=UTF-8

Unirest.post("http://httpbin.org")
                .body("This is the entire body")
                .asEmpty();

body方法传入对象，支持用Jackson序列化对象方式生成请求体。

Unirest.post("http://httpbin.org")
            .header("Content-Type", "application/json")
            .body(new SomeUserObject("Bob"))
            .asEmpty();

// This will use Jackson to serialize the object into JSON.

JSON Patch支持

Unirest 原生支持JSON Patch 技术(参见 RFC-6902 http://jsonpatch.com/) 。json-patch请求默认的Content-Type是application/json-patch+json。

Unirest.jsonPatch("http://httpbin.org")
            .add("/fruits/-", "Apple")
            .remove("/bugs")
            .replace("/lastname", "Flintstone")
            .test("/firstname", "Fred")
            .move("/old/location", "/new/location")
            .copy("/original/location", "/new/location")
            .asJson();

基本表单

通过body传输的表单name和value参数可以通过field指定，此类请求的Content-Type默认为application/x-www-form-urlencoded

Unirest.post("http://httpbin.org")
       .field("fruit", "apple")
       .field("droid", "R2D2")
       .asEmpty();

文件上传

可以通过POST表单提交二进制数据，例如:文件。这种类型的请求中，Content-Type默认为multipart/form-data。

Unirest.post("http://httpbin.org")
       .field("upload", new File("/MyFile.zip"))
       .asEmpty();

对于大文件上传，可以通过InputStream方式上传，同时可以附加文件名。示例中使用FileInputStream举例，实际上也同时支持各类InputStream。

InputStream file = new FileInputStream(new File("/MyFile.zip"));

Unirest.post("http://httpbin.org")
       .field("upload", file, "MyFile.zip")
       .asEmpty();

在上传大文件时，如果需要向用户展示进度条，可以通过提供一个ProgresMonitor来实现：

Unirest.post("http://httpbin.org")
                .field("upload", new File("/MyFile.zip"))
                .uploadMonitor((field, fileName, bytesWritten, totalBytes) -> {
                    updateProgressBarWithBytesLeft(totalBytes - bytesWritten);
                })
                .asEmpty();

异步请求

所有请求都支持异步版本，示例如下：

CompletableFuture<HttpResponse<JsonNode>> future = Unirest.post("http://httpbin.org/post")
  .header("accept", "application/json")
  .field("param1", "value1")
  .field("param2", "value2")
  .asJsonAsync(response -> {
        int code = response.getStatus();
        JsonNode body = response.getBody();
    });

请求分页

有些服务提供分页数据，Unirest可以通过一种标准方式，自动拉去全部数据。
使用这个功能需要提供两个方法参数。 第一个方法将返回内容转换为需要的HttpResponse对象， 另一个方法从返回内容中获取下一页的URL链接地址。此功能返回PagedList<HttpResponse>对象。 PagedList对象封装了处理返回结果的一些常用方法。
以下示例中，Unirest自动分页拉取了Doggos对象列表，下一页连接通过hearder内容获取。

PagedList<Doggos> result =  Unirest.get("https://somewhere/dogs")
                .asPaged(
                        r -> r.asObject(Doggos.class),
                        r -> r.getHeaders().getFirst("nextPage")
                );

客户端证书

在需要客户端证书的情况下，unirest支持通过传递自定义的KeyStore对象，或提供一个有效的PKCS#12 keystore文件实现服务认证。

Unirest.config()
  .clientCertificateStore("/path/mykeystore.p12", "password1!");

Unirest.get("https://some.custom.secured.place.com")
                .asString();

代理

Unirest支持通过proxy方法配置代理。需要注意的是，unirest不支持为单个请求，配置带有权限验证的代理，除非权限验证内容构建在URL中。

// 配置带有权限验证的代理
Unirest.config().proxy("proxy.com", 7777, "username", "password1!");

// 或使用无权限验证的代理
Unirest.config().proxy("proxy.com", 7777);

// 通过请求指定代理，这样会覆盖默认代理
// 这种情况下，只有不需要验证的代理可以生效
Unirest.get(MockServer.GET)
                .proxy("proxy.com", 7777)
                .asString();

返回值

Unirest 在调用as[type]方法时，实际发送请求。这类方法同时限定了返回值类型。例如：Empty, String, File, Object, byte and Json.
返回值对象HttpResponse 封装了例如：status,headers等。返回值body内容，通过getBody() 获取。

返回空值

如果不需要处理返回body内容，asEmpty是一个十分好用的方法，返回内容仍然包含status 和headers。

HttpResponse response = Unirest.delete("http://httpbin.org").asEmpty()

返回字符串

另一个方便的方法是通过asString方法获取返回字符串。

String body = Unirest.get("http://httpbin.org")
                     .asString()
                     .getBody();

返回对象处理

通常使用RESTful 服务时，会对返回值进行json对象转换。在这种情况下，需要为Unirest指定ObjectMapper （参见ObjectMapper ）。

Unirest 默认通过Google GSON来处理JSON数据。如果不希望使用默认处理方式，在使用asObject(Class)方法前，需要向Unirest提供ObjectMapper 接口的自定义实现。在初次指定之后，ObjectMapper 对象会被全局共享。

Unirest 同时提供一些ObjectMapper 插件， 例如：Jackson 、Gson. 可以通过maven center了解详情。

// 返回对象
Book book = Unirest.get("http://httpbin.org/books/1")
                   .asObject(Book.class)
                   .getBody();

// 通过GenericType支持构建泛型对象
List<Book> books = Unirest.get("http://httpbin.org/books/")
              .asObject(new GenericType<List<Book>>(){})
              .getBody();

Author author = Unirest.get("http://httpbin.org/books/{id}/author")
                       .routeParam("id", bookObject.getId())
                       .asObject(Author.class)
                       .getBody();

对象返回值异常处理

在JSON转化为对象过程中出现异常时，body返回值为null，需要通过getParsingError获取异常信息和返回的body值。

UnirestParsingException ex = response.getParsingError().get();

ex.getOriginalBody(); // 返回body原始值
ex.getMessage(); // 处理过程出现的异常信息
ex.getCause(); // 原始parsing exception

错误信息对象映射

有些场景下，REST API’s 会返回错误信息对象，通过以下方式可以进行转换：

HttpResponse<Book> book = Unirest.get("http://httpbin.org/books/{id}")
                                     .asObject(Book.class);

    // 在没有错误的情况下，此方法返回null
    Error er = book.mapError(Error.class);

    // ifFailure 方法中也可以做类似自动转换
    Unirest.get("http://httpbin.org/books/{id}")
           .asObject(Book.class)
           .ifFailure(Error.class, r -> {
                    Error e = r.getBody();
           });

返回值类型转换

如果不想实现ObjectMapper ，也可以通过如下方法自动转换返回内容。

int body = Unirest.get("http://httpbin/count")
                      .asString()
                      .mapBody(Integer::valueOf);

返回文件

Unirest 支持简单下载文件，或从响应体中转换文件下载，只需提供下载路径即可：

File result = Unirest.get("http://some.file.location/file.zip")
                .asFile("/disk/location/file.zip")
                .getBody();

返回JSON

在不需要Object Mapper时，Unirest 还提供一个轻量级JSON对象响应体。

String result = Unirest.get("http://some.json.com")
                       .asJson()
                       .getBody()
                       .getObject()
                       .getJSONObject("thing")
                       .getJSONArray("foo")
                       .get(0)

返回大量数据

通过一些方法 (asString, asJson) Unirest会将整个返回值加载到内存。 以下方法可以获取数据流对象，支持处理大量数据的情况:

Map r = Unirest.get(MockServer.GET)
                .queryString("foo", "bar")
                .asObject(i -> new Gson().fromJson(i.getContentReader(), HashMap.class))
                .getBody();

消费者模式

Unirest.get(MockServer.GET)
                .thenConsumeAsync(r -> {
                       // 此处可以写数据到文件
                });

Error Handling

HttpResponse支持链式处理成功和失败请求。
在返回值为2XX同时对象转换成功时，ifSuccess(Consumer<HttpResponse> response) 方法会被调用。在返回值为400+时或者对象转换失败时，ifFailure(Consumer会被调用。

Unirest.get("http://somewhere")
                .asJson()
                .ifSuccess(response -> someSuccessMethod(response))
                .ifFailure(response -> {
                    log.error("Oh No! Status" + response.getStatus());
                    response.getParsingError().ifPresent(e -> {
                        log.error("Parsing Exception: ", e);
                        log.error("Original body: " + e.getOriginalBody());
                    });
                });

Configuration

通过Unirest.config()，可以配置http请求的常见参数。参数详见官方文档（http://kong.github.io/unirest-java/#configuration）

Unirest.config()
           .socketTimeout(500)
           .connectTimeout(1000)
           .concurrency(10, 5)
           .proxy(new Proxy("https://proxy"))
           .setDefaultHeader("Accept", "application/json")
           .followRedirects(false)
           .enableCookieManagement(false)
           .addInterceptor(new MyCustomInterceptor());

全局拦截器

Unirest支持通过配置全局拦截器，实现统一日志，注入参数等操作。
示例：
Interceptor.java

自定义Apache Clients

Unirest 目前通过Apache Http Client提供底层 实现, 未来可能发生变化。
Unirest支持设置自定义Apache HttpClient 和HttpAsyncClient.

Unirest.config()
            .httpClient(ApacheClient.builder(myClient))
            .asyncClient(ApacheAsyncClient.builder(myAsyncClient));Copy

Unirest的请求配置也可以覆盖
Unirest.config()
            .httpClient(ApacheClient.builder(client)
                .withRequestConfig((c,r) -> RequestConfig.custom().build()
                );

配置不同客户端

通常，Unirest维护一个主单例对象。但有些情况下，例如：需要为不同系统设定不同配置，或需要为测试目的避开静态上下文时，可以使用如下方式：

 //第一个Unirest对象
    UnirestInstance unirest = Unirest.primaryInstance();
    unirest.config().connectTimeout(5000);
    String result = unirest.get("http://foo").asString().getBody();

    //第二个Unirest对象
    UnirestInstance unirest = Unirest.spawnInstance();

Object Mappers

Unirest 提供一些基于著名JSON库的ObjectMapper (Jackson and GSON)。可以通过以下方式引用。

<!-- https://mvnrepository.com/artifact/com.konghq/unirest-objectmapper-jackson -->
<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-objectmapper-jackson</artifactId>
    <version>3.5.00</version>
</dependency>

<!-- https://mvnrepository.com/artifact/com.konghq/unirest-object-mappers-gson -->
<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-object-mappers-gson</artifactId>
    <version>3.5.00</version>
</dependency>

Metrics

Unirest 支持动态收集指标的钩子函数。 此轻量级框架支持两类事件：
1、请求发生前
2、请求发生后
上下文信息例如方法名和请求路径等在这两个事件中都已经提供，因此基本上可以借助此框架收集到需要的任何指标信息。一个简单示例如下:

Unirest.config().instrumentWith(requestSummary -> {
              long startNanos = System.nanoTime();
              return (responseSummary,exception) -> logger.info("path: {} status: {} time: {}",
                      requestSummary.getRawPath(),
                      responseSummary.getStatus(),
                      System.nanoTime() - startNanos);
   });

关闭连接

Unirest 启动了一个后台事件总线 ,需要调用以下方法才能关闭

Unirest.shutdown();