Spring WebFlux使用手册

核心组件类

Spring WebFlux有以下核心类：

DispatcherHandler
HandlerMapper
HandlerAdapter
HandlerResultHandler
WebFilter
ServerWebExchange
ServerHttpRequest/ServerHttpResponse
WebSession
WebClient
Handler：处理器。负责处理请求。可能是一个controller或routerfunction。

DispatcherHandler

DispatcherHandler（对应于Spring MVC的DispatcherServlet）负责分发请求.

通过HandlerMapper找到具体处理器
使用HandlerAdapter适配器调用处理器，
使用HandlerResultHandler处理执行结果生成响应。

核心调用方法：

java

@Override
	public Mono<Void> handle(ServerWebExchange exchange) {
		if (this.handlerMappings == null) {
			return createNotFoundError();
		}
		if (CorsUtils.isPreFlightRequest(exchange.getRequest())) {
			return handlePreFlight(exchange);
		}
		return Flux.fromIterable(this.handlerMappings)
				.concatMap(mapping -> mapping.getHandler(exchange)) //step 1
				.next()
				.switchIfEmpty(createNotFoundError())
				.onErrorResume(ex -> handleDispatchError(exchange, ex)) //step 2
				.flatMap(handler -> handleRequestWith(exchange, handler)); //step 3
	}

HandlerMapper

HandlerMapper接口负责将请求URL映射到处理器

java

public interface HandlerMapping {
	/**
	 * Return a handler for this request.
	 * <p>Before returning a handler, an implementing method should check for
	 * CORS configuration associated with the handler, apply validation checks
	 * based on it, and update the response accordingly. For pre-flight requests,
	 * the same should be done based on the handler matching to the expected
	 * actual request.
	 * @param exchange current server exchange
	 * @return a {@link Mono} that emits one value or none in case the request
	 * cannot be resolved to a handler
	 */
	Mono<Object> getHandler(ServerWebExchange exchange);
}

HandlerMapping的实现类：

RequestMappingHandlerMapping：支持基于注解（@RequestMapping）的传统控制器（兼容式，通常用于 WebMVC 风格的 WebFlux）
RouterFunctionMapping：处理基于 RouterFunction 的函数式路由。
SimpleUrlHandlerMapping：处理简单的 URL 到对象的映射。

HandlerAdapter

HandlerAdapter负责检查处理器是否被当前适配器支持。若支持，适配器会负责调用处理器。

java

public interface HandlerAdapter {
	boolean supports(Object handler);
	Mono<HandlerResult> handle(ServerWebExchange exchange, Object handler);
}

HandlerAdapter的实现类：

HandlerFunctionAdapter：处理函数式编程风格的路由函数。处理实现HandlerFunction接口的Handler。
RequestMappingHandlerAdapter：支持基于注解的控制器方法，即带@RequestMapping注解的方法。处理继承HandlerMethod的Handler。
SimpleHandlerAdapter：即处理简单的URL对象映射。处理实现WebHandler接口的 Handler。
WebSocketHandlerAdapter：专门用于WebSocket 请求的处理，和普通的HTTP处理逻辑不同。处理实现WebSocketHandler接口的Handler。

HandlerResultHandler

负责将处理器的返回值转换为HTTP响应。HandlerResultHandler接口有两个方法需实现。

判断是否支持处理处理器的返回值
若支持，则将处理器的返回值转换到响应中。

java

public interface HandlerResultHandler {

	boolean supports(HandlerResult result);

	/**
	 * Process the given result modifying response headers and/or writing data
	 * to the response.
	 * @param exchange current server exchange
	 * @param result the result from the handling
	 * @return {@code Mono<Void>} to indicate when request handling is complete.
	 */
	Mono<Void> handleResult(ServerWebExchange exchange, HandlerResult result);

}

HandlerResultHandler的主要实现类：

ServerResponseResultHandler：处理实现ServerResponse接口的返回值。
ResponseBodyResultHandler：处理包含@ResponseBody注解的方法的返回值。
ViewResolutionResultHandler：处理视图渲染的返回值。支持以下类型的返回值。
- 包含@ModelAttribute注解的方法的返回值。
- Void / Mono<Void>类型的返回值。如果是空响应（无返回），允许继续渲染视图（比如只靠 model 渲染）
- CharSequence类型的返回值，字符串，表示视图名。
- 实现了Rendering接口的返回值。这是 WebFlux 的响应式视图构建器，支持代码式视图配置。
- 实现了Model、Map接口的返回值。提供模型数据，视图名通过请求路径推断。
- 实现了View接口的返回值。返回 Spring View 接口的实现，比如自定义渲染逻辑。
- 非简单Bean类型的返回值。自动视为 ModelAttribute，视图名推断自请求路径或类型名。
ResponseEntityResultHandler：处理响应实体对象类型的返回值。如下：
- HttpEntity 排除RequestEntity，即HttpEntity和ResponseEntity
- ErrorResponse
- ProblemDetail
- HttpHeaders，仅返回头信息，无body。

WebFilter

WebFilter过滤器用于对请求进行检查，决定过滤请求或是传递请求给过滤链的下一个请求。整个过程需要进行异步处理。

java

public interface WebFilter {

	/**
	 * Process the Web request and (optionally) delegate to the next
	 * {@code WebFilter} through the given {@link WebFilterChain}.
	 * @param exchange the current server exchange
	 * @param chain provides a way to delegate to the next filter
	 * @return {@code Mono<Void>} to indicate when request processing is complete
	 */
	Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain);
}

WebFilter的filter方法返回异步组件，意味响应式过滤器支持异步链式逻辑，可结合 doOnNext、doOnSuccess、doFinally 等 Reactor 操作符进行响应式编程。

WebFilter的常用实现类

实现类	作用	所属模块
`HiddenHttpMethodFilter`	支持 HTML 表单通过 `_method` 参数发送 `PUT`, `DELETE` 等方法	`spring-web`
`ForwardedHeaderFilter`	支持处理 `X-Forwarded-*` 头，用于反向代理场景	`spring-web`
`ShallowEtagHeaderFilter`	生成 ETag 头，支持缓存优化	`spring-web`
`CorsWebFilter`	处理跨域（CORS）请求	`spring-web`
`HttpHeaderFilter`	Netty 层的 HTTP 头过滤器（如清理 transfer-encoding）	`spring-web`（内部使用）
`ServerHttpObservationFilter`	Spring 观察者链路追踪（Micrometer）	`spring-web`（Spring 6+）
`SecurityWebFilterChain`	安全过滤器链（由 Spring Security 自动配置）	`spring-security-webflux`
`WebSessionManager`（相关）	会话管理相关过滤器	`spring-web`

Filter执行顺序

当定义了多个Filter时，就会涉及到Filter的执行顺序问题。

有两种方式定义其执行顺序：

实现Ordered接口的getOrder方法定义顺序。
使用@Order注解定义顺序。

当不主动定义顺序时，默认使用Spring的加载顺序，执行顺序会不稳定。

示例

java

@Component
public class TestFilter implements WebFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        System.out.println("请求的路径为：" + exchange.getRequest().getPath());
        long start = System.currentTimeMillis();
        return chain.filter(exchange).doFinally(signalType ->
                System.out.println("请求耗时：" + String.valueOf(System.currentTimeMillis() - start))
        );
    }

    @Override
    public int getOrder() {
        return 0;
    }
}

ServerWebExchange

ServerWebExchange 是 Spring WebFlux 中的核心接口之一，用于在请求处理链（例如 Filter、Handler、HandlerAdapter）中封装 HTTP 请求和响应的上下文信息。

它是 WebFlux 中对服务器 HTTP 交换（request/response exchange）的抽象，相当于 Spring MVC 中的 ServletWebRequest 或 HttpServletRequest/Response 的合体。

WebSession

WebSession 是 Spring WebFlux 中的响应式会话（Session）接口，作用类似于 Servlet 中的 HttpSession，但它是为了非阻塞、响应式（Reactive）编程模型而设计的。WebSession 是 WebFlux 中用来存储与用户相关的会话数据的接口，具有生命周期，可以跨请求维持状态。

WebClient

WebClient是Spring WebFlux中用于发起HTTP请求的非阻塞性HTTP客户端。

Spring WebFlux提供了WebClient的默认实现，涉及如下类:

WebClient接口
DefaultWebClientBuilder：DefaultWebClient类的建造者类
DefaultWebClient：WebClient接口的默认实现

WebClient的使用步骤：

从WebClient接口创建DefaultWebClientBuilder
配置DefaultWebClientBuilder，创建DefaultWebClient
配置DefaultWebClient，发起请求。

java

//返回百度
@GetMapping("/baidu")
public Mono<String> baidu() {
    return WebClient.builder()
            .baseUrl("https://www.baidu.com")
            .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(1024 * 1024))
            .build()
            .get()
            .retrieve()
            .bodyToMono(String.class);
}

Spring Data Reactive

Spring Data Reactive是Spring Data项目中为响应式编程设计的数据库访问支持，主要与Project Reactor工作，适用于Spring WebFlux。它的核心目标是以非阻塞、异步的方式访问数据库，实现更高的吞吐量和更好的扩展性。

模块	支持的数据库	驱动要求
Spring Data R2DBC	关系型数据库（PostgreSQL, MySQL, H2 等）	R2DBC 驱动
Spring Data MongoDB Reactive	MongoDB	MongoDB Reactive Streams 驱动
Spring Data Redis Reactive	Redis	Lettuce
Spring Data Cassandra Reactive	Cassandra	DataStax 驱动
Spring Data Couchbase Reactive	Couchbase	Couchbase SDK

Spring Security Reacvite

Spring Security Reactive 是为响应式 Web 应用（基于 Spring WebFlux）提供安全保障的模块，它是 Spring Security 的响应式编程实现，构建在 Project Reactor 之上。

核心组件

SecurityWebFilterChain：构建安全过滤器，并注册到WebFilter过滤链上。
ServerHttpSecurity：配置安全策略
ReactiveAuthenticationManager：响应式身份验证机制，验证授权。
ReactiveUserDetailsService：提供用户信息
SecurityContext：安全上下文对象

服务调用

服务发现

服务容错

链路跟踪

全局事务

网关

Spring WebFlux使用手册

核心组件类

DispatcherHandler

HandlerMapper

HandlerAdapter

HandlerResultHandler

WebFilter

WebFilter的常用实现类

Filter执行顺序

示例

ServerWebExchange

WebSession

WebClient

Spring Data Reactive

Spring Security Reacvite

Spring WebFlux使用手册 ​

核心组件类 ​

DispatcherHandler ​

HandlerMapper ​

HandlerAdapter ​

HandlerResultHandler ​

WebFilter ​

WebFilter的常用实现类 ​

Filter执行顺序 ​

示例 ​

ServerWebExchange ​

WebSession ​

WebClient ​

Spring Data Reactive ​

Spring Security Reacvite ​

Spring WebFlux使用手册

核心组件类

DispatcherHandler

HandlerMapper

HandlerAdapter

HandlerResultHandler

WebFilter

WebFilter的常用实现类

Filter执行顺序

示例

ServerWebExchange

WebSession

WebClient

Spring Data Reactive

Spring Security Reacvite