1. 前言
从一开始学习 Netty 到 rxjava、Rector,再到 java8 的 CompletableFuture,就深深的为响应式编程着迷,这种区别于传统的顺序式编程,没准未来能在编程世界开辟一片天地呢!
然后接触到了 WebFlux 框架,也是充满了浓厚的兴趣,想好好琢磨一番,奈何中文资料实在太少,就打起了英文文档的主意,可惜英文水平实在捉急,总是看下一句,忘了上一句。诶,要不咱一句句翻译出来吧,这样读起来就通顺了,顺便可以造福下后来学习者(想着翻译的东西要被人看,也是一份坚持的动力)。
翻译并没有逐字逐句去纠结,力求语义通顺,有理解错误的地方,还麻烦大家指出,一起学习探讨。另外,文中还补充了一些自己练习的 demo。
原文链接:https://docs.spring.io/spring-boot/docs/2.1.7.RELEASE/reference/htmlsingle/#boot-features-webflux
github 练习 demo:https://github.com/JMCuixy/webflux
tips:翻译是一项提高英语和学习技能一举两得的事呀!
2. WebFlux 简介
Spring WebFlux 是 Spring 5.0 引入的新的响应式框架,区别于 Spring MVC,它不需要依赖Servlet API,它是完全异步非阻塞的,并且基于 Reactor 来实现响应式流规范。
Spring WebFlux 有两种表现形式:基于配置和基于注释。基于注释的实现方式非常类似于 SpringMVC 模型,如以下实例:
@RestController
@RequestMapping("/users")
public class MyRestController {
@GetMapping("/\{user}")
public Mono<User> getUser(@PathVariable Long user) {
// ...
}
@GetMapping("/\{user}/customers")
public Flux<Customer> getUserCustomers(@PathVariable Long user) {
// ...
}
@DeleteMapping("/\{user}")
public Mono<User> deleteUser(@PathVariable Long user) {
// ...
}
}
基于配置的实现方式,把路由和具体请求逻辑分离开,如以下实例:
@Configuration
public class RoutingConfiguration {
@Bean
public RouterFunction<ServerResponse> monoRouterFunction(UserHandler userHandler) {
return route(GET("/\{user}").and(accept(APPLICATION_JSON)), userHandler::getUser)
.andRoute(GET("/\{user}/customers").and(accept(APPLICATION_JSON)), userHandler::getUserCustomers)
.andRoute(DELETE("/\{user}").and(accept(APPLICATION_JSON)), userHandler::deleteUser);
}
}
@Component
public class UserHandler {
public Mono<ServerResponse> getUser(ServerRequest request) {
// ...
}
public Mono<ServerResponse> getUserCustomers(ServerRequest request) {
// ...
}
public Mono<ServerResponse> deleteUser(ServerRequest request) {
// ...
}
}
WebFlux 是 Spring 框架的一部分,其参考文档中提供了详细信息。
你可以定义任意数量的 RouterFunction Bean,以对你的路由进行归纳整理。当然,你也可以针对多个 RouterFunction 设置优先级(@Order 注解)。
开始一个 WebFlux 项目,首先,需要将 spring-boot-starter-webflux 模块引入你的项目。值得注意的是,如果你同时引入了 spring-boot-starter-web 和 spring-boot-starter-webflux 模块会导致 Spring Boot 自动配置Spring MVC,而不是 WebFlux。因为许多 Spring 开发人员引入 spring-boot-starter-webflux ,仅仅是为了使用它的响应式编程(这个理由也是绝了),当然你也可以强制把你的项目配置成 WebFlux:
SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE)
3. 自动配置
Spring Boot 为 Spring WebFlux 提供的自动配置基本能适用于大多数应用。
Spring Boot 的提供的自动配置主要做了以下两个工作:
- 为 HttpMessageReader 和 HttpMessageWriter 实例配置 HTTP 编解码器
- 支持服务静态资源映射,包括对 WebJars 资源的支持
如果你想要保持 Spring Boot WebFlux 的自动配置功能,并且想添加额外的 WebFlux 配置项,你可以自定义 @Configuration 配置类,但不要添加 @EnableWebFlux 注解。
如果你想要完全控制 WebFlux,你可以定义@Configuration 配置类,并且添加 @EnableWebFlux. 注解。
4. HttpMessageReaders 和 HttpMessageWriters 的 HTTP 编解码器
Spring WebFlux 使用 HttpMessageReader 和 HttpMessageWriter 接口来转换 HTTP 请求和响应,可以通过 CodecConfigurer 得到它们的默认配置:
public interface CodecConfigurer {
...
List<HttpMessageReader<?>> getReaders();
List<HttpMessageWriter<?>> getWriters();
...
}
Spring Boot 提供了 CodecCustomizer 接口,允许你进一步定制编解码器,通过其 customize() 方法可以获取到 CodecConfigurer 对象,从而可以注册新的编解码工具,或对现有的编解码工具进行替换等。如以下实例:
import org.springframework.boot.web.codec.CodecCustomizer;
@Configuration
public class MyConfiguration {
@Bean
public CodecCustomizer myCodecCustomizer() {
return codecConfigurer -> {
// ...
}
}
}
5. 静态资源
Spring Boot 默认从类路径的以下目录(/static、 /public 、/resources 、/META-INF/resources)加载静态资源,当然,你可以自定义配置类实现 WebFluxConfigurer 并重写 addResourceHandlers 方法来修改默认资源路径:
@Configuration
public class MyWebFluxConfigurer implements WebFluxConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// do more
}
}
Spring Boot 默认将静态资源映射在 /** 的路径下,当然,你可以通过修改 spring.webflux.static-path-pattern 属性来调整默认映射,例如,将所有资源映射到 /resources/** 路径 ,可以通过以下方式实现:
spring.webflux.static-path-pattern=/resources/**
你也可以通过设置 spring.resources.static-locations 属性值来自定义资源目录,如果你这样做了,默认的欢迎页面检测也将会切换到你设置的资源目录。因此,在你的资源目录中,只要有一个 index.html 页面,都将会成为你的应用主页。
除了前面介绍的标准静态资源外,还有一种特殊的情况,那就是 webjars 内容。如果静态资源被打包成了 webjars 的格式,那么访问这些资源的路径就变成了 /webjars/** 。
tips:Spring WebFlux 应用程序不严格依赖 Servlet API,因此不能将它们部署为 war 文件,也不使用 src/main/webapp 目录。
6. 模板引擎
Spring WebFlux 除了提供 REST web 服务外,还支持渲染动态 HTML 内容,Spring WebFlux 支持一系列模板引擎,包括 Thymeleaf、FreeMarker 和 Mustache。
Spring Boot 为以下的模板引擎提供了自动配置的支持:
当你使用了其中某个模板引擎,并选择了 Spring Boot 自动配置,你需要将你的模板文件放在 src/main/resources/templates 目录下,以便被 Spring Boot 发现。
7. 异常处理
Spring Boot 提供了一个 WebExceptionHandler 用来处理所有错误,WebExceptionHandler 执行通常被认为是处理链中的最后一步,仅位于 WebFlux 提供服务之前。对于机器端,它通常是一个 JSON 响应,包含了HTTP 状态码、错误信息等;对于浏览器端,它通常是一个 “whitelabel” HTML 错误页面,页面渲染了相同的错误信息。当然,你也可以提供自定义的 HTML 模板来展示错误信息(下文会说到)。
首先,定制此功能通常涉及利用现有机制,但要替换或增加错误内容,你可以添加 ErrorAttributes 类型的 Bean。
若要更改错误处理行为,可以实现 ErrorWebExceptionHandler 并注册该类型的 bean 定义,但是 WebExceptionHandler 级别很低。因此 Spring Boot 还提供了一种方便的方式,即继承 AbstractErrorWebExceptionHandler,让你可以通过 WebFlux 的方式处理错误,如以下示例所示(这个配置贼复杂,建议还是乖乖的用默认配置吧):
public class CustomErrorWebExceptionHandler extends AbstractErrorWebExceptionHandler {
// Define constructor here
@Override
protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
return RouterFunctions
.route(aPredicate, aHandler)
.andRoute(anotherPredicate, anotherHandler);
}
}
如果你想要为给定的错误码展示自定义的 HTML 错误页面,你可以在 /error 目录下添加一个错误页面文件。可以是静态HTML(即添加到任意静态资源文件夹下),也可以使用模板构建,文件名应为确切的状态码或系列掩码。
例如,要映射 404 错误码到静态 HTML 文件,您的文件夹结构如下:
src/
+- main/
+- java/
| + <source code>
+- resources/
+- public/
+- error/
| +- 404.html
+- <other public assets>
使用 Mustache 模板对 5xx 错误码作映射,您的文件夹结构如下:
src/
+- main/
+- java/
| + <source code>
+- resources/
+- templates/
+- error/
| +- 5xx.mustache
+- <other templates>
8. 过滤器
Spring WebFlux 提供了一个 WebFilter 接口,用来对 HTTP 请求-响应路由进行过滤,在应用程序上下文中找到的 WebFilter bean 将自动用于过滤每个路由!以下是一个简单鉴权的过滤器 demo — 对于 没有 token 参数的请求返回 401 错误:
@Component
public class CustomWebFilter implements WebFilter {
@Override
public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
MultiValueMap<String, String> queryParams = request.getQueryParams();
if (queryParams == null || StringUtils.isEmpty(queryParams.getFirst("token"))) {
Map<String, String> resultMap = new HashMap<>();
resultMap.put("code", "401");
resultMap.put("msg", "非法请求");
byte[] datas = new byte[0];
try {
datas = new ObjectMapper().writeValueAsBytes(resultMap);
} catch (JsonProcessingException e) {
e.printStackTrace();
}
ServerHttpResponse response = exchange.getResponse();
DataBuffer buffer = response.bufferFactory().wrap(datas);
response.setStatusCode(HttpStatus.UNAUTHORIZED);
response.getHeaders().add("Content-Type", "application/json;charset=UTF-8");
return response.writeWith(Mono.just(buffer));
}
return chain.filter(exchange).then(Mono.fromRunnable(() -> {
ServerHttpResponse response = exchange.getResponse();
//Manipulate the response in some way
}));
}
}
可以通过实现 Ordered 接口或使用 @Order 注释来设置过滤器的执行顺序(执行顺序是从小到大执行,较高的值被解释为较低的优先级)。Spring Boot 的自动配置功能已经为你提供了一些内置的过滤器,如下是它们的执行顺序:
MetricsWebFilter | Ordered.HIGHEST_PRECEDENCE + 1 |
WebFilterChainProxy (Spring Security) | -100 |
HttpTraceWebFilter | Ordered.LOWEST_PRECEDENCE - 10 |