WebFlux Java 配置声明了处理所需的组件 使用带注释的控制器或功能端点的请求,并提供 API 来 自定义配置。这意味着您不需要了解底层 由 Java 配置创建的 Bean。但是,如果您想了解它们, 您可以在 中查看它们或阅读更多有关它们的信息 在特殊的豆类类型中。WebFluxConfigurationSupport

对于配置 API 中不可用的更高级自定义项,您可以 通过高级配置模式获得对配置的完全控制。

启用 WebFlux 配置

您可以在 Java 配置中使用注解,如以下示例所示:@EnableWebFlux

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig {
}
@Configuration
@EnableWebFlux
class WebConfig

前面的示例注册了许多 Spring WebFlux 基础结构 bean 并适应依赖关系 在类路径上可用 — 用于 JSON、XML 等。

WebFlux 配置 API

在您的 Java 配置中,您可以实现接口, 如以下示例所示:WebFluxConfigurer

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	// Implement configuration methods...
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	// Implement configuration methods...
}

转换、格式化

默认情况下,会安装各种数字和日期类型的格式化程序以及支持 用于自定义 via 和 on 字段。@NumberFormat@DateTimeFormat

要在 Java config 中注册自定义格式化程序和转换器,请使用以下命令:

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void addFormatters(FormatterRegistry registry) {
		// ...
	}

}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun addFormatters(registry: FormatterRegistry) {
		// ...
	}
}

默认情况下,Spring WebFlux 在解析和格式化日期时会考虑请求 Locale 值。这适用于日期表示为带有“输入”形式的字符串的表单 领域。但是,对于“日期”和“时间”表单字段,浏览器使用定义的固定格式 在 HTML 规范中。对于这种情况,可以按如下方式自定义日期和时间格式:

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void addFormatters(FormatterRegistry registry) {
		DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();
		registrar.setUseIsoFormat(true);
		registrar.registerFormatters(registry);
     	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun addFormatters(registry: FormatterRegistry) {
		val registrar = DateTimeFormatterRegistrar()
		registrar.setUseIsoFormat(true)
		registrar.registerFormatters(registry)
	}
}
请参阅 FormatterRegistrar SPI 和 有关何时使用 使用实现。FormattingConversionServiceFactoryBeanFormatterRegistrar

验证

缺省情况下,如果存在 Bean 验证 在类路径(例如,Hibernate Validator)上,将 注册为全局验证器,以便与方法参数一起使用。LocalValidatorFactoryBean@Valid@Validated@Controller

在 Java 配置中,您可以自定义全局实例, 如以下示例所示:Validator

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public Validator getValidator() {
		// ...
	}

}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun getValidator(): Validator {
		// ...
	}

}

请注意,您还可以在本地注册实现, 如以下示例所示:Validator

  • Java

  • Kotlin

@Controller
public class MyController {

	@InitBinder
	protected void initBinder(WebDataBinder binder) {
		binder.addValidators(new FooValidator());
	}

}
@Controller
class MyController {

	@InitBinder
	protected fun initBinder(binder: WebDataBinder) {
		binder.addValidators(FooValidator())
	}
}
如果您需要在某个地方注射,请创建一个豆子并 标记它以避免与 MVC 配置中声明的冲突。LocalValidatorFactoryBean@Primary

内容类型解析程序

您可以配置 Spring WebFlux 如何从请求中确定实例的请求媒体类型。默认情况下,仅检查标头, 但您也可以启用基于查询参数的策略。@ControllerAccept

以下示例演示如何自定义请求的内容类型解析:

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
		// ...
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun configureContentTypeResolver(builder: RequestedContentTypeResolverBuilder) {
		// ...
	}
}

HTTP 消息编解码器

以下示例演示如何自定义请求和响应正文的读取和写入方式:

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
		configurer.defaultCodecs().maxInMemorySize(512 * 1024);
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) {
		configurer.defaultCodecs().maxInMemorySize(512 * 1024)
	}
}

ServerCodecConfigurer提供一组默认读取器和写入器。您可以使用它来添加 更多的阅读器和写入器,自定义默认的,或完全替换默认的。

对于 Jackson JSON 和 XML,请考虑使用 Jackson2ObjectMapperBuilder, 它使用以下属性自定义 Jackson 的默认属性:

如果在类路径上检测到以下已知模块,它还会自动注册它们:

查看解析器

以下示例演示如何配置视图分辨率:

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void configureViewResolvers(ViewResolverRegistry registry) {
		// ...
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun configureViewResolvers(registry: ViewResolverRegistry) {
		// ...
	}
}

具有 Spring 框架使用的视图技术的快捷方式 集成。以下示例使用 FreeMarker(还需要配置 底层 FreeMarker 视图技术):ViewResolverRegistry

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {


	@Override
	public void configureViewResolvers(ViewResolverRegistry registry) {
		registry.freeMarker();
	}

	// Configure Freemarker...

	@Bean
	public FreeMarkerConfigurer freeMarkerConfigurer() {
		FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
		configurer.setTemplateLoaderPath("classpath:/templates");
		return configurer;
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun configureViewResolvers(registry: ViewResolverRegistry) {
		registry.freeMarker()
	}

	// Configure Freemarker...

	@Bean
	fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {
		setTemplateLoaderPath("classpath:/templates")
	}
}

您还可以插入任何实现,如以下示例所示:ViewResolver

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {


	@Override
	public void configureViewResolvers(ViewResolverRegistry registry) {
		ViewResolver resolver = ... ;
		registry.viewResolver(resolver);
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun configureViewResolvers(registry: ViewResolverRegistry) {
		val resolver: ViewResolver = ...
		registry.viewResolver(resolver
	}
}

支持内容协商和呈现其他格式 通过视图解析(除 HTML 外),您可以配置一个或多个默认视图 ,它接受来自 的任何可用编解码器。以下示例演示如何执行此操作:HttpMessageWriterViewspring-web

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {


	@Override
	public void configureViewResolvers(ViewResolverRegistry registry) {
		registry.freeMarker();

		Jackson2JsonEncoder encoder = new Jackson2JsonEncoder();
		registry.defaultViews(new HttpMessageWriterView(encoder));
	}

	// ...
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {


	override fun configureViewResolvers(registry: ViewResolverRegistry) {
		registry.freeMarker()

		val encoder = Jackson2JsonEncoder()
		registry.defaultViews(HttpMessageWriterView(encoder))
	}

	// ...
}

有关与 Spring WebFlux 集成的视图技术的更多信息,请参阅视图技术

静态资源

此选项提供了一种从基于资源的位置列表中提供静态资源的便捷方法。

在下一个示例中,给定一个以 开头的请求,相对路径为 用于查找和提供相对于类路径的静态资源。资源 提供一年的未来到期,以确保最大限度地使用浏览器缓存 并减少了浏览器发出的 HTTP 请求。标题也是 已计算,如果存在,则返回状态代码。以下列表显示 示例:/resources/staticLast-Modified304

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("/resources/**")
				.addResourceLocations("/public", "classpath:/static/")
				.setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS));
	}

}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun addResourceHandlers(registry: ResourceHandlerRegistry) {
		registry.addResourceHandler("/resources/**")
				.addResourceLocations("/public", "classpath:/static/")
				.setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS))
	}
}

资源处理程序还支持 ResourceResolver 实现和 ResourceTransformer 实现链, 可用于创建用于处理优化资源的工具链。

您可以使用基于 MD5 哈希的 for 版本化资源 URL 根据内容、固定应用程序版本或其他信息计算得出。A(MD5 哈希)是一个不错的选择,但有一些值得注意的例外(例如 与模块加载器一起使用的 JavaScript 资源)。VersionResourceResolverContentVersionStrategy

以下示例显示了如何在 Java 配置中使用:VersionResourceResolver

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("/resources/**")
				.addResourceLocations("/public/")
				.resourceChain(true)
				.addResolver(new VersionResourceResolver().addContentVersionStrategy("/**"));
	}

}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	override fun addResourceHandlers(registry: ResourceHandlerRegistry) {
		registry.addResourceHandler("/resources/**")
				.addResourceLocations("/public/")
				.resourceChain(true)
				.addResolver(VersionResourceResolver().addContentVersionStrategy("/**"))
	}

}

您可以使用重写 URL 并应用解析器的完整链和 转换器(例如,插入版本)。WebFlux 配置提供了一个,以便可以将其注入到其他配置中。ResourceUrlProviderResourceUrlProvider

与Spring MVC不同,目前在WebFlux中,没有办法透明地重写静态 资源 URL,因为没有可以使用非阻塞链的视图技术 旋转变压器和变压器。当仅提供本地资源时,解决方法是直接使用(例如,通过自定义元素)和块。ResourceUrlProvider

请注意,当同时使用两者(例如,Gzip、Brotli 编码)和 时,必须按该顺序注册它们,以确保基于内容 版本始终基于未编码的文件可靠地计算。EncodedResourceResolverVersionedResourceResolver

对于 WebJar,版本控制的 URL 是推荐的,也是最有效的使用方式。 相关资源位置是使用 Spring Boot 现成配置的(或者可以配置 手动通过 ),并且不需要添加依赖项。/webjars/jquery/1.2.0/jquery.min.jsResourceHandlerRegistryorg.webjars:webjars-locator-core

无版本的 URL 通过 当库存在于类路径上时自动注册,但代价是 类路径扫描可能会减慢应用程序启动速度。解析器可以将 URL 重写为 包括 jar 的版本,还可以与没有版本的传入 URL 进行匹配,例如,从 到 ./webjars/jquery/jquery.min.jsWebJarsResourceResolverorg.webjars:webjars-locator-core/webjars/jquery/jquery.min.js/webjars/jquery/1.2.0/jquery.min.js

基于的 Java 配置提供了更多选项 用于细粒度控制,例如最后修改的行为和优化的资源解析。ResourceHandlerRegistry

路径匹配

您可以自定义与路径匹配相关的选项。有关各个选项的详细信息,请参阅 PathMatchConfigurer javadoc。 以下示例演示如何使用:PathMatchConfigurer

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void configurePathMatch(PathMatchConfigurer configurer) {
		configurer.addPathPrefix(
				"/api", HandlerTypePredicate.forAnnotation(RestController.class));
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	@Override
	fun configurePathMatch(configurer: PathMatchConfigurer) {
		configurer.addPathPrefix(
				"/api", HandlerTypePredicate.forAnnotation(RestController::class.java))
	}
}

Spring WebFlux 依赖于请求路径的解析表示,该请求路径用于访问解码的路径段值,并删除分号内容 (即路径或矩阵变量)。这意味着,与Spring MVC不同,您不需要指出 是否解码请求路径,是否删除 路径匹配目的。RequestPath

Spring WebFlux 也不支持后缀模式匹配,这与 Spring MVC 不同,在 Spring MVC 中,我们 也建议远离 依赖它。

阻止执行

WebFlux Java 配置允许您自定义 WebFlux 中的阻塞执行。

您可以通过提供 例如 VirtualThreadTaskExecutor,如下所示:AsyncTaskExecutor

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public void configureBlockingExecution(BlockingExecutionConfigurer configurer) {
		AsyncTaskExecutor executor = ...
		configurer.setExecutor(executor);
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	@Override
	fun configureBlockingExecution(configurer: BlockingExecutionConfigurer) {
		val executor = ...
		configurer.setExecutor(executor)
	}
}

默认情况下,其返回类型未被配置的控制器方法视为阻塞,但您可以设置自定义控制器 方法谓词通过 .ReactiveAdapterRegistryBlockingExecutionConfigurer

WebSocket服务

WebFlux Java 配置声明了一个 bean,它提供 支持调用 WebSocket 处理程序。这意味着所有剩下要做的就是 处理 WebSocket 握手请求的顺序是将 a 映射到 URL 通过。WebSocketHandlerAdapterWebSocketHandlerSimpleUrlHandlerMapping

在某些情况下,可能需要使用 提供了允许配置 WebSocket 服务器属性的服务。 例如:WebSocketHandlerAdapterWebSocketService

  • Java

  • Kotlin

@Configuration
@EnableWebFlux
public class WebConfig implements WebFluxConfigurer {

	@Override
	public WebSocketService getWebSocketService() {
		TomcatRequestUpgradeStrategy strategy = new TomcatRequestUpgradeStrategy();
		strategy.setMaxSessionIdleTimeout(0L);
		return new HandshakeWebSocketService(strategy);
	}
}
@Configuration
@EnableWebFlux
class WebConfig : WebFluxConfigurer {

	@Override
	fun webSocketService(): WebSocketService {
		val strategy = TomcatRequestUpgradeStrategy().apply {
			setMaxSessionIdleTimeout(0L)
		}
		return HandshakeWebSocketService(strategy)
	}
}

高级配置模式

@EnableWebFlux导入:DelegatingWebFluxConfiguration

  • 为 WebFlux 应用程序提供默认的 Spring 配置

  • 检测并委托给实现以自定义该配置。WebFluxConfigurer

对于高级模式,您可以直接从 中删除和扩展,而不是实现 如以下示例所示:@EnableWebFluxDelegatingWebFluxConfigurationWebFluxConfigurer

  • Java

  • Kotlin

@Configuration
public class WebConfig extends DelegatingWebFluxConfiguration {

	// ...
}
@Configuration
class WebConfig : DelegatingWebFluxConfiguration {

	// ...
}

您可以将现有方法保留在 中,但现在也可以覆盖 Bean 声明 从基类开始,并且仍然有任意数量的其他实现 类路径。WebConfigWebMvcConfigurer