[Spring WebFlux] 3. DispatcherHandler

0. DispatcherHandler란?

• WebFlux 요청 처리의 중심
• ✅ FrontController 역할을 담당함 (DispatcherServlet와 비슷)
• ✅ 'webHandler'란 이름으로 빈 등록되며, WebHttpHandlerBuilder가 주변 구성요소들을 모아 WebFlux 처리 Chain에 넣어줌
• ✅ 다양한 Delegate Component를 활용하여 적절한 Handler를 호출함

 

1. Special Bean Types

• DispatcherHandler는 요청을 직접 전부 처리하지 않고, Spring Bean들에게 작업을 위임함

Bean Type	역할	대표 구현체
HandlerMapping	Request를 처리할 Handler를 찾음 (가장 먼저 매칭된 Handler가 선택됨)	- RequestMappingHandlerMapping - RouterFunctionMapping - SimpleUrlHandlerMapping
HandlerAdapter	찾은 Handler를 실제 실행하고 결과를 HandlerResult로 반환	- Annotation Controller 호출 - Argument 해석 등
HandlerResultHandler	HandlerResult를 처리하여 HTTP Response를 직접 작성하거나 View를 Rendering	반환값을 Response Body/Status 등으로 처리

 

2. WebFlux Config

• 요청을 처리하기 위한 WebFlux 관련 빈들을 자동 설정해주는 체계
• ex) DispatcherHandler, HandlerMapping, HandlerAdapter
• ✅ 필요한 부분만 고수준 API로 Customize 할 수 있게 해줌

 

3. Processing

순서	구성요소	역할	핵심 결과
1	Reactor Netty	실제 Non-Blocking Network I/O 처리	HTTP Request 수신
2	ReactorHttpHandlerAdapter	Reactor Netty의 요청/응답을 Spring HttpHandler에 연결	Server API → WebFlux API 변환
3	HttpHandler	WebFlux의 저수준 HTTP 처리 진입점	Reactive Request Processing 시작
4	WebFilter Chain	Request/Response 전후 공통 처리	다음 Filter 또는 WebHandler 호출
5	DispatcherHandler	Front Controller로 전체 요청 처리 흐름 조정	Delegate Component 호출
6	HandlerMapping	Request와 매칭되는 Controller / Handler 탐색	Handler 선택
7	HandlerAdapter	선택된 Handler를 실행할 수 있도록 처리	Handler 실행
8	Controller / Handler	Application Logic 실행	Mono / Flux 등 반환
9	HandlerResult	Handler 실행 결과와 처리에 필요한 정보 보관	실행 결과 전달
10	HandlerResultHandler	HandlerResult를 실제 HTTP Response로 처리	Body 작성 / View Rendering
11	Reactor Netty	만들어진 Response를 Network로 전송	Client에 HTTP Response 전달

 

4. Result Handling

• HandlerAdapter가 Handler를 실행하면 HandlerResult로 감싼 뒤 적절한 HandlerResultHandler에게 전달함

 

종류

HandlerResultHandler	처리 대상	주 사용처	기본 Order
ResponseEntityResultHandler	ResponseEntity	@Controller, @RestController에서 상태코드/Header/Body 직접 제어	0
ServerResponseResultHandler	ServerResponse	Functional Endpoint	0
ResponseBodyResultHandler	@ResponseBody 반환값	@RestController, @ResponseBody	100
ViewResolutionResultHandler	String, View, Model, Map, 기타 Model 객체	View Rendering	Integer.MAX_VALUE

 

예제) ResponseEntityResultHandler

@GetMapping("/users/{id}")
Mono<ResponseEntity<User>> getUser(@PathVariable Long id) {
    return userService.findById(id)
        .map(user -> ResponseEntity.ok(user))
        .defaultIfEmpty(ResponseEntity.notFound().build());
}

• ➡️ Status / Header / Body를 직접 제어하고 싶을 때

 

예제) ServerResponseResultHandler

Mono<ServerResponse> getUser(ServerRequest request) {
    String id = request.pathVariable("id");

    return userService.findById(id)
        .flatMap(user ->
            ServerResponse.ok().bodyValue(user)
        )
        .switchIfEmpty(
            ServerResponse.notFound().build()
        );
}

• ➡️ Functional Endpoint의 Response 처리

 

예제) ResponseBodyResultHandler

@RestController
class UserController {

    @GetMapping("/users/{id}")
    Mono<User> getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

 

5. Exceptions

• 요청 처리 중 발생한 Exception은 HandlerAdapter와 DispatcherHandler가 함께 처리할 수 있음

발생 위치	처리 방식
Controller/Handler 실행 중 즉시 발생	HandlerAdapter가 내부적으로 처리 가능
Handler가 반환한 Mono/Flux에서 나중에 Error 발생	HandlerResult에 연결된 DispatchExceptionHandler가 처리 가능
HandlerMapping 과정에서 발생한 Exception	DispatcherHandler가 DispatchExceptionHandler를 적용 가능
WebFilter 등 WebHandler Chain 앞단에서 발생한 Exception	WebExceptionHandler가 처리

 

 

예제) Controller/Handler 실행 중 즉시 발생

@GetMapping("/users/{id}")
Mono<User> getUser(...) {
    throw new RuntimeException("error");
}

 

예제) Handler가 반환한 Mono/Flux가 나중에 Error 발생

@GetMapping("/users/{id}")
Mono<User> getUser(...) {
    return userService.findById(id)
        .map(user -> {
            throw new RuntimeException("error");
        });
}

• 나중에 Pipeline 실행 중 onError가 발생함.
• ✅ HandlerAdapter가 반환한 HandlerResult에 DispatchExceptionHandler를 연결할 수 있음
• ➡️ HandlerResult → Reactive 처리 중 Error → DispatchExceptionHandler

 

예제) HandlerMapping 과정에서 Error 발생

• HandlerMapping → ErrorHandlerMapping Error → DispatcherHandler → DispatchExceptionHandler

 

예제) 앞단에서 Error 발생 (WebFilter)

• Request → WebFilter → Error
• DispatcherHandler 내부까지 도달하지 못한 경우
• 상위 WebHandler chain의 WebExceptionHandler가 처리함

 

6. View Resolution

Handling

Redirecting

Content Negotiation

 

출처

• Spring WebFlux - DispatcherHandler