spring-projects/spring-framework

spring-webflux

Active contributors: rstoyanchev, Juergen Hoeller, Brian Clozel, Sébastien Deleuze

Purpose

spring-webflux is Spring's reactive web framework. Like spring-webmvc it supports annotation-driven controllers (@RestController, @RequestMapping) and a functional RouterFunction API, but it operates on Reactor types (Mono/Flux) end-to-end. It runs on Reactor Netty, Undertow, Jetty, or any Servlet 5+ container — anywhere a non-blocking transport is available.

Directory layout

spring-webflux/
└── src/main/java/org/springframework/web/reactive/
    ├── DispatcherHandler.java                      # the reactive front controller
    ├── HandlerMapping.java
    ├── HandlerAdapter.java
    ├── HandlerResult.java
    ├── HandlerResultHandler.java
    ├── config/                                     # @EnableWebFlux, WebFluxConfigurer
    ├── function/                                   # functional RouterFunction API
    │   ├── client/                                 # WebClient lives here
    │   └── server/
    ├── handler/                                    # AbstractHandlerMapping, exception handling
    ├── result/                                     # ResponseEntity / view / @ResponseBody handlers
    │   ├── method/
    │   │   └── annotation/                         # RequestMappingHandlerMapping/Adapter
    │   └── view/                                   # view resolvers (FreeMarker, Mustache, …)
    ├── socket/                                     # WebSocket (reactive)
    ├── resource/                                   # static resources
    └── …

Key abstractions

Type	File	Role
`DispatcherHandler`	`spring-webflux/src/main/java/org/springframework/web/reactive/DispatcherHandler.java`	Reactive front controller
`WebHandler`	`spring-web/src/main/java/org/springframework/web/server/WebHandler.java`	Top-level reactive handler interface
`WebFilter`	`spring-web/src/main/java/org/springframework/web/server/WebFilter.java`	Reactive filter (analog of Servlet `Filter`)
`RequestMappingHandlerMapping`	`spring-webflux/src/main/java/org/springframework/web/reactive/result/method/annotation/RequestMappingHandlerMapping.java`	Annotation-driven routing
`HandlerAdapter`	`spring-webflux/src/main/java/org/springframework/web/reactive/HandlerAdapter.java`	Invokes a handler
`RouterFunction` / `HandlerFunction`	`spring-webflux/src/main/java/org/springframework/web/reactive/function/server/`	Functional, lambda-based routing
`WebClient`	`spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java`	Reactive HTTP client
`WebFluxConfigurer`	`spring-webflux/src/main/java/org/springframework/web/reactive/config/WebFluxConfigurer.java`	Customization callbacks
`@EnableWebFlux`	`spring-webflux/src/main/java/org/springframework/web/reactive/config/EnableWebFlux.java`	Imports the default reactive configuration

How it works

Request lifecycle

sequenceDiagram
    participant Client
    participant Server as Reactor Netty / Servlet
    participant DH as DispatcherHandler
    participant HM as HandlerMapping
    participant HA as HandlerAdapter
    participant Ctrl as Controller
    participant RH as HandlerResultHandler
    Client->>Server: HTTP request
    Server->>DH: ServerWebExchange
    DH->>HM: getHandler(exchange) → Mono<Object>
    HM-->>DH: handler
    DH->>HA: handle(exchange, handler) → Mono<HandlerResult>
    HA->>Ctrl: invoke (Reactor-aware arg resolvers)
    Ctrl-->>HA: Mono / Flux / value
    HA-->>DH: HandlerResult
    DH->>RH: handle(exchange, result) → Mono<Void>
    RH-->>Server: backpressure-aware write
    Server-->>Client: response

Every step returns Mono<…> rather than blocking. The pipeline composes through Reactor operators; the response is written when the framework subscribes to the chain.

Two programming styles

// Annotation-driven
@RestController
class UserController {
    @GetMapping("/users/{id}")
    Mono<User> get(@PathVariable Long id) { … }
}

// Functional
@Bean
RouterFunction<ServerResponse> routes() {
    return route(GET("/users/{id}"), req -> ServerResponse.ok().body(...));
}

Both produce the same wire behavior. The annotation style covers the vast majority of apps; the functional style is preferred when wiring small, focused endpoints.

Argument resolution

Reactor-aware. Argument resolvers can return Mono<T>/Flux<T> directly. HandlerMethodArgumentResolverSupport deals with reactive types via ReactiveAdapterRegistry (in spring-core), so RxJava's Single/Observable, Mutiny's types, and Kotlin coroutines all work via adapters.

`WebClient`

WebClient is the reactive HTTP client. It builds on ClientHttpConnector (Reactor Netty by default) and uses ExchangeFunction for filtering. Suitable for both reactive and imperative apps that want a non-blocking client.

graph LR
    App -->|"get/post/…"| WC[WebClient]
    WC --> EF[ExchangeFunction chain]
    EF --> CHC[ClientHttpConnector]
    CHC -->|"Reactor Netty / Jetty / HttpClient5"| Server

Reactor and backpressure

Every HTTP body, every collection result, every server-sent-events stream is a Publisher. The transport (Reactor Netty) signals demand back through the pipeline; controllers don't generally need to think about this, but it gives WebFlux the ability to handle large streaming payloads with bounded memory.

Integration points

Depends on spring-beans, spring-core, spring-web.
Runs on Reactor Netty (default), Servlet 5+ containers (HttpHandlerServletAdapter), Undertow, Jetty.
Reactive transactions via spring-tx ReactiveTransactionManager and spring-r2dbc.

Entry points for modification

New HandlerResultHandler — Implement and register via WebFluxConfigurer.addArgumentResolvers or as a bean.
Custom codec — Implement Encoder / Decoder and register via WebFluxConfigurer.configureHttpMessageCodecs.
Filter pipeline — Provide WebFilter beans; ordered via @Order.

Notable internals

InvocableHandlerMethod (and its *Method siblings) — Reactive variants of MVC's invocation utilities; aware of Reactor types.
ResponseEntityResultHandler — Recognizes ResponseEntity<Mono<T>> and friends for status/header customization.
ServerWebExchange — The reactive analog of HttpServletRequest+HttpServletResponse. Available throughout the pipeline.