感兴趣的朋友，可以关注微信服务号“猿学堂社区”，或加入“猿学堂社区”微信交流群
版权声明：本文由作者自行翻译，未经作者授权，不得随意转发。
现代应用很少位于孤岛之上，因为它们需要与其它（分布式）应用和服务集成。集成通常采用API实现，这些API通过多功能的HTTP协议公开。
本章展示了如何使用Vert.x的HTTP客户端API与第三方Web服务集成。
6.1 场景：备份到GitHub Gist
GitHub Gist服务（https://gist.github.com/）因分享代码片段到全世界而广受欢迎。其它服务可以使用它，一个例子就是Medium publishing platform，在该平台，Gist链接使代码片段可以嵌入到出版物内部。
GitHub公开了一个详细的API用于获取、创建、更新和删除Gist。该API使用以http://api.github.com/开始的HTTPS端点和JSON荷载。
虽然许多操作使用OAuth认证从客户端获取授权，但在匿名的情况下创建Gist是可能的。我们将利用这个特征备份我们的wiki页面为Gist。
一个新的按钮将被添加到wiki index页面：
点击backup按钮将触发一个Gist的创建操作：
备份Gist由每个Wiki页面一个文件组成，内容是未加工的Markdown文本：
6.2 更新数据库服务
在我们深入Web客户端API，并执行到其它服务的HTTP请求之前，我们需要更新数据库服务API，一次性获取所有的Wiki页面。这相当于添加下面的SQL查询到db-queries.properties：
all-pages-data=select * from Pages
添加一个新的方法到WikiDatabaseService接口：
@Fluent
WikiDatabaseService fetchAllPagesData(Handler<AsyncResult<List<JsonObject>>> resultHandler);
WikiDatabaseServiceImpl中的实现如下：
@Override
public WikiDatabaseService fetchAllPagesData(Handler<AsyncResult<List<JsonObject>>> resultHandler) {
dbClient.query(sqlQueries.get(SqlQuery.ALL_PAGES_DATA), queryResult -> {
if (queryResult.succeeded()) {
resultHandler.handle(Future.succeededFuture(queryResult.result().getRows()));
} else {
LOGGER.error("Database query error", queryResult.cause());
resultHandler.handle(Future.failedFuture(queryResult.cause()));
}
});
return this;
}
6.3 Web客户端API
Vert.x核心库在vertx上下文对象提供了一个createHttpClient方法。io.vertx.core.http.HttpClient实例提供了底层的方法用于执行所有类型的HTTP请求，并对协议和事件流进行细粒度控制。
Web客户端API提供了一个简单的外观，尤其是简化了荷载的编组与解组。该API以一种新的依赖的形式出现：
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-web-client</artifactId>
<version>${vertx.version}</version>
</dependency>
以下是来自一个单元测试的样例用法。它启动一个HTTP服务器，然后使用Web客户端API执行一个HTTP GET请求，检查到服务器的请求是否成功：
@Test
public void start_http_server(TestContext context) {
Async async = context.async();
vertx.createHttpServer()
.requestHandler(req -> req.response().putHeader("Content-Type", "text/plain").end("Ok"))
.listen(8080,context.asyncAssertSuccess(server -> {
WebClient webClient = WebClient.create(vertx);
webClient.get(8080, "localhost", "/").send(ar -> {
if (ar.succeeded()) {
HttpResponse<Buffer> response = ar.result();
context.assertTrue(response.headers().contains("Content-Type"));
context.assertEquals("text/plain",response.getHeader("Content-Type"));
context.assertEquals("Ok", response.body().toString());
webClient.close();
async.complete();
} else {
async.resolve(Future.failedFuture(ar.cause()));
}
});
}));
}
6.4 创建匿名的Gist
我们首先创建一个Web客户端对象，然后向Gist API发出HTTP请求：
webClient = WebClient.create(vertx, new WebClientOptions()
.setSsl(true)
.setUserAgent("vert-x3"));
由于请求使用HTTPS构造，我们需要配置Web客户端支持SSL。
GitHub API需要一个有效的User-Agent头，并请求一个GitHub账号或者组织标识。我们复写默认的User-Agent为vert-x3，但是你可以选择你自己的值替代。
我们接下来修改HttpServerVerticle类中的Web路由配置，为触发备份添加一个新的路由：
router.get("/backup").handler(this::backupHandler);
该处理器的代码如下：
private void backupHandler(RoutingContext context) {
dbService.fetchAllPagesData(reply -> {
if (reply.succeeded()) {
JsonObject filesObject = new JsonObject();
JsonObject gistPayload = new JsonObject() ①
.put("files", filesObject)
.put("description", "A wiki backup")
.put("public", true);
reply.result().forEach(page -> {
JsonObject fileObject = new JsonObject(); ②
filesObject.put(page.getString("NAME"), fileObject);
fileObject.put("content", page.getString("CONTENT"));
});
webClient.post(443, "api.github.com", "/gists") ③
.putHeader("Accept", "application/vnd.github.v3+json") ④
.putHeader("Content-Type", "application/json")
.as(BodyCodec.jsonObject()) ⑤
.sendJsonObject(gistPayload, ar -> { ⑥
if (ar.succeeded()) {
HttpResponse<JsonObject> response = ar.result();
if (response.statusCode() == 201) {
context.put("backup_gist_url", response.body().getString("html_url")); ⑦
indexHandler(context);
} else {
StringBuilder message = new StringBuilder()
.append("Could not backup the wiki: ")
.append(response.statusMessage());
JsonObject body = response.body();
if (body != null) {
message.append(System.getProperty("line.separator"))
.append(body.encodePrettily());
}
LOGGER.error(message.toString());
context.fail(502);
}
} else {
Throwable err = ar.cause();
LOGGER.error("HTTP Client error", err);
context.fail(err);
}
});
} else {
context.fail(reply.cause());
}
});
}
① Gist创建的请求载荷（payload）是一个JSON文档，如GitHub API文档（https://developer.github.com/v3/gists/#create-a-gist）中所描述。
② 每个文件是载荷files对象中的一条记录，title为键，值为文本。
③ web客户端需要发出一个POST请求到443端口（HTTPS），路径必须为/gists。
④ 请求中强制包含一个Accept头，使用application/vnd.github.v3+json MIME类型，否则请求会失败。在下一行中指定有效载荷是JSON对象也很重要。
⑤ BodyCodec类提供了一个助手，明确规定将响应直接转换为Vert.x的JsonObject实例。它也可以使用BodyCodec#json(Class<T>)方法，将JSON数据将映射为一个Java对象，类型为T（底层使用了Jackson数据映射）。
⑥ sendJsonObject是一个助手方法，用于触发JSON载荷的HTTP请求。
⑦ 当成功时，我们可以通过JSON数据（html_url键）来获得新建Gist的用户友好的URL。
