HandlerFunction & ServerResponse · Spring Framework — interview questions

What is a HandlerFunction<ServerResponse> in Spring WebFlux, and how does it differ from an annotated @RestController method?

juniormust knowfreq 60%

answer

handle(ServerRequest) -> Mono<ServerResponse>
functional model, not annotations
wired via RouterFunction, not @GetMapping
immutable ServerRequest/ServerResponse
same runtime, different style

basics

~10 s

A HandlerFunction is a function that takes a ServerRequest and returns a Mono<ServerResponse>. It's the functional way to write a WebFlux endpoint, instead of using annotations like @GetMapping on a controller method.

solid answer

~40 s

HandlerFunction<ServerResponse> is a functional interface with one method: Mono<ServerResponse> handle(ServerRequest request). It represents a single reactive endpoint as a plain function rather than an annotated method. Instead of @RestController + @GetMapping, you write a handler that reads from ServerRequest and returns a Mono<ServerResponse>, then map it to a path via a RouterFunction. Both run on the same reactive engine and non-blocking runtime; the difference is style. The functional model keeps routing explicit and testable (handlers are just methods you can call directly), avoids annotation/reflection magic, and gives programmatic control over route composition. Annotated controllers are more declarative and familiar. Semantics — non-blocking I/O, Reactor types, the same HTTP contract — are identical.

code

java · 12 lines

java

import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;

// A HandlerFunction is just: ServerRequest -> Mono<ServerResponse>
public Mono<ServerResponse> hello(ServerRequest request) {
    return ServerResponse.ok()
            .bodyValue("Hello, " + request.pathVariable("name"));
}

// It can also be written as a lambda typed as HandlerFunction<ServerResponse>:
// HandlerFunction<ServerResponse> h = req -> ServerResponse.ok().bodyValue("hi");

go deeper

for a junior

Know the signature: ServerRequest in, Mono<ServerResponse> out, and that it's the annotation-free alternative to @RestController.

for a middle

Explain the immutability of ServerRequest/ServerResponse and that routing is explicit via RouterFunction.

for a senior

Discuss testability, composition, and that behavior/runtime is identical to annotated controllers — only the authoring style differs.

for a principal

Weigh when a functional style pays off (libraries, programmatic/conditional routing, filters as functions) vs. annotated declarativeness for large teams.

Context. Spring WebFlux is the reactive, non-blocking web stack (an alternative to Spring MVC). It offers two programming models: the annotated model (@RestController, @GetMapping, familiar from MVC) and the functional model (router + handler functions). This question is about the functional model's core building block.

HandlerFunction. HandlerFunction<T extends ServerResponse> is a @FunctionalInterface in org.springframework.web.reactive.function.server. Its single method is:

java

Mono<T> handle(ServerRequest request);

So a handler receives one ServerRequest and returns a Mono<ServerResponse> (a reactive publisher that will emit exactly one response, asynchronously). Because it is a functional interface, a handler can be a lambda, a method reference, or a method on a @Component bean.

ServerRequest / ServerResponse. These are immutable, WebFlux-specific abstractions (not the Servlet HttpServletRequest/Response). ServerRequest gives access to headers, path/query params, and the body via bodyToMono/bodyToFlux. ServerResponse is built with a fluent builder — ServerResponse.ok().bodyValue(x) — and the terminal builder call returns a Mono<ServerResponse>.

How it differs from an annotated controller.

Wiring: annotated methods are discovered by reflection over @RequestMapping annotations; handler functions are wired explicitly through a RouterFunction bean (RouterFunctions.route().GET("/x", handler::method).build()).
Testability: a handler is a normal method taking a ServerRequest — you can construct a MockServerRequest and call it directly, no dispatcher needed.
Composition: routes are composed programmatically (.and(...), nested routes, filters as ordinary functions), which is powerful for building libraries or conditional routing.
No behavioral difference: threading, non-blocking I/O, backpressure, content negotiation, and the resulting HTTP semantics are the same; it is purely a different authoring style.

When to use. Functional endpoints shine when you want explicit, centralized routing, lightweight endpoints, or fine-grained programmatic control; annotated controllers are usually chosen for familiarity and large declarative APIs. The two can coexist in one application.

Gotchas.

The return type is Mono<ServerResponse> — a single response publisher — even when the body itself is a Flux of many items (the body is a stream inside one response).
Handlers are typically registered as beans and referenced by method reference; they are not auto-scanned as endpoints the way @GetMapping methods are.
This is reactive WebFlux (org.springframework.web.reactive.function.server). There is a separate org.springframework.web.servlet.function variant for MVC that uses the same names but blocking types — don't mix imports.

**Context.** Spring WebFlux is the reactive, non-blocking web stack (an alternative to Spring MVC). It offers two programming models: the *annotated* model (`@RestController`, `@GetMapping`, familiar from MVC) and the *functional* model (router + handler functions). This question is about the functional model's core building block. **HandlerFunction.** `HandlerFunction<T extends ServerResponse>` is a `@FunctionalInterface` in `org.springframework.web.reactive.function.server`. Its single method is: ```java Mono<T> handle(ServerRequest request); ``` So a handler receives one `ServerRequest` and returns a `Mono<ServerResponse>` (a reactive publisher that will emit exactly one response, asynchronously). Because it is a functional interface, a handler can be a lambda, a method reference, or a method on a `@Component` bean. **ServerRequest / ServerResponse.** These are *immutable*, WebFlux-specific abstractions (not the Servlet `HttpServletRequest`/`Response`). `ServerRequest` gives access to headers, path/query params, and the body via `bodyToMono`/`bodyToFlux`. `ServerResponse` is built with a fluent builder — `ServerResponse.ok().bodyValue(x)` — and the terminal builder call returns a `Mono<ServerResponse>`. **How it differs from an annotated controller.** - *Wiring*: annotated methods are discovered by reflection over `@RequestMapping` annotations; handler functions are wired explicitly through a `RouterFunction` bean (`RouterFunctions.route().GET("/x", handler::method).build()`). - *Testability*: a handler is a normal method taking a `ServerRequest` — you can construct a `MockServerRequest` and call it directly, no dispatcher needed. - *Composition*: routes are composed programmatically (`.and(...)`, nested routes, filters as ordinary functions), which is powerful for building libraries or conditional routing. - *No behavioral difference*: threading, non-blocking I/O, backpressure, content negotiation, and the resulting HTTP semantics are the same; it is purely a different authoring style. **When to use.** Functional endpoints shine when you want explicit, centralized routing, lightweight endpoints, or fine-grained programmatic control; annotated controllers are usually chosen for familiarity and large declarative APIs. The two can coexist in one application. **Gotchas.** - The return type is `Mono<ServerResponse>` — a *single* response publisher — even when the body itself is a `Flux` of many items (the body is a stream inside one response). - Handlers are typically registered as beans and referenced by method reference; they are not auto-scanned as endpoints the way `@GetMapping` methods are. - This is *reactive* WebFlux (`org.springframework.web.reactive.function.server`). There is a separate `org.springframework.web.servlet.function` variant for MVC that uses the same names but blocking types — don't mix imports.

Can annotated controllers and functional endpoints coexist in the same WebFlux app?
Yes. Both models run on the same reactive infrastructure and can be used side by side; the DispatcherHandler routes to whichever matches. Teams often mix them, though most keep one style per module for consistency.
Why does handle() return a Mono<ServerResponse> and not just a ServerResponse?
Because building the response may itself require async work (e.g. reading the request body, a DB call). Returning a Mono lets the whole pipeline stay non-blocking; the framework subscribes and writes the response when it resolves.

saying these in an interview costs you the question

Thinking HandlerFunction returns ServerResponse directly instead of Mono<ServerResponse>
Believing functional endpoints are blocking or non-reactive
Confusing WebFlux ServerRequest with the Servlet HttpServletRequest
Assuming handler methods are auto-discovered like @GetMapping (they must be wired via a RouterFunction)

context

open as a page

How do you extract the request body inside a HandlerFunction, and when do you use bodyToMono versus bodyToFlux?

middlemust knowfreq 55%

basics

~10 s

Call request.bodyToMono(MyType.class) when the body is a single object, or request.bodyToFlux(MyType.class) when the body is a stream/array of many objects. Both return reactive publishers you then chain onto.

open as a page

How do you build a ServerResponse, and what is the difference between .body(...) and .bodyValue(...)?

middlemust knowfreq 50%

basics

~10 s

Use the builder: ServerResponse.ok() (or .status(...), .created(uri), etc.), set headers, then a terminal call. Use bodyValue(obj) for a plain already-available object; use body(publisher, Class) when the body is a Mono/Flux.

open as a page

How do you wire handler beans into routes with a RouterFunction, and how does the request reach the right handler method?

seniorshould knowfreq 45%

basics

~10 s

Define a @Bean RouterFunction<ServerResponse> using RouterFunctions.route(), mapping each path+method predicate to a handler method reference (e.g. .GET("/users/{id}", handler::getUser)). Spring uses the router to dispatch each request to the matching handler.

open as a page

In a functional WebFlux endpoint, how do you handle errors and empty results so the client gets the right status, and what threading pitfalls must you avoid?

principalshould knowfreq 35%

basics

~10 s

Keep everything in the reactive chain: use switchIfEmpty to turn an empty Mono into a 404/400 response, and onErrorResume to map exceptions to error responses. Never block; always return the composed Mono<ServerResponse>.

open as a page

§explore

▾roadmaps that cover this3

§questions

What is a HandlerFunction<ServerResponse> in Spring WebFlux, and how does it differ from an annotated @RestController method?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~2 min

▾common follow-ups2 questions

▾red flags4 flags

§ context

▾related questions7 questions

▾related topics4 topics

How do you extract the request body inside a HandlerFunction, and when do you use bodyToMono versus bodyToFlux?

basics

How do you build a ServerResponse, and what is the difference between .body(...) and .bodyValue(...)?

basics

How do you wire handler beans into routes with a RouterFunction, and how does the request reach the right handler method?

basics

In a functional WebFlux endpoint, how do you handle errors and empty results so the client gets the right status, and what threading pitfalls must you avoid?

basics

explore

questions

answer

go deeper

context