8.2.1. “Spring WebFlux 框架”
Spring WebFlux 是 Spring Framework 5.0 中引入的新的响应式 Web 框架。与 Spring MVC 不同,它不需要 servlet API,完全异步且非阻塞,并通过Reactor 项目实现Reactive Streams规范。
Spring WebFlux 有两种风格:函数式和基于注释的。基于注解的模型非常接近 Spring MVC 模型,如下例所示:
WebFlux 是 Spring 框架的一部分,详细信息可在其参考文档中找到。
“WebFlux.fn”,功能变体,将路由配置与请求的实际处理分开,如以下示例所示:
“WebFlux.fn”是 Spring 框架的一部分,详细信息可在其参考文档中找到。
您可以定义任意数量的
RouterFunction
bean,以模块化路由器的定义。如果您需要应用优先级,可以对bean类排序。
首先,将该spring-boot-starter-webflux
模块添加到您的应用程序中。
在应用程序中添加
spring-boot-starter-web
和spring-boot-starter-webflux
模块会导致 Spring Boot 自动配置 Spring MVC,而不是 WebFlux。选择这种行为是因为许多 Spring 开发人员添加spring-boot-starter-webflux
到他们的 Spring MVC 应用程序中以使用响应式WebClient
. 您仍然可以通过将所选应用程序类型设置为 来强制执行您的选择SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE)
。
Spring WebFlux 自动配置
Spring Boot 为 Spring WebFlux 提供自动配置,适用于大多数应用程序。
自动配置在 Spring 默认设置的基础上添加了以下功能:
如果您想保留 Spring Boot WebFlux 功能并添加额外的WebFlux 配置,您可以添加自己的@Configuration
type 类WebFluxConfigurer
,但不添加 @EnableWebFlux
.
如果你想完全控制Spring WebFlux,你可以添加你自己的@Configuration
注释@EnableWebFlux
。
Spring WebFlux 转换服务
如果你想自定义ConversionService
Spring WebFlux使用的,你可以提供一个WebFluxConfigurer
带有方法的bean addFormatters
。
还可以使用spring.webflux.format.*
配置属性来自定义转换。如果未配置,则使用以下默认值:
具有 HttpMessageReaders 和 HttpMessageWriters 的 HTTP 编解码器
Spring WebFlux 使用HttpMessageReader
和HttpMessageWriter
接口来转换 HTTP 请求和响应。通过查看类路径中可用的库,将它们配置为具有合理的默认值的CodecConfigurer
。
Spring Boot 为编解码器提供了专用的配置属性 spring.codec.*
。它还通过使用 CodecCustomizer
实例来应用进一步的自定义。例如, spring.jackson.*
配置键应用于 Jackson 编解码器。
如果您需要添加或自定义编解码器,您可以创建自定义CodecCustomizer
组件,如下例所示:
您还可以利用Boot 的自定义 JSON 序列化器和反序列化器。
静态内容
默认情况下,Spring Boot 从类路径中名为/static
(或 /public
或 /resources
或/META-INF/resources
)的目录提供静态内容。它使用Spring WebFlux的ResourceWebHandler
,以便您可以通过添加自己的WebFluxConfigurer
并覆盖addResourceHandlers
方法来修改该行为。
默认情况下,资源映射到/**
,但您可以通过设置spring.webflux.static-path-pattern
属性来调整它。例如,将所有资源重新定位/resources/**
可以实现如下:
您还可以使用spring.web.resources.static-locations
自定义静态资源位置。这样做会用目录位置列表替换默认值。如果您这样做,默认欢迎页面检测将切换到您的自定义位置。因此,如果启动时在任何位置有index.html
,则它是应用程序的主页。
除了前面列出的“标准”静态资源位置之外,还为Webjars 内容制作了一个特殊情况。默认情况下,如果以 Webjars 格式打包,则任何路径为/webjars/**
的资源都将从 jar 文件提供。可以使用属性spring.webflux.webjars-path-pattern
自定义路径。
Spring WebFlux应用程序并不严格依赖于servlet API,因此它们不能部署为war文件并且不使用
src/main/webapp
目录。
欢迎页面
Spring Boot 支持静态和模板化欢迎页面。index.html
它首先在配置的静态内容位置查找文件。如果没有找到,它就会寻找index
模板。如果找到其中一个,它将自动用作应用程序的欢迎页面。
这仅充当应用程序定义的实际索引路由的后备。顺序由HandlerMapping
bean 的顺序定义,默认情况如下:
模板引擎
除了 REST Web 服务之外,您还可以使用 Spring WebFlux 来提供动态 HTML 内容。Spring WebFlux 支持多种模板技术,包括 Thymeleaf、FreeMarker 和 Mustache。
Spring Boot 包括对以下模板引擎的自动配置支持:
当您使用这些模板引擎之一和默认配置时,您的模板会自动从src/main/resources/templates
加载.
错误处理
Spring Boot 提供了一种WebExceptionHandler
以合理的方式处理所有错误的方法。它在处理顺序中的位置紧邻 WebFlux 提供的处理程序之前,这些处理程序被认为是最后的。对于机器客户端,它会生成一个 JSON 响应,其中包含错误、HTTP 状态和异常消息的详细信息。对于浏览器客户端,有一个“whitelabel”错误处理程序,可以以 HTML 格式呈现相同的数据。您还可以提供自己的 HTML 模板来显示错误(请参阅下一节)。
在直接在 Spring Boot 中自定义错误处理之前,您可以利用Spring WebFlux 中的RFC 7807 Problem Details支持。Spring WebFlux 可以使用application/problem+json
媒体类型生成自定义错误消息,例如:
可以通过设置spring.webflux.problemdetails.enabled
为 true
来启用此支持。
定制此功能的第一步通常涉及使用现有机制,但替换或增加错误内容。为此,您可以添加类型为ErrorAttributes
的 bean 。
要更改错误处理行为,您可以实现ErrorWebExceptionHandler
并注册该类型的 bean 定义。由于 ErrorWebExceptionHandler
是相当低级的,Spring Boot 还提供了一种方便的AbstractErrorWebExceptionHandler
让您以 WebFlux 功能方式处理错误,如以下示例所示:
为了获得更完整的图片,您还可以直接子类化DefaultErrorWebExceptionHandler
并重写特定方法。
在某些情况下,度量基础设施不会记录在控制器或处理函数级别处理的错误。应用程序可以通过将已处理的异常设置为请求属性来确保此类异常与请求指标一起记录:
自定义错误页面
如果要显示给定状态代码的自定义 HTML 错误页面,您可以添加从error/*
解析的视图,例如通过将文件添加到/error
目录。错误页面可以是静态 HTML(即添加在任何静态资源目录下)或使用模板构建。文件的名称应该是准确的状态代码、状态代码系列掩码,或者如果没有其他匹配的情况则为默认值error
。请注意,默认错误视图的路径是error/error
,而对于 Spring MVC,默认错误视图的路径是error
。
例如,要映射404
到静态 HTML 文件,您的目录结构将如下所示:
要使用 Mustache 模板映射所有5xx
错误,您的目录结构将如下所示:
网页过滤器
Spring WebFlux 提供了一个WebFilter
可以实现过滤 HTTP 请求-响应交换的接口。 WebFilter
在应用程序上下文中找到的 bean 将自动用于过滤每个交换。
如果过滤器的顺序很重要,则可以实现Ordered
或注释@Order
。Spring Boot 自动配置可以为您配置 Web 过滤器。执行此操作时,将使用下表中显示的顺序:
最后更新于