Vert.x-Web是用Vert.x创建Web应用程序的一组构建模块的集合。
可以将Vert.x想象成构建现代，伸缩we应用的瑞士军刀。Vert.x核心模块提供相当低层功能用于处理HTTP，和应用充分使用的功能。Vert.x-Web构建于Vert.x 核心模块之上，用于提供更丰富的构建真实web应用程序的功能集，并更加简单。
对于使用Vert.x 2.x的Yoke是成功的并且从Node.js世界中的Express框架和Ruby世界中的Sinatra获得灵感。
Vert.x-Web强在设计，灵活的并可以完全嵌入。使用你需要的的，其他都不需要。Vertx-Web不是容器。
可以使用 Vert.x-web创建经典的服务器侧Web应用程序，RESTfulweb应用程序，’实时(服务器推送)Web应用’,或者是你关心过的某些种类的web应用。Vert.x-Web不关心。应用的类型根据你的喜好决定，而不是由Vert.x-web决定。
Vert.x-Web非常适合编写RESTful HTTP微服务，但是Vert.x不强迫你像那样编写应用程序。
Vert.x-Web包含的一关键特性有：
-
路由(基于方法【get,post】,路径，等)
-
路径的正则表达式匹配
-
从路径中抽取参数
-
内容协商
-
请求体处理
-
请求和响应体大小限制
-
Cookie解析与处理
-
多部分表单（指有表单域和上传的表单）
-
多部分文件上传
-
子路由器
-
会话支持——包括本地（粘滞会话）和集群（非粘滞）
-
CORS（跨区域资源共享）支持
-
错误页处理
-
Basic认证
-
基于认证的重定向
-
JWt (Java Web Toolkit) 基本认证
-
用户/角色/权限认证
-
favicon（指浏览器页面上的图标）处理
-
模板支持服务端渲染，支持下列模板引擎
-
Handlebars
-
Jade
-
MVEL
-
Thymeleaf
-
-
响应时间处理器
-
静态文件提供，包括缓存逻辑和目录列表
-
请求超时处理
-
SockJS支持
-
事件总线桥
-
CSRF虚拟跨站请求
-
虚拟主机
Vert.x-web的大多数特性被实现成处理器，所以要以自己编写。随着时间推移，会在vert.x-web中添加更多内容。我们将在此手册中讨认所有这些特性。
使用Vert.xWeb
为了使用vert.x web模块，添加下列依赖项到构建文件的依赖管理节。
-
Maven(在项目的pom.xml文件中)
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-web</artifactId>
<version>3.2.1</version>
</dependency>
-
Gradle(在项目的build.gradle文件中)
dependencies {
compile 'io.vertx:vertx-web:3.2.1'
}
Vert.x内核HTT服务器回顾
Vert.x-Web使用Vert.x内核模块API，同时也暴露了一些内核模块的API。所以撑握Vert.x内核中的编写HTTP服务器的基本概念是有价值的，如是你还不知道。
Vert.x内核HTTP文档包含很多详细信息。
这是一个用Vert.x内核模块编写的helloworld web服务器。这里不涉及Vert.x-Web:
HttpServer server =vertx.createHttpServer();
server.requestHandler(request -> {
//This handler gets called for each request that arrives on the server
HttpServerResponse response = request.response();
response.putHeader("content-type", "text/plain");
//Write to the response and end it
response.end("Hello World!");
});
server.listen(8080);
我们创建了一个HTTP服务器实例，然后设置了一个请求处理器。无论什么时候，只要请求到达服务器，就会调用请求处理器。在请前到达到后，我们设置了Content-Type为text/plain，然后写入”Hello World!”并结束Response。
最后们们告诉服务器在8080端口上侦听请求(默认的主机是localhost)。
运行这段代码，让浏览器访问http://localhost:8080验正是否如我们期望的一样。
基本的Vert.x-Web概念
这是最基本的概念：
Router(路由器)是Vert.x-Web核心概念之一。它是一个维护零到多个路由的对象。
某个路由器将一个HTTP请求匹配到第一个发现的路由并将请求传给此路由。
route路由与一些处理器关联，这此处理器接收请求。然后在处理器中对请求进行处理或者结束它，或者将其传递给下一个匹配的处理器。
这是一个简单路由器的例子：
HttpServer server =vertx.createHttpServer();
Router router = Router.router(vertx);
router.route().handler(routingContext ->{
//This handler will be called for every request
HttpServerResponse response = routingContext.response();
response.putHeader("content-type", "text/plain");
//Write to the response and end it
response.end("Hello World from Vert.x-Web!");
});
server.requestHandler(router::accept).listen(8080);
这与前一节Vert.x内核模块的Helloworld的例子所做的事一样。但此时用的是Vert.x-Web。
如前面章节一样，我们创建了一个HTT服务器，然后我们创建了一个路由器。无参route方法创建了一个没有匹配条件的简单路由，所以此路由将匹配到达服务器的所有请求。然后我们为路由指定了一个处理器，所有的请求到达服务器时，者将调用此处理器。传入处理器的是一个RoutingContex对象，此对象包含了标准的Vert.x HttpServerRequest和HttpServerResponse对象，当然也包含一些使Vert.x-Webg易于使用其他对象。
对于被路由的每个请求，都有一个唯一的路由一下文实例，此实例被传给匹配此请求的所有处理器。一旦我们设置了处理器，Http服务器的所有请求处理器将把所有到来的请求传给accept方法。
这就是基本概念，现在我们来研究更多信息：
处理请求和调用下一个处理器
在Vert.x-Web决定路由一个请求到匹配的路由时，Vert.x-Web将传入一个RoutingContext实例，并调用路由处理器。
如果在此路由处理器中不结束响应，Vert.x-Web将会调用另一个能处理请求的匹配路由。在当前处理器执行完成之前，不必调用next方法调用下一个匹配地处理器。
如果我想那样做，可以在一段时间之后：
Route route1 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
//enable chunked responses because we will be adding data as
//we execute over other handlers. This is only required once and
//only if several handlers do output.
response.setChunked(true);
response.write("route1\n");
//Call the next matching route after a 5 second delay
routingContext.vertx().setTimer(5000, tid -> routingContext.next());
});
Route route2 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
response.write("route2\n");
//Call the next matching route after a 5 second delay
routingContext.vertx().setTimer(5000, tid -> routingContext.next());
});
Route route3 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
response.write("route3");
//Now end the response
routingContext.response().end();
});
在上面例子中，route1被写入到响应，5秒后，route2被写到响应，然后5秒后，route3被写入响应，最后响应结束。
注意:做这些都不会产生线程阻塞。
使用阻塞处理器
有时，可能在处理器中不得不做一个阻塞事件循环的事，例如调用遗留阻塞API或者做高密度的运算。在正常的处理器不能这样做，所以Vert.x-Web提供了在路由上设置阻塞处理器的的能力。一个阻塞处理器和正常处理器一样，但是由Vert.x从工作线程池中获取的线程调用，而不是用事件循环调用。用blockingHandler方法将阻塞处理器设置到路由上，这里有一个例子：
router.route().blockingHandler(routingContext-> {
//Do something that might take some time synchronously
service.doSomethingThatBlocks();
//Now call the next handler
routingContext.next();
});
默认的，一些阻塞处理器在同一个上下文中顺序执行（如，相同的verticle实例），这意味着上一个没有执行完成，下一个不会执行。如果你不用关心顺序也不在意处理器的并发执行，可以在使用blockingHandler时设置ordered为false。
根据确切路径路由
一个设置好的路由用来匹配请求RUI中的路径。这样，这样路由可以匹配与设置路径一样的任何请求。在下面的例子中，处理器将由路径为/some/path/的请求调用。路么由会忽视斜线，因为/some/path与/some/path//都会调用处理器：
Route route = router.route().path("/some/path/");
route.handler(routingContext -> {
//This handler will be called for the following request paths:
//`/some/path`
//`/some/path/`
//`/some/path//`
//
//but not:
//`/some/path/subdir`
});
路由匹配前缀的路径
通常需要路由所由以某个路径为前缀的所有请求。可以用正则表达式完成这样任务，一个简单的方法是在声明路由路径时，在路径最后使用*号占位符。在下面的例子里，任何以/some/path/开关的RUI路径都会调用例子中的处理器。例如/some/path/foo.html和/some/path/otherdir/blah.css都能匹配。
Route route =router.route().path("/some/path/*");
route.handler(routingContext -> {
//This handler will be called for any path that starts with
//`/some/path/`, e.g.
//`/some/path`
//`/some/path/`
//`/some/path/subdir`
//`/some/path/subdir/blah.html`
//
//but not:
//`/some/bath`
});
在创建路由的时候也可以指定任意路径:
Route route =router.route("/some/path/*");
route.handler(routingContext -> {
//This handler will be called same as previous example
});
获取路径参数
使用参数占位符匹配路径是可能的，这些参数可以通过请求的params方法获取。这是一个例子：
Route route = router.route(HttpMethod.POST,"/catalogue/products/:productype/:productid/");
route.handler(routingContext -> {
String productType = routingContext.request().getParam("producttype");
String productID =routingContext.request().getParam("productid");
//Do something with them...
});
占位符由跟在冒号后面的参数名组成。参数名称由一些字母，数字和下划线组成。在上面的例子中，一个POST请求发向路径:/catalogue/products/tools/drill123/，路由将会匹配到productType并得到值tools,productID将会收到值drill123。
使用正则表达式路由
在路由中正则表达也可以用于匹配URI路径。
Route route =router.route().pathRegex(".*foo");
route.handler(routingContext -> {
//This handler will be called for:
///some/path/foo
///foo
///foo/bar/wibble/foo
///foo/bar
//But not:
///bar/wibble
});
另一种是在创建路由时指定正则表达式：
Route route = router.routeWithRegex(".*foo");
route.handler(routingContext -> {
//This handler will be called same as previous example
});
用正则表达式获取路径参数
在使用正则表达式时，可以获取路径参数，这是一个例子：
Route route = router.routeWithRegex(".*foo");
// This regular expression matches pathsthat start with something like:
// "/foo/bar" - where the"foo" is captured into param0 and the "bar" is capturedinto
// param1
route.pathRegex("\\/([^\\/]+)\\/([^\\/]+)").handler(routingContext-> {
String productType =routingContext.request().getParam("param0");
String productID =routingContext.request().getParam("param1");
//Do something with them...
});
在上面的例子中，如何请求路径为：/tools/drill123/，然后路由将会匹配上，并且productType将接到值为tools，productID将会接到值drill123。之所以能获取，因为在表达式中存在获取组（此例是小括号括起来的部分）。
根据HTTP方法（POST,GET,PUT,DELETE…）路由
一个路由默认是匹配所有HTTP方法。如果想让一个路由到指定的HTTP方法，可以有method方法。
Route route =router.route().method(HttpMethod.POST);
route.handler(routingContext -> {
//This handler will be called for any POST request
});
也可以在创建路由时与path一起设置：
Route route = router.route(HttpMethod.POST,"/some/path/");
route.handler(routingContext -> {
//This handler will be called for any POST request to a URI path starting with/some/path/
});
也可以用路由器上的get,post,put方法将请求路由到指定的HTTP方法，例如：
router.get().handler(routingContext -> {
//Will be called for any GET request
});
router.get("/some/path/").handler(routingContext-> {
//Will be called for any GET request to a path
//starting with /some/path
});
router.getWithRegex(".*foo").handler(routingContext-> {
//Will be called for any GET request to a path
//ending with `foo`
});
如果想用多个HTTP方法指定一个路由，可以多次调用method方法：
Route route = router.route().method(HttpMethod.POST).method(HttpMethod.PUT);
route.handler(routingContext -> {
//This handler will be called for any POST or PUT request
});
路由顺序
默认，路由匹配根据加入路由器的顺序执行。在请求到达路由器时，路由器将逐一通过每个路由，并检查是否匹配。如果匹配此路由的处理器将会被调用。如此处理器随后调用next方法，下一个匹配的处理器将会被调用，如此类推。这个例子对此进行了阐述：
Route route1 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
//enable chunked responses because we will be adding data as
//we execute over other handlers. This is only required once and
//only if several handlers do output.
response.setChunked(true);
response.write("route1\n");
//Now call the next matching route
routingContext.next();
});
Route route2 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
response.write("route2\n");
//Now call the next matching route
routingContext.next();
});
Route route3 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
response.write("route3");
//Now end the response
routingContext.response().end();
});
从面例子的响应包括：
route1
route2
route3
因为路由已经按顺序匹配/some/path为前缀的路径的请求，并调用相应的处理器。如果相覆盖默认的路由顺序，可以用order方法指定一个整型值。在创建路由时，给期指定一个顺序值决定哪一个被加到路由器中。每个路由的数值是0,第二个路由的数值是1，以此类推。通过为路由指定顺序值，可以覆盖默认的顺序。顺序值可以为负值，例如想确保一个路由在顺序值为0的路由之前解析。
让我们改变路由route2顺序,让它在路由一（route1）之前执行：
Route route1 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
response.write("route1\n");
//Now call the next matching route
routingContext.next();
});
Route route2 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
//enable chunked responses because we will be adding data as
//we execute over other handlers. This is only required once and
//only if several handlers do output.
response.setChunked(true);
response.write("route2\n");
//Now call the next matching route
routingContext.next();
});
Route route3 =router.route("/some/path/").handler(routingContext -> {
HttpServerResponse response = routingContext.response();
response.write("route3");
//Now end the response
routingContext.response().end();
});
// Change the order of route2 so it runsbefore route1
route2.order(-1);
然后响应如下：
route2
route1
route3
如果两具路由有相同的顺序值，那么它们将按添加时的顺序被调用。可以用last方法指定最后处理的路由。
基于请求MIME类型路由
可以用consumes方法设置一个路由匹配请求的MIME类型。这样，请求将要包含一个Content-type的头，指定请求体的MIME类型。这将匹在consumes方法中指定的值。基本上，consumes方法描述那一个MIME类型可以被处理器消费。
可以进行精确的MIME类型匹配:
router.route().consumes("text/html").handler(routingContext-> {
//This handler will be called for any request with
//content-type header set to `text/html`
});
也可以指定多个MIME类型的精确匹配:
router.route().consumes("text/html").consumes("text/plain").handler(routingContext-> {
//This handler will be called for any request with
//content-type header set to `text/html` or `text/plain`.
});
用通配符匹配子类型也支持：
router.route().consumes("text/*").handler(routingContext -> {
//This handler will be called for any request with top level type `text`
//e.g. content-type header set to `text/html` or `text/plain` will both match
});
也可以匹配MIME的顶层类型
router.route().consumes("*/json").handler(routingContext-> {
//This handler will be called for any request with sub-type json
//e.g. content-type header set to `text/json` or `application/json` will bothmatch
});
如果在consumers没有指定“/”，Vert.x-Web默认指定的是子类型。
基于客户可接收的MIME类型进行路由
accept HTTP头用于标识客户端接收的哪种MIME类型。一个accept头可以有多个以“，”分隔的MIME类型。MIME类型也可以加一q值说明每个匹配MIME类型的响应的的权重。q值是0至1之间的一数值，如果忽略，默认值为1.0。
例如，下面accept头说明客户端接收text/plain的MIME类型的响应。
Accept: text/plain
下面的客户端将接收text/plain或者text/html的响应
Accept: text/plain, text/html
下面的客户端将接收text/plain或者text/html，但是更侧重于text/html,因为有较高的q值（默认值是q=1.0）
Accept: text/plain; q=0.9, text/html
如果服务既可以提供text/plain,也可以提供text/html,服务器在此种设置下会提供text/html。
使用produces方法，可以决定路由产生哪种MIME类型，例如下面的处理器产生一个application/json的MIME类型响应。
router.route().produces("application/json").handler(routingContext-> {
HttpServerResponse response = routingContext.response();
response.putHeader("content-type","application/json");
response.write(someJSON).end();
});
这样路由将匹配任何以application/json为值的accept的请求。这一些可以匹配accept头的例子： Accept: application/json
Accept: application/*
Accept: application/json, text/html
Accept: application/json;q=0.7, text/html;q=0.8,text/plain
也可以使路由生产多个MIME类型。如果这样，可以使用getAcceptableContentType方法找到实际可接收的MIME类型。
router.route().produces("application/json").produces("text/html").handler(routingContext-> {
HttpServerResponse response = routingContext.response();
// Get the actualMIME type acceptable
StringacceptableContentType = routingContext.getAcceptableContentType();
response.putHeader("content-type", acceptableContentType);
response.write(whatever).end();
});
在上面的例子中，如果你发送一个下面的accept头的请求： Accept: application/json; q=0.7, text/html
路由将匹配，并且acceptableContentType将包含text/html,因两个都会接收，但是text/html有着较高的q值。
组合路由条件
可以用多种方法组合上面所有的路由条件，例如：
Route route = router.route(HttpMethod.PUT,"myapi/orders")
.consumes("application/json")
.produces("application/json");
route.handler(routingContext -> {
// This would bematch for any PUT method to paths starting with "myapi/orders" with a
// content-typeof "application/json"
// and an acceptheader matching "application/json"
});
启动和禁用路由
用disable方法禁用路由，一个禁用的路由在匹配时会被忽视，用enable方法重新启用路由。