本文主要介绍Vert.x 3.4.x 版本新组件Web Client的使用
Vert.x不久前发布了3.4.0 release版本,该版本在语言支持上新增了Scala和Kotlin的支持,新引入了Web Client和Kafka Client,同时加强了微服务组件的功能,支持多种集群管理器供开发者选择(公司一位同事是vertx-zookeeper集群管理器的开发者),除了这些还有些些微的改动,比如Auth/Security方面的增强,RxJava的支持增强等等,更多的请进入传送门。
本文不具体对每个新特性做分析,只针对Web Client做介绍,简单了解下3.4.x版本的Web Client和3.3.x版本的Http Client的差异。
可以明确的是Web Client是Http Client的升级版,他继承了Http Client的功能特性比如配置,Http/2的支持,pipelining等,同时又提供了一些高级特性,比如表单提交、错误处理、30X跳转等。如果你不需要细粒度的处理http请求/响应,建议你使用Web Client,它已经为你封装了好了很简单的方法供你调用,很多API也都来自HttpClient。
使用Web Client前,你需要引入依赖
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-web-client</artifactId>
<version>3.4.1</version>
</dependency>
创建一个默认的WebClient:
WebClient client = WebClient.create(vertx);
创建一个可配置的WebClient:
WebClientOptions options = new WebClientOptions();
options.setDefaultHost("wonapi.maxleap.cn");
WebClient webClient = WebClient.create(vertx,options);
WebClientOption的配置项全部继承了HttpClientOption,你可以配置其中任意选项。如果你的应用中已经使用了HttpClient并且配置了Option,你可以复用它:
WebClient client = WebClient.wrap(httpClient);
构建一个无body数据的简单请求:
HttpRequest<Buffer> request = client.request(HttpMethod.GET,"/1.0/orders");
request.send(asyncResult -> {
if (asyncResult.succeeded()) {
HttpResponse<Buffer> response = asyncResult.result();
System.out.println("status code:"+response.statusCode());
} else {
System.err.println("error:"+asyncResult.cause().getMessage());
}
});
这适用于GET/OPTIONS/HEAD方式的请求,你可以设置request的query参数,比如
通过request.addQueryParam("param1", "param1_value");
来添加query参数,也可以通过request.setQueryParam("param2", "another_param2_value");
来覆盖query参数,你甚至可以通过request.uri("/1.0/orders?param1=param1_value2¶m2=param2_value")
来放弃现有的query参数重新设置。
构建一个有body数据的请求:
Buffer buffer = Buffer.buffer("{\"a\":1}");
HttpRequest<Buffer> request = client.request(HttpMethod.POST,"/1.0/orders");
httpRequest.sendBuffer(buffer,asyncResult -> {
if (asyncResult.succeeded()) {
HttpResponse<Buffer> response = asyncResult.result();
System.out.println("status code:"+response.statusCode());
} else {
System.err.println("error:"+asyncResult.cause().getMessage());
}
});
上面send
方法来发送无body数据的请求,而通过sendXXX方法可以发送一个带body数据的请求。sendBuffer
用来发送一个buffer缓冲区数据,这个很有用,但通常我们不希望将内容全部加载到内存里,因为它可能很大,或者我们想处理很多并发请求,并且希望对每个请求使用最小值。
为此我们可以使用sendStream来发送一个ReadStream<Buffer>
(比如AsyncFile)流,WebClient会自动为我们实现管道传输pump数据。因为流的长度不确定,请求将使用chunk即分块传输。当然如果知道流的大小,你需要指定content-length
大小。
fs.open("content.txt", new OpenOptions(), fileRes -> {
if (fileRes.succeeded()) {
ReadStream<Buffer> fileStream = fileRes.result();
String fileLen = "1024";
// Send the file to the server using POST
client
.post(80, "api.maxleap.cn", "/2.0/files")
.putHeader("content-length", fileLen)
.sendStream(fileStream, ar -> {
if (ar.succeeded()) {
// Ok
}
});
}
});
上面就是发送一个本地文件content.txt到服务器,通过流传输的方式,因为知道文件大小所以没有使用chunked分块传输。
sendJsonObject
用来发送一个json格式数据,使用它WebClient为自动为你设置Content-Type
为application/json
。比如:
request.sendJsonObject(new JsonObject().put("name","Jack").put("age",18));
sendJson
用来发送一个POJO,本质上是通过Json.encode来将对象转化为json字符串(通过Jackson实现)。比如:
request.sendJson(new User("jack",18));
sendForm
用来发送表单数据,使用它WebClient会自动为你设置Content-Type
为application/x-www-form-urlencoded
。你也可以设置Content-Type
为multipart/form-data
,但当前版本(目前3.4.1)不支持表单文件上传,表单文件上传将会在后续的API版本中支持。比如:
MultiMap form = MultiMap.caseInsensitiveMultiMap();
form.set("name","jack");
form.set("age","18");
client
.post(80, "api.maxleap.cn", "/2.0/users")
.putHeader("content-type", "multipart/form-data")
.sendStream(fileStream, ar -> {
if (ar.succeeded()) {
// Ok
}
});
跟HttpClient的API类似,你可以通过request.putHeader("header1":"value1")
来添加一条头信息,也可以通过MultiMap headers = request.headers();
来获取头信息并操作它(add,addAll,set,setAll,remove等操作)。
send方法可以被多次安全的调用,这对于无body数据的请求很容易复用配置和HttpRequest。同时你可以在request的基础上修改请求,比如我要复用之前使用过的request,同时修改下头信息,那么我们只需要调用之前的request对象的putHeader方法即可得到我们想要的新的request。
通过调用request.timeout(10000)
你可以为请求设置数据读取超时时间,如果请求在超时期限内任未返回任何数据,会将异常java.util.concurrent.TimeoutException
传递给响应处理程序。
send方法接受一个回调函数,用来处理请求发送后异步接受响应结果,需要注意的是默认接受到的响应数据会全部缓冲存放在内存里(通过request.as(BodyCodec.buffer())
设置),如果数据很大,建议你通过request.as(BodyCodec.pipe(writeStream))
将响应传递给写入流中,你也可以通过BodyCodec
实现你想要的响应体解码,比如request.as(BodyCodec.jsonObject())
将响应解析为JsonObject,request.as(BodyCodec.json(User.class))
将响应解析为POJO,如果你不关注响应数据,你可以通过request.as(BodyCodec.none())
来忽略响应体。如此在接受响应的回调函数里可以直接得到request.as()
设置的响应解码体。比如:
client
.get(80, "api.maxleap.cn", "/2.0/users")
.as(BodyCodec.json(User.class))
.send(ar -> {
if (ar.succeeded()) {
HttpResponse<User> response = ar.result();
User user = response.body();
System.out.println("Received response with status code" + response.statusCode() + " with body " + user.toString());
} else {
System.out.println("Something went wrong " + ar.cause().getMessage());
}
});
默认情况下,你可以在处理响应时直接使用bodyAsXXX()
来解析成想要的响应体,这只针对默认的request.as(BodyCodec.buffer())
有效。
vertx 3.3.x的HttpClient是不支持30X重定向的,需要自己实现跳转逻辑,在3.4.x中WebClient默认为我们实现了自动重定向,我们可以在WebClientOption中配置30X重定向的配置:
WebClientOptions options = new WebClientOptions();
options
.setFollowRedirects(true)//设置遵循重定向
.setMaxRedirects(5);//最大重定向次数
WebClient webClient = WebClient.create(vertx,options);
Vert.x web client 可以跟HttpClient相同的方式使用https:
client
.get(443, "api.maxleap.cn", "/2.0/users")
.ssl(true)
.send(ar -> {
if (ar.succeeded()) {
// OK
}
});
或者直接通过决定路径发起https请求:
client
.getAbs("https://api.maxleap.cn/2.0/users")
.send(ar -> {
if (ar.succeeded()) {
// OK
}
});
Vert.x RxJava是一个非常受欢迎的响应式编程扩展程序包,3.4.X版本增强了对RxJava的支持,原本返回Observable
的API全部更改为返回rx.Single
,使其语义更加清晰,结合Vert.x Web Client,将会是一个非常强大的组合。
io.vertx.rxjava.core.Vertx rxVertx = io.vertx.rxjava.core.Vertx.vertx();
io.vertx.rxjava.ext.web.client.WebClient rxWebClient = io.vertx.rxjava.ext.web.client.WebClient.create(rxVertx);
rxWebClient.get(80,"api.maxleap.cn","/2.0/users")
.putHeader("header1","header1-value")
.addQueryParam("query1","query1-value")
.as(io.vertx.rxjava.ext.web.codec.BodyCodec.jsonObject())
.rxSend()
.subscribe(response -> {}, Throwable::printStackTrace);
rxSend
方法返回一个Single<HttpResponse<Buffer>>
,它能在订阅一个Single
请求事件后发送该请求,它能被多次订阅。
作者信息
原文系力谱云旗下技术团队_云服务研发成员:David Young
首发链接:https://blog.maxleap.cn/archi...
相关文章
Maxleap Vert.x应用实践总结
次时代Java编程(一):续 vertx-sync实践
使用Vert.x构建Web服务器和消息系统
欢迎关注微信公众号
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。