[Spring Boot] 핸들러 인터셉터(Handler Interceptor)

 

핸들러 인터셉터란?

핸들러 인터셉터는 Spring에서 요청 전후 처리를 담당하는 컴포넌트로, Filter와는 달리 DispatcherServlet 수준에서 작동합니다. 이 컴포넌트는 컨트롤러에 도달하기 전, 후, 그리고 뷰 렌더링 직전에 특정 로직을 수행할 수 있게 해줍니다.

 

 

핸들러 인터셉터 인터페이스 메소드 설명

CustomInterceptor 클래스

@Slf4j
@Component
public class CustomInterceptor implements HandlerInterceptor {


    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        log.info("컨트롤러 진입 전 호출");
        return HandlerInterceptor.super.preHandle(request, response, handler);
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        log.info("컨트롤러 진입 후 호출");
        HandlerInterceptor.super.postHandle(request, response, handler, modelAndView);
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        log.info("응답 반환 직전 호출");
        HandlerInterceptor.super.afterCompletion(request, response, handler, ex);
    }
}

 

메소드 설명

1. preHandle:
   • 컨트롤러 진입 전에 호출됩니다.
   • 반환 값이 true일 경우 컨트롤러로 요청을 전달하고, false일 경우 요청 처리를 중단합니다.
2. postHandle:
   • 컨트롤러의 요청 처리 후 호출됩니다.
   • 모든 로직이 종료된 후, ModelAndView를 통해 추가 작업을 수행할 수 있습니다. 예를 들어, 응답에 추가 정보를 삽입하거나, View를 변경할 수 있습니다.
3. afterCompletion:
   • 모든 처리가 완료된 후, 응답이 반환되기 직전에 호출됩니다.
   • 이 메소드는 요청 처리 중 발생한 예외를 확인할 수 있으며, 리소스 정리와 같은 후처리를 수행하는 데 유용합니다.

인터셉터 설정하기

핸들러 인터셉터를 Spring MVC에 설정하는 방법은 다음과 같습니다.

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {

    private final CustomInterceptor customInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(customInterceptor)
                .addPathPatterns("/**");
    }
}

 

 

핸들러 인터셉터를 활용한 간단한 검증 만들기

해당 요청이 OpenApi인지 확인하기

 

 

OpenApi 어노테이션

@Target(value = {ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface OpenApi {

}

 

 

Open Controller

@Slf4j
@RestController
public class OpenController {

    @OpenApi
    @GetMapping("/test1")
    public void test1() {
        log.info("test1");
    }


    @GetMapping("/test2")
    public void test2() {
        log.info("test2");
    }
}

 

핸들러 인터셉터의 OpenApi 검증

@Slf4j
@Component
public class CustomInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        log.info("컨트롤러 진입 전 호출");

        HandlerMethod handlerMethod = (HandlerMethod) handler;

        // 메소드에 OpenApi 어노테이션이 붙어있는지 확인
        var methodLevel = handlerMethod.getMethodAnnotation(OpenApi.class);
        if (methodLevel != null) {
            log.info("method level");
            return true;
        }

        // 클래스에 OpenApi 어노테이션이 붙어있는지 확인
        var classLevel = handlerMethod.getBeanType().getAnnotation(OpenApi.class);
        if (classLevel != null){
            log.info("class level");
            return true;
        }

        log.info("어노테이션이 없습니다");
        return false;
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        log.info("컨트롤러 진입 후 호출");
        HandlerInterceptor.super.postHandle(request, response, handler, modelAndView);
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        log.info("응답 반환 직전 호출");
        HandlerInterceptor.super.afterCompletion(request, response, handler, ex);
    }
}

 

결과 화면

 

 

핸들러 인터셉터 정리

• Spring MVC에서 DispatcherServlet 이후 동작합니다.
• 요청 처리 및 컨트롤러/뷰 렌더링 단계에서 작동합니다.
• addPathPatterns() 메소드를 통해 세밀한 요청 경로 제어가 가능합니다.
• 인증, 권한 검사, 로깅 등 다양한 상황에서 활용됩니다.