Vert.x Blueprint 系列教程(一) | 待办事项服务开发教程

摘要：本文章是蓝图系列的第一篇教程。是事件驱动的，同时也是非阻塞的。是一组负责分发和处理事件的线程。注意，我们绝对不能去阻塞线程，否则事件的处理过程会被阻塞，我们的应用就失去了响应能力。每个负责处理请求并且写入回应结果。

本文章是 Vert.x 蓝图系列 的第一篇教程。全系列：

Vert.x Blueprint 系列教程(一) | 待办事项服务开发教程

Vert.x Blueprint 系列教程(二) | 开发基于消息的应用 - Vert.x Kue 教程

Vert.x Blueprint 系列教程(三) | Micro-Shop 微服务应用实战

本系列已发布至Vert.x官网：Vert.x Blueprint Tutorials

在本教程中，我们会使用Vert.x来一步一步地开发一个REST风格的Web服务 - Todo Backend，你可以把它看作是一个简单的待办事项服务，我们可以自由添加或者取消各种待办事项。

通过本教程，你将会学习到以下的内容：

Vert.x 是什么，以及其基本设计思想

Verticle是什么，以及如何使用Verticle

如何用 Vert.x Web 来开发REST风格的Web服务

异步编程风格 的应用

如何通过 Vert.x 的各种组件来进行数据的存储操作（如 Redis 和 MySQL）

本教程是Vert.x 蓝图系列的第一篇教程，对应的Vert.x版本为3.3.0。本教程中的完整代码已托管至GitHub。

朋友，欢迎来到Vert.x的世界！初次听说Vert.x，你一定会非常好奇：这是啥？让我们来看一下Vert.x的官方解释：

Vert.x is a tool-kit for building reactive applications on the JVM.

(⊙o⊙)哦哦。。。翻译一下，Vert.x是一个在JVM上构建 响应式 应用的 工具集 。这个定义比较模糊，我们来简单解释一下：工具集 意味着Vert.x非常轻量，可以嵌入到你当前的应用中而不需要改变现有的结构；另一个重要的描述是 响应式 —— Vert.x就是为构建响应式应用（系统）而设计的。响应式系统这个概念在 Reactive Manifesto 中有详细的定义。我们在这里总结4个要点：

响应式的(Responsive)：一个响应式系统需要在 合理 的时间内处理请求。

弹性的(Resilient)：一个响应式系统必须在遇到 异常 （崩溃，超时， 500 错误等等）的时候保持响应的能力，所以它必须要为 异常处理 而设计。

可伸缩的(Elastic)：一个响应式系统必须在不同的负载情况下都要保持响应能力，所以它必须能伸能缩，并且可以利用最少的资源来处理负载。

消息驱动：一个响应式系统的各个组件之间通过 异步消息传递 来进行交互。

Vert.x是事件驱动的，同时也是非阻塞的。首先，我们来介绍 Event Loop 的概念。Event Loop是一组负责分发和处理事件的线程。注意，我们绝对不能去阻塞Event Loop线程，否则事件的处理过程会被阻塞，我们的应用就失去了响应能力。因此当我们在写Vert.x应用的时候，我们要时刻谨记 异步非阻塞开发模式 而不是传统的阻塞开发模式。我们将会在下面详细讲解异步非阻塞开发模式。

我们的应用是一个REST风格的待办事项服务，它非常简单，整个API其实就围绕着 增删改查 四种操作。所以我们可以设计以下的路由：

添加待办事项: POST /todos

获取某一待办事项: GET /todos/:todoId

获取所有待办事项: GET /todos

更新待办事项: PATCH /todos/:todoId

删除某一待办事项: DELETE /todos/:todoId

删除所有待办事项: DELETE /todos

注意我们这里不讨论REST风格API的设计规范（仁者见仁,智者见智），因此你也可以用你喜欢的方式去定义路由。

下面我们开始开发我们的项目！High起来～～～

Vert.x Core提供了一些较为底层的处理HTTP请求的功能，这对于Web开发来说不是很方便，因为我们通常不需要这么底层的功能，因此Vert.x Web应运而生。Vert.x Web基于Vert.x Core，并且提供一组更易于创建Web应用的上层功能（如路由）。

首先我们先来创建我们的项目。在本教程中我们使用Gradle作为构建工具，当然你也可以使用其它诸如Maven之类的构建工具。我们的项目目录里需要有：

src/main/java 文件夹（源码目录）

src/test/java 文件夹（测试目录）

build.gradle 文件（Gradle配置文件）

.
├── build.gradle
├── settings.gradle
├── src
│   ├── main
│   │   └── java
│   └── test
│       └── java

我们首先来创建 build.gradle 文件，这是Gradle对应的配置文件：

apply plugin: "java"

targetCompatibility = 1.8
sourceCompatibility = 1.8

repositories {
  mavenCentral()
  mavenLocal()
}

dependencies {

  compile "io.vertx:vertx-core:3.3.0"
  compile "io.vertx:vertx-web:3.3.0"

  testCompile "io.vertx:vertx-unit:3.3.0"
  testCompile group: "junit", name: "junit", version: "4.12"
}

你可能不是很熟悉Gradle，这不要紧。我们来解释一下：

我们将 targetCompatibility 和 sourceCompatibility 这两个值都设为1.8，代表目标Java版本是Java 8。这非常重要，因为Vert.x就是基于Java 8构建的。

在dependencies中，我们声明了我们需要的依赖。vertx-core 和 vert-web 用于开发REST API。

注： 若国内用户出现用Gradle解析依赖非常缓慢的情况，可以尝试使用开源中国Maven镜像代替默认的镜像（有的时候速度比较快）。只要在build.gradle中配置即可：

repositories {
    maven {
            url "http://maven.oschina.net/content/groups/public/"
        }
    mavenLocal()
}

搞定build.gradle以后，我们开始写代码！

首先我们需要创建我们的数据实体对象 - Todo 实体。在io.vertx.blueprint.todolist.entity包下创建Todo类，并且编写以下代码：

package io.vertx.blueprint.todolist.entity;

import io.vertx.codegen.annotations.DataObject;
import io.vertx.core.json.JsonObject;

import java.util.concurrent.atomic.AtomicInteger;


@DataObject(generateConverter = true)
public class Todo {

  private static final AtomicInteger acc = new AtomicInteger(0); // counter

  private int id;
  private String title;
  private Boolean completed;
  private Integer order;
  private String url;

  public Todo() {
  }

  public Todo(Todo other) {
    this.id = other.id;
    this.title = other.title;
    this.completed = other.completed;
    this.order = other.order;
    this.url = other.url;
  }

  public Todo(JsonObject obj) {
    TodoConverter.fromJson(obj, this); // 还未生成Converter的时候需要先注释掉，生成过后再取消注释
  }

  public Todo(String jsonStr) {
    TodoConverter.fromJson(new JsonObject(jsonStr), this);
  }

  public Todo(int id, String title, Boolean completed, Integer order, String url) {
    this.id = id;
    this.title = title;
    this.completed = completed;
    this.order = order;
    this.url = url;
  }

  public JsonObject toJson() {
    JsonObject json = new JsonObject();
    TodoConverter.toJson(this, json);
    return json;
  }

  public int getId() {
    return id;
  }

  public void setId(int id) {
    this.id = id;
  }

  public void setIncId() {
    this.id = acc.incrementAndGet();
  }

  public static int getIncId() {
    return acc.get();
  }

  public static void setIncIdWith(int n) {
    acc.set(n);
  }

  public String getTitle() {
    return title;
  }

  public void setTitle(String title) {
    this.title = title;
  }

  public Boolean isCompleted() {
    return getOrElse(completed, false);
  }

  public void setCompleted(Boolean completed) {
    this.completed = completed;
  }

  public Integer getOrder() {
    return getOrElse(order, 0);
  }

  public void setOrder(Integer order) {
    this.order = order;
  }

  public String getUrl() {
    return url;
  }

  public void setUrl(String url) {
    this.url = url;
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;

    Todo todo = (Todo) o;

    if (id != todo.id) return false;
    if (!title.equals(todo.title)) return false;
    if (completed != null ? !completed.equals(todo.completed) : todo.completed != null) return false;
    return order != null ? order.equals(todo.order) : todo.order == null;

  }

  @Override
  public int hashCode() {
    int result = id;
    result = 31 * result + title.hashCode();
    result = 31 * result + (completed != null ? completed.hashCode() : 0);
    result = 31 * result + (order != null ? order.hashCode() : 0);
    return result;
  }

  @Override
  public String toString() {
    return "Todo -> {" +
      "id=" + id +
      ", title="" + title + """ +
      ", completed=" + completed +
      ", order=" + order +
      ", url="" + url + """ +
      "}";
  }

  private  T getOrElse(T value, T defaultValue) {
    return value == null ? defaultValue : value;
  }

  public Todo merge(Todo todo) {
    return new Todo(id,
      getOrElse(todo.title, title),
      getOrElse(todo.completed, completed),
      getOrElse(todo.order, order),
      url);
  }
}

我们的 Todo 实体对象由序号id、标题title、次序order、地址url以及代表待办事项是否完成的一个标识complete组成。我们可以把它看作是一个简单的Java Bean。它可以被编码成JSON格式的数据，我们在后边会大量使用JSON（事实上，在Vert.x中JSON非常普遍）。同时注意到我们给Todo类加上了一个注解：@DataObject，这是用于生成JSON转换类的注解。

DataObject 注解
被 @DataObject 注解的实体类需要满足以下条件：拥有一个拷贝构造函数以及一个接受一个 JsonObject 对象的构造函数。

我们利用Vert.x Codegen来自动生成JSON转换类。我们需要在build.gradle中添加依赖：

compile "io.vertx:vertx-codegen:3.3.0"

同时，我们需要在io.vertx.blueprint.todolist.entity包中添加package-info.java文件来指引Vert.x Codegen生成代码：

/**
 * Indicates that this module contains classes that need to be generated / processed.
 */
@ModuleGen(name = "vertx-blueprint-todo-entity", groupPackage = "io.vertx.blueprint.todolist.entity")
package io.vertx.blueprint.todolist.entity;

import io.vertx.codegen.annotations.ModuleGen;

Vert.x Codegen本质上是一个注解处理器(annotation processing tool)，因此我们还需要在build.gradle中配置apt。往里面添加以下代码：

task annotationProcessing(type: JavaCompile, group: "build") {
  source = sourceSets.main.java
  classpath = configurations.compile
  destinationDir = project.file("src/main/generated")
  options.compilerArgs = [
    "-proc:only",
    "-processor", "io.vertx.codegen.CodeGenProcessor",
    "-AoutputDirectory=${destinationDir.absolutePath}"
  ]
}

sourceSets {
  main {
    java {
      srcDirs += "src/main/generated"
    }
  }
}

compileJava {
  targetCompatibility = 1.8
  sourceCompatibility = 1.8

  dependsOn annotationProcessing
}

这样，每次我们在编译项目的时候，Vert.x Codegen都会自动检测含有 @DataObject 注解的类并且根据配置生成JSON转换类。在本例中，我们应该会得到一个 TodoConverter 类，然后我们可以在Todo类中使用它。

下面我们来写我们的应用组件。在io.vertx.blueprint.todolist.verticles包中创建SingleApplicationVerticle类，并编写以下代码：

package io.vertx.blueprint.todolist.verticles;

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Future;
import io.vertx.redis.RedisClient;
import io.vertx.redis.RedisOptions;

public class SingleApplicationVerticle extends AbstractVerticle {

  private static final String HTTP_HOST = "0.0.0.0";
  private static final String REDIS_HOST = "127.0.0.1";
  private static final int HTTP_PORT = 8082;
  private static final int REDIS_PORT = 6379;

  private RedisClient redis;

  @Override
  public void start(Future future) throws Exception {
      // TODO with start...
  }
}

我们的SingleApplicationVerticle类继承了AbstractVerticle抽象类。那么什么是 Verticle 呢？在Vert.x中，一个Verticle代表应用的某一组件。我们可以通过部署Verticle来运行这些组件。如果你了解 Actor 模型的话，你会发现它和Actor非常类似。

当Verticle被部署的时候，其start方法会被调用。我们注意到这里的start方法接受一个类型为Future的参数，这代表了这是一个异步的初始化方法。这里的Future代表着Verticle的初始化过程是否完成。你可以通过调用Future的complete方法来代表初始化过程完成，或者fail方法代表初始化过程失败。

现在我们Verticle的轮廓已经搞好了，那么下一步也就很明了了 - 创建HTTP Client并且配置路由，处理HTTP请求。

我们来给start方法加点东西：

@Override
public void start(Future future) throws Exception {
  initData();
  Router router = Router.router(vertx); // <1>
  // CORS support
  Set allowHeaders = new HashSet<>();
  allowHeaders.add("x-requested-with");
  allowHeaders.add("Access-Control-Allow-Origin");
  allowHeaders.add("origin");
  allowHeaders.add("Content-Type");
  allowHeaders.add("accept");
  Set allowMethods = new HashSet<>();
  allowMethods.add(HttpMethod.GET);
  allowMethods.add(HttpMethod.POST);
  allowMethods.add(HttpMethod.DELETE);
  allowMethods.add(HttpMethod.PATCH);

  router.route().handler(CorsHandler.create("*") // <2>
    .allowedHeaders(allowHeaders)
    .allowedMethods(allowMethods));
  router.route().handler(BodyHandler.create()); // <3>

  // TODO:routes

  vertx.createHttpServer() // <4>
    .requestHandler(router::accept)
    .listen(PORT, HOST, result -> {
        if (result.succeeded())
          future.complete();
        else
          future.fail(result.cause());
      });
}

(⊙o⊙)…一长串代码诶。。是不是看着很晕呢？我们来详细解释一下。

首先我们创建了一个 Router 实例 （1）。这里的Router代表路由器，相信做过Web开发的开发者们一定不会陌生。路由器负责将对应的HTTP请求分发至对应的处理逻辑（Handler）中。每个Handler负责处理请求并且写入回应结果。当HTTP请求到达时，对应的Handler会被调用。

然后我们创建了两个Set：allowHeaders和allowMethods，并且我们向里面添加了一些HTTP Header以及HTTP Method，然后我们给路由器绑定了一个CorsHandler （2）。route()方法（无参数）代表此路由匹配所有请求。这两个Set的作用是支持 CORS，因为我们的API需要开启CORS以便配合前端正常工作。有关CORS的详细内容我们就不在这里细说了，详情可以参考这里。我们这里只需要知道如何开启CORS支持即可。

接下来我们给路由器绑定了一个全局的BodyHandler （3），它的作用是处理HTTP请求正文并获取其中的数据。比如，在实现添加待办事项逻辑的时候，我们需要读取请求正文中的JSON数据，这时候我们就可以用BodyHandler。

最后，我们通过vertx.createHttpServer()方法来创建一个HTTP服务端 （4）。注意这个功能是Vert.x Core提供的底层功能之一。然后我们将我们的路由处理器绑定到服务端上，这也是Vert.x Web的核心。你可能不熟悉router::accept这样的表示，这是Java 8中的 方法引用，它相当于一个分发路由的Handler。当有请求到达时，Vert.x会调用accept方法。然后我们通过listen方法监听8082端口。因为创建服务端的过程可能失败，因此我们还需要给listen方法传递一个Handler来检查服务端是否创建成功。正如我们前面所提到的，我们可以使用future.complete来表示过程成功，或者用future.fail来表示过程失败。

到现在为止，我们已经创建好HTTP服务端了，但我们还没有见到任何的路由呢！不要着急，是时候去声明路由了！

下面我们来声明路由。正如我们之前提到的，我们的路由可以设计成这样：

添加待办事项: POST /todos

获取某一待办事项: GET /todos/:todoId

获取所有待办事项: GET /todos

更新待办事项: PATCH /todos/:todoId

删除某一待办事项: DELETE /todos/:todoId

删除所有待办事项: DELETE /todos

路径参数

在URL中，我们可以通过:name的形式定义路径参数。当处理请求的时候，Vert.x会自动获取这些路径参数并允许我们访问它们。拿我们的路由举个例子，/todos/19 将 todoId 映射为 19。

首先我们先在 io.vertx.blueprint.todolist 包下创建一个Constants类用于存储各种全局常量（当然也可以放到其对应的类中）：

package io.vertx.blueprint.todolist;

public final class Constants {

  private Constants() {}

  /** API Route */
  public static final String API_GET = "/todos/:todoId";
  public static final String API_LIST_ALL = "/todos";
  public static final String API_CREATE = "/todos";
  public static final String API_UPDATE = "/todos/:todoId";
  public static final String API_DELETE = "/todos/:todoId";
  public static final String API_DELETE_ALL = "/todos";

}

然后我们将start方法中的TODO标识处替换为以下的内容：

// routes
router.get(Constants.API_GET).handler(this::handleGetTodo);
router.get(Constants.API_LIST_ALL).handler(this::handleGetAll);
router.post(Constants.API_CREATE).handler(this::handleCreateTodo);
router.patch(Constants.API_UPDATE).handler(this::handleUpdateTodo);
router.delete(Constants.API_DELETE).handler(this::handleDeleteOne);
router.delete(Constants.API_DELETE_ALL).handler(this::handleDeleteAll);

代码很直观、明了。我们用对应的方法（如get,post,patch等等）将路由路径与路由器绑定，并且我们调用handler方法给每个路由绑定上对应的Handler，接受的Handler类型为Handler。这里我们分别绑定了六个方法引用，它们的形式都类似于这样：

private void handleRequest(RoutingContext context) {
    // ...
}

我们将在稍后实现这六个方法，这也是我们待办事项服务逻辑的核心。

我们之前提到过，Vert.x是 异步、非阻塞的 。每一个异步的方法总会接受一个 Handler 参数作为回调函数，当对应的操作完成时会调用接受的Handler，这是异步方法的一种实现。还有一种等价的实现是返回Future对象：

void doAsync(A a, B b, Handler handler);
// 这两种实现等价
Future doAsync(A a, B b);

其中，Future 对象代表着一个操作的结果，这个操作可能还没有进行，可能正在进行，可能成功也可能失败。当操作完成时，Future对象会得到对应的结果。我们也可以通过setHandler方法给Future绑定一个Handler，当Future被赋予结果的时候，此Handler会被调用。

Future future = doAsync(A a, B b);
future.setHandler(r -> {
    if (r.failed()) {
        // 处理失败
    } else {
        // 操作结果
    }
});

Vert.x中大多数异步方法都是基于Handler的。而在本教程中，这两种异步模式我们都会接触到。

现在是时候来实现我们的待办事项业务逻辑了！这里我们使用 Redis 作为数据持久化存储。有关Redis的详细介绍请参照Redis 官方网站。Vert.x给我们提供了一个组件—— Vert.x-redis，允许我们以异步的形式操作Redis数据。

如何安装Redis？ | 请参照Redis官方网站上详细的安装指南。

Vert.x Redis允许我们以异步的形式操作Redis数据。我们首先需要在build.gradle中添加以下依赖：

compile "io.vertx:vertx-redis-client:3.3.0"

我们通过RedisClient对象来操作Redis中的数据，因此我们定义了一个类成员redis。在使用RedisClient之前，我们首先需要与Redis建立连接，并且需要配置（以RedisOptions的形式），后边我们再讲需要配置哪些东西。

我们来实现 initData 方法用于初始化 RedisClient 并且测试连接：

private void initData() {
  RedisOptions config = new RedisOptions()
      .setHost(config().getString("redis.host", REDIS_HOST)) // redis host
      .setPort(config().getInteger("redis.port", REDIS_PORT)); // redis port

  this.redis = RedisClient.create(vertx, config); // create redis client

  redis.hset(Constants.REDIS_TODO_KEY, "24", Json.encodePrettily( // test connection
    new Todo(24, "Something to do...", false, 1, "todo/ex")), res -> {
    if (res.failed()) {
      System.err.println("[Error] Redis service is not running!");
      res.cause().printStackTrace();
    }
  });

}

当我们在加载Verticle的时候，我们会首先调用initData方法，这样可以保证RedisClient可以被正常创建。

我们知道，Redis支持各种格式的数据，并且支持多种方式存储（如list、hash map等）。这里我们将我们的待办事项存储在 哈希表(map) 中。我们使用待办事项的id作为key，JSON格式的待办事项数据作为value。同时，我们的哈希表本身也要有个key，我们把它命名为 VERT_TODO，并且存储到Constants类中：

public static final String REDIS_TODO_KEY = "VERT_TODO";

正如我们之前提到的，我们利用了生成的JSON数据转换类来实现Todo实体与JSON数据之间的转换（通过几个构造函数），在后面实现待办事项服务的时候可以广泛利用。

我们首先来实现获取待办事项的逻辑。正如我们之前所提到的，我们的处理逻辑方法需要接受一个RoutingContext类型的参数。我们看一下获取某一待办事项的逻辑方法(handleGetTodo)：

private void handleGetTodo(RoutingContext context) {
  String todoID = context.request().getParam("todoId"); // (1)
  if (todoID == null)
    sendError(400, context.response()); // (2)
  else {
    redis.hget(Constants.REDIS_TODO_KEY, todoID, x -> { // (3)
      if (x.succeeded()) {
        String result = x.result();
        if (result == null)
          sendError(404, context.response());
        else {
          context.response()
            .putHeader("content-type", "application/json")
            .end(result); // (4)
        }
      } else
        sendError(503, context.response());
    });
  }
}

首先我们先通过getParam方法获取路径参数todoId (1)。我们需要检测路径参数获取是否成功，如果不成功就返回 400 Bad Request 错误 (2)。这里我们写一个函数封装返回错误response的逻辑：

private void sendError(int statusCode, HttpServerResponse response) {
  response.setStatusCode(statusCode).end();
}

这里面，end方法是非常重要的。只有我们调用end方法时，对应的HTTP Response才能被发送回客户端。

再回到handleGetTodo方法中。如果我们成功获取到了todoId，我们可以通过hget操作从Redis中获取对应的待办事项 (3)。hget代表通过key从对应的哈希表中获取对应的value，我们来看一下hget函数的定义：

RedisClient hget(String key, String field, Handler> handler);

第一个参数key对应哈希表的key，第二个参数field代表待办事项的key，第三个参数代表当获取操作成功时对应的回调。在Handler中，我们首先检查操作是否成功，如果不成功就返回503错误。如果成功了，我们就可以获取操作的结果了。结果是null的话，说明Redis中没有对应的待办事项，因此我们返回404 Not Found代表不存在。如果结果存在，那么我们就可以通过end方法将其写入response中 (4)。注意到我们所有的RESTful API都返回JSON格式的数据，所以我们将content-type头设为JSON。

获取所有待办事项的逻辑handleGetAll与handleGetTodo大体上类似，但实现上有些许不同：

private void handleGetAll(RoutingContext context) {
  redis.hvals(Constants.REDIS_TODO_KEY, res -> { // (1)
    if (res.succeeded()) {
      String encoded = Json.encodePrettily(res.result().stream() // (2)
        .map(x -> new Todo((String) x))
        .collect(Collectors.toList()));
      context.response()
        .putHeader("content-type", "application/json")
        .end(encoded); // (3)
    } else
      sendError(503, context.response());
  });
}

这里我们通过hvals操作 (1) 来获取某个哈希表中的所有数据（以JSON数组的形式返回，即JsonArray对象）。在Handler中我们还是像之前那样先检查操作是否成功。如果成功的话我们就可以将结果写入response了。注意这里我们不能直接将返回的JsonArray写入response。想象一下返回的JsonArray包括着待办事项的key以及对应的JSON数据（字符串形式），因此此时每个待办事项对应的JSON数据都被转义了，所以我们需要先把这些转义过的JSON数据转换成实体对象，再重新编码。

我们这里采用了一种响应式编程思想的方法。首先我们了解到JsonArray类继承了Iterable