Spring Boot WebFlux 2.1.7 中文翻译文档

Posted 2020-11-21 JMCui

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 为以下的模板引擎提供了自动配置的支持：

• FreeMarker
• Thymeleaf
• Mustache

当你使用了其中某个模板引擎，并选择了 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 的自动配置功能已经为你提供了一些内置的过滤器，如下是它们的执行顺序：

Web Filter	Order
MetricsWebFilter	Ordered.HIGHEST_PRECEDENCE + 1
WebFilterChainProxy (Spring Security)	-100
HttpTraceWebFilter	Ordered.LOWEST_PRECEDENCE - 10