Vert.x Web Client是一個非同步的HTTP和HTTP/2網路客戶端。

相對來說，這是一個比較小的框架，而且功能也很直接，做一個方便好用的HTTP客戶端。它具有以下功能：

• Json body 編碼 / 解碼
• request 引數
• 統一的錯誤處理
• 表單提交

需要注意，它和Vertx核心包中的HttpClient有很多聯絡。它繼承了HttpClient，提供了更多功能。

引用類庫

要使用這個類庫很簡單。如果使用Maven，新增下面的依賴。

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web-client</artifactId>
  <version>3.4.2</version>
</dependency>
 

如果使用Gradle，新增下面的依賴。

dependencies {
  compile 'io.vertx:vertx-web-client:3.4.2'
}

建立客戶端

建立客戶端稍微有點不一樣。

WebClient client = WebClient.create(vertx);

如果要新增配置引數，可以這樣做。

WebClientOptions options = new WebClientOptions()
  .setUserAgent("My-App/1.2.3");
options.setKeepAlive(false);
WebClient client = WebClient.create(vertx, options);
 

如果已經有了HttpClient，可以重用它。

WebClient client = WebClient.wrap(httpClient);

發起請求

無請求體的請求

這是最簡單的情況，一般的GET、HEAD等請求都輸這種方式。

webClient.get("www.baidu.com", "/")
        .send(ar -> {
            if (ar.succeeded()) {
                HttpResponse<Buffer> response = ar.result();
                System.out.println(response.body());
            } else {
                System.out.println(ar.cause());
            }
        });
 

如果要攜帶查詢引數，可以採用流式API。

client
  .get(8080, "myserver.mycompany.com", "/some-uri")
  .addQueryParam("param", "param_value")
  .send(ar -> {});

也可以直接在URL中設定查詢引數。

HttpRequest<Buffer> request = client.get(8080, "myserver.mycompany.com", "/some-uri");

// 新增引數1
request.addQueryParam("param1", "param1_value");

// 用URL覆蓋引數
request.uri("/some-uri?param1=param1_value&param2=param2_value");

新增請求體

假如使用POST方式傳遞引數，或者上傳圖片等，就需要帶有請求體的請求了。這種情況下，只需要額外使用sendXXX等方法新增要傳遞的請求體即可。

webClient.post("httpbin.org", "/post")
        .sendBuffer(Buffer.buffer("name=yitian&age=25"), ar -> {
            if (ar.succeeded()) {
                HttpResponse<Buffer> response = ar.result();
                System.out.println(response.body());
            }
        });

如果要傳送的資訊比較大，可以使用sendStream方法，使用流來傳輸資料。

client
  .post(8080, "myserver.mycompany.com", "/some-uri")
  .sendStream(stream, resp -> {});

Json請求體

有時候可能需要傳送Json資料，這時候可以使用sendJsonObject方法。

client
  .post(8080, "myserver.mycompany.com", "/some-uri")
  .sendJsonObject(new JsonObject()
    .put("firstName", "Dale")
    .put("lastName", "Cooper"), ar -> {
    if (ar.succeeded()) {
      // Ok
    }
  });

傳送表單

傳送表單使用sendForm方法。

MultiMap multiMap = MultiMap.caseInsensitiveMultiMap();
multiMap.add("name", "yitian");
multiMap.add("age", "25");
webClient.post("httpbin.org", "/post")
        .sendForm(multiMap, ar -> {
            if (ar.succeeded()) {
                HttpResponse<Buffer> response = ar.result();
                System.out.println(response.body());
            }
        });

預設表單使用application/x-www-form-urlencoded型別的Content Type傳送，也可以修改成multipart/form-data型別。

client
  .post(8080, "myserver.mycompany.com", "/some-uri")
  .putHeader("content-type", "multipart/form-data")
  .sendForm(form, ar -> {
    if (ar.succeeded()) {
      // Ok
    }
  });

目前上傳檔案還不支援，將會在以後的版本中支援上傳檔案。

修改請求頭

可以新增和修改要傳送的請求頭。

HttpRequest<Buffer> request = client.get(8080, "myserver.mycompany.com", "/some-uri");
MultiMap headers = request.headers();
headers.set("content-type", "application/json");
headers.set("other-header", "foo");

也可以呼叫putHeader方法直接新增請求頭。

HttpRequest<Buffer> request = client.get(8080, "myserver.mycompany.com", "/some-uri");
request.putHeader("content-type", "application/json");
request.putHeader("other-header", "foo");

重用請求

如果需要對同一個地址發起多次請求，我們可以設定一次請求，然後重複使用它。

HttpRequest<Buffer> get = client.get(8080, "myserver.mycompany.com", "/some-uri");
get.send(ar -> {
  if (ar.succeeded()) {
    // Ok
  }
});

// 重複使用
get.send(ar -> {
  if (ar.succeeded()) {
    // Ok
  }
});

超時

發起請求的時候可以設定超時值，單位是毫秒。

client
  .get(8080, "myserver.mycompany.com", "/some-uri")
  .timeout(5000)
  .send(ar -> {
    if (ar.succeeded()) {
      // Ok
    } else {
      // Might be a timeout when cause is java.util.concurrent.TimeoutException
    }
  });

處理請求

處理請求也是非同步的。這裡的ar型別實際是AsyncResult的型別，代表非同步結果。如果結果成功了，呼叫result()方法返回HttpResponse<Buffer>型別物件，這就是我們發起請求的結果，呼叫statusCode()、body()等方法就可以檢視相應結果了。

webClient.get("www.baidu.com", "/")
        .send(ar -> {
            if (ar.succeeded()) {
                HttpResponse<Buffer> response = ar.result();
                System.out.println(response.body());
            } else {
                System.out.println(ar.cause());
            }
        });

解碼響應

前面的響應是以Buffer形式返回的。如果我們確定響應是普通字串、Json物件、可以和Json對映的POJO類以及WriteStream，我們還可以解碼響應。例如下面就將響應體解碼為了JsonObject物件。

webClient.post("httpbin.org", "/post")
        .as(BodyCodec.jsonObject())
        .sendBuffer(Buffer.buffer("name=yitian&age=25"), ar -> {
            if (ar.succeeded()) {
                HttpResponse<JsonObject> response = ar.result();
                System.out.println(response.body());
            }
        });

BodyCodec類還有另外幾個方法，可以將響應體解碼為不同型別。假如響應體比較大，可以直接將響應體轉換為輸出流，以後慢慢讀取。

client
  .get(8080, "myserver.mycompany.com", "/some-uri")
  .as(BodyCodec.pipe(writeStream))
  .send(ar -> {
    if (ar.succeeded()) {

      HttpResponse<Void> response = ar.result();

      System.out.println("Received response with status code" + response.statusCode());
    } else {
      System.out.println("Something went wrong " + ar.cause().getMessage());
    }
  });

如果確定不需要響應體，可以直接用none()方法扔掉響應體。

client
  .get(8080, "myserver.mycompany.com", "/some-uri")
  .as(BodyCodec.none())
  .send(ar -> {
    if (ar.succeeded()) {

      HttpResponse<Void> response = ar.result();

      System.out.println("Received response with status code" + response.statusCode());
    } else {
      System.out.println("Something went wrong " + ar.cause().getMessage());
    }
  });

當然，如果響應體還是解碼為Buffer，我們仍然可以呼叫bodyAsXXX方法來解碼響應體。這種方法僅適用於Buffer響應體。

client
  .get(8080, "myserver.mycompany.com", "/some-uri")
  .send(ar -> {
    if (ar.succeeded()) {

      HttpResponse<Buffer> response = ar.result();

      // Decode the body as a json object
      JsonObject body = response.bodyAsJsonObject();

      System.out.println("Received response with status code" + response.statusCode() + " with body " + body);
    } else {
      System.out.println("Something went wrong " + ar.cause().getMessage());
    }
  });

使用HTTPS

前面使用的都是普通的HTTP，如果要使用HTTPS連線也很容易，將埠號指定為443即可。

client
  .get(443, "myserver.mycompany.com", "/some-uri")
  .ssl(true)
  .send(ar -> {
    if (ar.succeeded()) {
      // Obtain response
      HttpResponse<Buffer> response = ar.result();

      System.out.println("Received response with status code" + response.statusCode());
    } else {
      System.out.println("Something went wrong " + ar.cause().getMessage());
    }
  });

或者使用絕對路徑標誌的URI也可以。

client
  .getAbs("https://myserver.mycompany.com:4043/some-uri")
  .send(ar -> {
    if (ar.succeeded()) {
      // Obtain response
      HttpResponse<Buffer> response = ar.result();

      System.out.println("Received response with status code" + response.statusCode());
    } else {
      System.out.println("Something went wrong " + ar.cause().getMessage());
    }
  });

官方文件的最後還介紹了RxJava的一些整合。不過由於我還沒學習過RxJava，所以這部分就不介紹了。有興趣的同學可以查閱相關資料來進行自學。