Vert.x Java开发指南——第六章 与第三方的Web服务集成

第六章 与第三方的Web服务集成

版权声明：本文为博主自主翻译，转载请标明出处。 https://blog.csdn.net/elinespace/article/details/80558824

相应代码位于本指南仓库的step-5目录下。

现代应用很少位于孤岛之上，因为它们需要与其它（分布式）应用和服务集成。集成通常采用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)方法，将JSON数据将映射为一个Java对象，类型为T（底层使用了Jackson数据映射）。

⑥ sendJsonObject是一个助手方法，用于触发JSON载荷的HTTP请求。

⑦ 当成功时，我们可以通过JSON数据（html_url键）来获得新建Gist的用户友好的URL。