Understanding Spring WebFlux Request Flow: From HttpHandler to DispatcherHandler

1 Request Entry HttpHandler

Spring WebFlux provides an automatic configuration class HttpHandlerAutoConfiguration that creates the core HttpHandler bean used in a reactive web application.

public class HttpHandlerAutoConfiguration {
    @Configuration(proxyBeanMethods = false)
    public static class AnnotationConfig {
        private final ApplicationContext applicationContext;
        public AnnotationConfig(ApplicationContext applicationContext) {
            this.applicationContext = applicationContext;
        }
        @Bean
        public HttpHandler httpHandler(ObjectProvider<WebFluxProperties> propsProvider) {
            HttpHandler httpHandler = WebHttpHandlerBuilder.applicationContext(this.applicationContext).build();
            // optional base‑path handling omitted for brevity
            return httpHandler;
        }
    }
}

The created HttpHandler is an instance of HttpWebHandlerAdapter, which is the core processor in the WebFlux environment.

2 HttpWebHandlerAdapter Creation

The HttpWebHandlerAdapter extends WebHandlerDecorator and implements HttpHandler. Its handle method delegates to the underlying WebHandler chain.

public class HttpWebHandlerAdapter extends WebHandlerDecorator implements HttpHandler {
    public HttpWebHandlerAdapter(WebHandler delegate) {
        super(delegate);
    }
    // handle method is inherited from WebHandlerDecorator
}

The delegate is built by WebHttpHandlerBuilder and consists of several decorator layers:

FilteringWebHandler – applies all WebFilter beans.

ExceptionHandlingWebHandler – adds global exception handling.

WebHandlerDecorator – base decorator providing getDelegate().

3 Delegated WebHandler Execution

The WebHandlerDecorator simply forwards the call to its delegate:

public class WebHandlerDecorator implements WebHandler {
    private final WebHandler delegate;
    public WebHandlerDecorator(WebHandler delegate) { this.delegate = delegate; }
    public WebHandler getDelegate() { return this.delegate; }
    public Mono<Void> handle(ServerWebExchange exchange) {
        return this.delegate.handle(exchange);
    }
}

During request processing, the chain looks like:

HttpWebHandlerAdapter.handle()
    -> getDelegate() // returns ExceptionHandlingWebHandler
    -> ExceptionHandlingWebHandler.handle()
        -> super.handle() // invokes FilteringWebHandler
            -> FilteringWebHandler.handle()
                -> DefaultWebFilterChain.filter(exchange)
                    -> (executes each WebFilter in order)
                    -> finally calls DispatcherHandler.handle()

4 DispatcherHandler Execution

The final handler, DispatcherHandler, resolves the appropriate HandlerMapping, obtains a HandlerAdapter, invokes the controller method, and processes the result through a series of HandlerResultHandler implementations (e.g., ResponseEntityResultHandler, ServerResponseResultHandler, ResponseBodyResultHandler, ViewResolutionResultHandler).

public class DispatcherHandler implements WebHandler {
    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))
            .next()
            .switchIfEmpty(createNotFoundError())
            .flatMap(handler -> invokeHandler(exchange, handler))
            .flatMap(result -> handleResult(exchange, result));
    }
}

The overall flow mirrors Spring MVC but operates in a fully reactive, non‑blocking manner.

5 Filter Chain Illustration

The three WebFilter beans are linked together to form a DefaultWebFilterChain:

WebFilter1 -> WebFilter2 -> WebFilter3 -> DispatcherHandler.handle()