1. Overview
1.概述
In this article, we’ll discuss Vert.x, cover its core concepts and create a simple RESTfull web service with it.
在这篇文章中，我们将讨论Vert.x，涵盖其核心概念，并利用它创建一个简单的RESTfull Web服务。
We’ll start by covering the foundation concepts about the toolkit, slowly move forward to an HTTP server and then build the RESTfull service.
我们将从工具包的基础概念开始，慢慢推进到HTTP服务器，然后建立RESTfull服务。
2. About Vert.x
2.关于Vert.x
Vert.x is an open source, reactive and polyglot software development toolkit from the developers of Eclipse.
Vert.x是一个开源的、反应式的和多语言的软件开发工具包，来自Eclipse的开发者。
Reactive programming is a programming paradigm, associated with asynchronous streams, which respond to any changes or events.
反应式编程是一种编程范式，与异步流有关，它对任何变化或事件作出反应。
Similarly, Vert.x uses an event bus, to communicate with different parts of the application and passes events, asynchronously to handlers when they available.
同样，Vert.x使用一个事件总线，与应用程序的不同部分进行通信，并在事件可用时异步传递给处理程序。
We call it polyglot due to its support for multiple JVM and non-JVM languages like Java, Groovy, Ruby, Python, and JavaScript.
由于它支持多种JVM和非JVM语言，如Java、Groovy、Ruby、Python和JavaScript，所以我们称之为polyglot。
3. Setup
3.设置
To use Vert.x we need to add the Maven dependency:
要使用Vert.x，我们需要添加Maven的依赖性。
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-core</artifactId>
<version>3.4.1</version>
</dependency>The latest version of the dependency can be found here.
最新版本的依赖性可以在这里找到。
3. Verticles
3.垂直线
Verticles are pieces of code that Vert.x engine executes. The toolkit provides us many abstract verticle class, which can be extended, and implemented as we want to.
Verticle是Vert.x引擎执行的代码片段。工具包为我们提供了许多抽象的垂直点类，它们可以被扩展，并按照我们的意愿来实现。
Being polyglot, verticles can be written in any of the supported languages. An application would typically be composed of multiple verticles running in the same Vert.x instance and communicate with each other using events via the event bus.
由于是多语种，verticles可以用任何支持的语言编写。一个应用程序通常由运行在同一Vert.x实例中的多个verticle组成，并通过事件总线使用事件进行相互通信。
To create a verticle in JAVA, the class must implement io.vertx.core.Verticle interface, or any one of its subclasses.
要在JAVA中创建一个垂直物体，该类必须实现io.vertx.core.Verticle接口，或其任意一个子类。
4. Event Bus
4.活动巴士
It is the nerve system of any Vert.x application.
它是任何Vert.x应用程序的神经系统。
Being reactive, verticles remain dormant until they receive a message or event. Verticles communicate with each other through the event bus. The message can be anything from a string to a complex object.
作为反应式，顶点在收到消息或事件之前一直处于休眠状态。顶点通过事件总线相互沟通。消息可以是任何东西，从一个字符串到一个复杂的对象。
Message handling is ideally asynchronous, messages are queued to the event bus, and control is returned to the sender. Later it’s dequeued to the listening verticle. The response is sent using Future and callback methods.
消息处理最好是异步的，消息被排到事件总线上，控制被返回给发送者。后来，它又被排到了监听顶层。响应是使用Future 和callback 方法发送的。
5. Simple Vert.x Application
5.简单的Vert.x应用程序
Let’s create a simple application with a verticle and deploy it using a vertx instance. To create our verticle, we’ll extend the
让我们创建一个带有垂直面的简单应用程序，并使用vertx实例进行部署。为了创建我们的垂直体，我们将扩展
To create our verticle, we’ll extend the io.vertx.core.AbstractVerticle class and override the start() method:
为了创建我们的垂直线，我们将扩展io.vertx.core.AbstractVerticle类并重载start()方法。
public class HelloVerticle extends AbstractVerticle {
@Override
public void start(Future<Void> future) {
LOGGER.info("Welcome to Vertx");
}
}The start() method will be invoked by the vertx instance when the verticle is deployed. The method takes io.vertx.core.Future as a parameter, which can be used to discover the status of an asynchronous deployment of the verticle.
start() 方法将由vertx 实例在垂直物体被部署时调用。该方法以io.vertx.core.Future为参数，可用于发现垂直体的异步部署的状态。
Now let’s deploy the verticle:
现在我们来部署垂直方向。
public static void main(String[] args) {
Vertx vertx = Vertx.vertx();
vertx.deployVerticle(new HelloVerticle());
}Similarly, we can override the stop() method from the AbstractVerticle class, which will be invoked while shutting down the verticle:
同样地，我们可以从AbstractVerticle类中重载stop()方法，该方法将在关闭垂直体时被调用。
@Override
public void stop() {
LOGGER.info("Shutting down application");
}6. HTTP Server
6.HTTP服务器
Now let’s spin up an HTTP server using a verticle:
现在，让我们用一个垂直仪来旋转一个HTTP服务器。
@Override
public void start(Future<Void> future) {
vertx.createHttpServer()
.requestHandler(r -> r.response().end("Welcome to Vert.x Intro");
})
.listen(config().getInteger("http.port", 9090),
result -> {
if (result.succeeded()) {
future.complete();
} else {
future.fail(result.cause());
}
});
}We have overridden the start() method to create an HTTP server and attached a request handler to it. The requestHandler() method is called every time the server receives a request.
我们重载了start() 方法来创建一个HTTP服务器，并给它附加了一个请求处理程序。每次服务器收到请求时，都会调用requestHandler()方法。
Finally, the server is bound to a port, and an AsyncResult<HttpServer> handler is passed to the listen() method whether or not the connection or the server startup is succeeded using future.complete() or future.fail() in the case of any errors.
最后，服务器被绑定到一个端口，并且一个AsyncResult<HttpServer>处理程序被传递给listen()方法，无论连接或服务器启动是否成功，使用future.complete()或future.fail()在任何错误情况下。
Note that: config.getInteger() method, is reading the value for HTTP port configuration which is being loaded from an external conf.json file.
请注意。config.getInteger()方法，正在读取HTTP端口配置的值，该配置正在从外部conf.json文件中加载。
Let’s test our server:
让我们测试一下我们的服务器。
@Test
public void whenReceivedResponse_thenSuccess(TestContext testContext) {
Async async = testContext.async();
vertx.createHttpClient()
.getNow(port, "localhost", "/", response -> {
response.handler(responseBody -> {
testContext.assertTrue(responseBody.toString().contains("Hello"));
async.complete();
});
});
}For the test, let’s use vertx-unit along with JUnit.:
对于测试，让我们使用vertx-unit和JUnit。
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-unit</artifactId>
<version>3.4.1</version>
<scope>test</scope>
</dependency>We can get the latest version here.
我们可以在这里获得最新版本。
The verticle is deployed and in a vertx instance in the setup() method of the unit test:
在单元测试的setup()方法中，垂直体被部署并在一个vertx实例中。
@Before
public void setup(TestContext testContext) {
vertx = Vertx.vertx();
vertx.deployVerticle(SimpleServerVerticle.class.getName(),
testContext.asyncAssertSuccess());
}Similarly, the vertx instance is closed in the @AfterClass tearDown() method:
同样地，vertx 实例在@AfterClass tearDown() 方法中被关闭。
@After
public void tearDown(TestContext testContext) {
vertx.close(testContext.asyncAssertSuccess());
}Notice that the @BeforeClass setup() method takes an TestContext argument. This helps up in controlling and testing the asynchronous behavior of the test. For example, the verticle deployment is async, so basically we can’t test anything unless it’s deployed correctly.
注意，@BeforeClass setup() 方法需要一个TestContext 参数。这有助于控制和测试测试的异步行为。例如，垂直部署是异步的，所以基本上我们不能测试任何东西，除非它被正确部署。
We have a second parameter to the deployVerticle() method, testContext.asyncAssertSuccess(). This is used to know if the server is deployed correctly or any failures occurred. It waits for the future.complete() or future.fail() in the server verticle to be called. In the case of a failure, it fails the test.
我们为deployVerticle()方法提供了第二个参数，testContext.asyncAssertSuccess()。T这被用来了解服务器是否被正确部署或发生任何故障。它等待服务器中的future.complete() 或 future.fail() 被调用。在失败的情况下，它不能进行测试。
7. RESTful WebService
7.RESTful WebService
We have created an HTTP server, lets now use that to host an RESTfull WebService. In order do so we will need another Vert.x module called vertx-web. This gives a lot of additional features for web development on top of vertx-core.
我们已经创建了一个HTTP服务器，现在让我们用它来托管一个RESTfull WebService。为了做到这一点，我们需要另一个名为vertx-web的Vert.x模块。它在vertx-core的基础上为Web开发提供了很多额外的功能。
Let’s add the dependency to our pom.xml:
让我们把这个依赖关系添加到我们的pom.xml中：。
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-web</artifactId>
<version>3.4.1</version>
</dependency>We can find the latest version here.
7.1. Router and Routes
7.1.路由器和路由
Let’s create a router for our WebService. This router will take a simple route of GET method, and handler method getArtilces():
让我们为我们的WebService创建一个路由器。这个路由器将采用一个简单的GET方法，以及处理方法getArtilces()。
Router router = Router.router(vertx);
router.get("/api/baeldung/articles/article/:id")
.handler(this::getArticles);The getArticle() method is a simple method that returns new Article object:
getArticle()方法是一个简单的方法，返回新的Article对象。
private void getArticles(RoutingContext routingContext) {
String articleId = routingContext.request()
.getParam("id");
Article article = new Article(articleId,
"This is an intro to vertx", "baeldung", "01-02-2017", 1578);
routingContext.response()
.putHeader("content-type", "application/json")
.setStatusCode(200)
.end(Json.encodePrettily(article));
}A Router, when receives a request, looks for the matching route, and passes the request further. The routes having a handler method associated with it to do sumthing with the request.
一个路由器，当收到一个请求时，寻找匹配的路由，并进一步传递请求。路由有一个与之相关的处理方法，对请求进行处理。
In our case, the handler invokes the getArticle() method. It receives the routingContext object as an argument. Derives the path parameter id, and creates an Article object with it.
在我们的案例中，处理程序调用了getArticle() 方法。它接收routingContext对象作为一个参数。衍生出路径参数id，并用它创建一个Article对象。
In the last part of the method, let’s invoke the response() method on the routingContext object and put the headers, set the HTTP response code, and end the response using the JSON encoded article object.
在方法的最后部分，让我们在routingContext对象上调用response()方法，并放入头文件，设置HTTP响应代码，并使用JSON编码的article对象结束响应。
7.2. Adding Router to Server
7.2.将路由器添加到服务器
Now let’s add the router, created in the previous section to the HTTP server:
现在让我们把上一节中创建的路由器添加到HTTP服务器上。
vertx.createHttpServer()
.requestHandler(router::accept)
.listen(config().getInteger("http.port", 8080),
result -> {
if (result.succeeded()) {
future.complete();
} else {
future.fail(result.cause());
}
});Notice that we have added requestHandler(router::accept) to the server. This instructs the server, to invoke the accept() of the router object when any request is received.
注意，我们在服务器上添加了requestHandler(router::accept) 。这指示服务器，当收到任何请求时，调用router对象的accept() 。
Now let’s test our WebService:
现在让我们测试一下我们的WebService。
@Test
public void givenId_whenReceivedArticle_thenSuccess(TestContext testContext) {
Async async = testContext.async();
vertx.createHttpClient()
.getNow(8080, "localhost", "/api/baeldung/articles/article/12345",
response -> {
response.handler(responseBody -> {
testContext.assertTrue(
responseBody.toString().contains("\"id\" : \"12345\""));
async.complete();
});
});
}8. Packaging Vert.x Application
8.包装Vert.x应用程序
To package the application as a deployable Java Archive (.jar) let’s use Maven Shade plugin and the configurations in the execution tag:
为了将应用程序打包成可部署的Java Archive（.jar），我们使用Maven Shade插件和execution标签中的配置。
<configuration>
<transformers>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<manifestEntries>
<Main-Class>io.vertx.core.Starter</Main-Class>
<Main-Verticle>com.baeldung.SimpleServerVerticle</Main-Verticle>
</manifestEntries>
</transformer>
</transformers>
<artifactSet />
<outputFile>
${project.build.directory}/${project.artifactId}-${project.version}-app.jar
</outputFile>
</configuration>In the manifestEntries, Main-Verticle indicates the starting point of the application and the Main-Class is a Vert.x class which, creates the vertx instance and deploys the Main-Verticle.
在manifestEntries中，Main-Verticle表示应用程序的起点，Main-Class是一个Vert.x类，它创建vertx实例并部署Main-Verticle。
9. Conclusion
9.结论
In this introductory article, we discussed the Vert.x toolkit and its fundamental concepts. Saw how to create and HTTP server, with Vert.x and also an RESTFull WebService and showed how to test them using vertx-unit.
在这篇介绍性文章中，我们讨论了Vert.x工具箱和它的基本概念。看到了如何用Vert.x创建HTTP服务器和RESTFull WebService，并展示了如何用vertx-unit测试它们。
Finally packaged the application as an executable jar.
最后将应用程序打包成一个可执行的jar。
The complete implementation of the code snippets is available over on GitHub.
完整的代码片段的实现可在GitHub上获得，。