[Spring] Spring MVC: HandlerMapping

서론

Spring MVC가 동작하는 과정 중, DispatcherServlet이 컨트롤러에 접근하는 과정을 자세하게 설명하려고 한다.

 

---

HandlerMapping

식당으로 예시를 들어보자. 손님은 들어와서 다양한 주문을 하고 해당 주문을 효율적으로 처리하기 위한 시스템을 만들었다.

• 주문 접수원 (HandlerMapping)
• 전문 요리사 (컨트롤러/핸들러)

HandlerMapping (주문 접수원)

• 역할: "어떤 손님(요청)의 주문(URL)이 어떤 요리사(컨트롤러)에게 가야 할지"를 결정하고 연결해 준다.
• 설명: "스테이크" 주문은 '스테이크 전문 요리사'에게, "파스타" 주문은 '파스타 전문 요리사'에게 전달해야 함을 주문 접수원(HandlerMapping) 이 파악하고 연결한다.

==> HandlerMapping은 들어오는 웹 요청(URL)을 보고, 이 요청을 처리할 수 있는 컨트롤러(Controller)를 찾아준다.

 

// 이 매핑은 @Controller 어노테이션이 붙은 클래스와 @RequestMapping 어노테이션이 붙은 메서드를 스캔하여
// 특정 URL 요청이 왔을 때 어떤 컨트롤러의 어떤 메서드를 호출해야 할지 결정한다

@Controller
public class OrderController {

    @GetMapping("/order/steak") // 이 URL 요청이 오면
    public String orderSteak() { // 이 메서드가 실행되어야 한다고 HandlerMapping이 파악한다
        return "steakOrderPage";
    }

    @GetMapping("/order/pasta") // 이 URL 요청이 오면
    public String orderPasta() { // 이 메서드가 실행되어야 한다고 HandlerMapping이 파악한다
        return "pastaOrderPage";
    }
}
// 위 코드에서 /order/steak라는 요청이 오면 
// OrderController의 orderSteak() 메서드를 호출해야 한다고 HandlerMapping이 알려준다

---

HandlerMapping의 동작 원리

DispatcherServlet은 요청을 받으면, HandlerMapping에게 요청을 위임하여 해당 요청을 처리할 핸들러를 찾는 것을 가장 먼저 시작한다.

 

1. HanlerMapping 조회

DispatcherServlet은 설정된 HandlerMapping 빈들을 순회하며 요청을 처리할 Handler를 찾아달라고 요청. 우선순위(Order)에 따라 조회

 

2. Handler 검색

각 HandlerMapping 구현체는 자신만의 매핑 전략에 따라 요청 URL과 매핑되는 핸들러를 찾는다.

ex: @RequestMapping 어노테이션 기반 HandlerMapping은 클래스, 메서드에 붙은 @RequestMapping 정보를 분석 후 매핑

 

3. HandlerExecutionChain 반환

HandlerMapping이 요청에 해당하는 핸들러를 찾으면, 단순히 핸들러 객체만 반환하는 것이 아니라 HandlerExecutionChain 객체 반환 -> HandlerExecutionChain은 다음과 같은 정보가 포함된다.

• Handler 객체: 실제 요청을 처리할 컨트롤러의 메서드 (또는 해당 메서드를 감싸는 프록시 객체)
• Interceptor 목록: 해당 요청을 처리하기 전에, 후에, 그리고 완료 후에 실행될 HandlerInterceptor(인터셉터)들의 목록

 

4. HandlerAdapter 선택 (by DispatcherServlet)

DispatcherServlet은 HandlerExecutionChain에서 얻은 Handler 객체를 실제로 실행할 HandlerAdapter를 찾는다. Handler는 다양한 형태일 수 있으므로, HandlerAdapter는 핸들러의 종류에 따라 적절한 방식으로 핸들러를 호출하고 결과를 반환한다.

 

5. Handler 실행

선택된 HandlerAdapter가 HandlerExecutionChain에 있는 Handler 객체를 호출하여 요청을 처리

---

주요 HandlerMapping 구현체

• 스프링은 다양한 HandlerMapping 구현체를 제공하며, 개발자는 필요에 따라 이를 조합하여 사용
• 스프링 부트를 사용하지 않는 경우 명시적으로 설정해야 하지만, 스프링 부트에서는 기본적으로 많이 사용되는 HandlerMapping들을 자동으로 등록

 

RequestMappingHandlerMapping

• 특징: 스프링 3.1부터 도입된 가장 기본적인 HandlerMapping으로, @Controller 및 @RestController 어노테이션이 붙은 클래스와 @RequestMapping, @GetMapping, @PostMapping 등 요청 매핑 어노테이션이 붙은 메서드를 스캔하여 매핑 정보를 구성한다.
• 동작: 애플리케이션 시작 시점에 모든 컨트롤러 클래스를 스캔하여 @RequestMapping 어노테이션이 있는 메서드들을 찾고, 해당 메서드와 매핑될 URL 패턴 정보를 내부적으로 캐싱, 이후 요청이 들어오면 캐싱된 정보에서 가장 적합한 핸들러를 찾아 반환한다.
• 우선순위: 기본적으로 가장 높은 우선순위

BeanNameUrlHandlerMapping

• 특징: 빈의 이름을 URL로 사용하여 매핑. 즉, 스프링 컨테이너에 등록된 빈의 이름과 요청 URL이 일치하면 해당 빈을 핸들러로 사용한다.
• 예시: <bean name="/home.do" class="com.example.controller.HomeController"/> 와 같이 설정하면 '/home.do' 요청은 'HomeController' 빈으로 매핑
• 사용 빈도: @RequestMapping 등장 이후로는 거의 사용 X

SimpleUrlHandlerMapping

• 특징: 명시적으로 URL과 핸들러 빈을 매핑하는 방식. 설정 파일에 직접 URL과 핸들러를 맵 형태로 정의
• 예시: 

<bean class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
    <property name="mappings">
        <props>
            <prop key="/hello.do">myHelloController</prop>
            <prop key="/bye.do">myByeController</prop>
        </props>
    </property>
</bean>

• 사용 빈도: @RequestMapping 등장 이후로는 거의 사용 X

RouterFunctionMapping (Spring WebFlux)

• 특징: 함수형 프로그래밍 스타일로 라우팅을 정의할 수 있도록 하는 HandlerMapping. @Controller 기반의 어노테이션 방식 대신 RouterFunction을 사용하여 요청을 핸들러 함수에 매핑한다.
• 주로 사용되는 곳: Spring WebFlux에서 많이 사용. Spring MVC에서도 사용 가능하다.
• 예시:

@Configuration
public class RouterConfig {
    @Bean
    public RouterFunction<ServerResponse> route(MyHandler handler) {
        return route(GET("/hello"), handler::hello)
                .andRoute(GET("/bye"), handler::bye);
    }
}

---

HandlerMapping의 우선순위 (Order)

여러 개의 HandlerMapping이 등록되어 있을 때, DispatcherServlet은 Ordered 인터페이스를 구현하거나 @Order 어노테이션을 사용하여 정의된 우선순위(Order)에 따라 HandlerMapping을 순회한다.(낮은 숫자가 높은 우선순위)

• 가장 높은 우선순위: Ordered.HIGHEST_PRECEDENCE (Integer.MIN_VALUE)
• 가장 낮은 우선순위: Ordered.LOWEST_PRECEDENCE (Integer.MAX_VALUE)

DispatcherServlet은 초기화될 때(initHandlerMappings(ApplicationContext context)) 스프링 컨테이너에 등록된 모든 HandlerMapping 타입의 빈들을 찾은 뒤 정렬하여 내부적으로 List 형태로 유지

1. 모든 HandlerMapping 빈 조회
2. AnnotationAwareOrderComparator를 통한 정렬
   • Ordered 인터페이스를 구현한 빈의 getOrder() 메서드 반환 값
   • @Order 어노테이션에 지정된 값
3. 정렬된 리스트 유지 후 요청 시 순차적 조회

@Nullable
protected HandlerExecutionChain getHandler(HttpServletRequest request) throws Exception {
    if (this.handlerMappings != null) {
        for (HandlerMapping mapping : this.handlerMappings) { // 정렬된 리스트 순차 조회
            // 각 HandlerMapping에게 요청을 처리할 수 있는 핸들러를 요청
            HandlerExecutionChain handler = mapping.getHandler(request);
            if (handler != null) {
                // 핸들러를 찾으면 즉시 반환하고 다음 HandlerMapping은 조회하지 않음
                return handler;
            }
        }
    }
    return null; // 모든 HandlerMapping이 핸들러를 찾지 못함
}

 

Default Order

• RequestMappingHandlerMapping: 기본적으로 0 (가장 높은 우선순위)
• SimpleUrlHandlerMapping: Integer.MAX_VALUE - 1 또는 그에 준하는 매우 낮은 우선순위
• BeanNameUrlHandlerMapping, ControllerClassNameHandlerMapping: 스프링 부트에서는 기본적으로 등록되지 않거나, 등록되더라도 매우 낮은 우선순위

명시적 Order

개발자는 Order값을 명시적으로 지정해 우선순위를 조절할 수 있다.

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Bean
    public SimpleUrlHandlerMapping customSimpleUrlHandlerMapping() {
        SimpleUrlHandlerMapping mapping = new SimpleUrlHandlerMapping();
        Properties urlMappings = new Properties();
        urlMappings.put("/customUrl", "myCustomController");
        mapping.setMappings(urlMappings);
        mapping.setOrder(1); // RequestMappingHandlerMapping (order=0) 보다 낮은 우선순위
        return mapping;
    }

    @Bean
    public MyCustomController myCustomController() {
        return new MyCustomController();
    }
}