API 예외 처리

API 서버는 예외 발생 시 각 예외 상황에 맞는 오류 응답 스펙을 정하고, 스펙에 맞는 데이터를 응답해야 한다. API 서버는 HTTP 요청 시 JSON 데이터를 응답한다고 가정한다.

서블릿 예외 처리 방식

서블릿 예외 처리 방식으로 예외 발생 시 API 응답 방식을 알아보자. 먼저 ErrorPage로 처리할 예외와 경로를 지정한다.

package hello.exception;

import org.springframework.boot.web.server.ConfigurableWebServerFactory;
import org.springframework.boot.web.server.ErrorPage;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;

@Component
public class WebServerCustomizer implements WebServerFactoryCustomizer<ConfigurableWebServerFactory> {
    @Override
    public void customize(ConfigurableWebServerFactory factory) {
        ErrorPage errorPage404 = new ErrorPage(HttpStatus.NOT_FOUND, "/error-page/404");
        ErrorPage errorPage500 = new ErrorPage(HttpStatus.INTERNAL_SERVER_ERROR, "/error-page/500");
        ErrorPage errorPageEx = new ErrorPage(RuntimeException.class, "/error-page/500");

        factory.addErrorPages(errorPage404, errorPage500, errorPageEx);
    }
}

그리고 위의 경로를 처리하는 컨트롤러에서 JSON 데이터를 응답한다.

@RequestMapping(value = "/error-page/500", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<Map<String, Object>> errorPage500Api(
        HttpServletRequest request, HttpServletResponse response) {

    log.info("API errorPage 500");
    HashMap<String, Object> result = new HashMap<>();
    Exception ex = (Exception) request.getAttribute(ERROR_EXCEPTION);
    result.put("status", request.getAttribute(ERROR_STATUS_CODE));
    result.put("message", ex.getMessage());

    Integer statusCode = (Integer) request.getAttribute(ERROR_STATUS_CODE);
    return new ResponseEntity<>(result, HttpStatus.valueOf(statusCode));
}

스프링 부트 예외 처리 방식

이번엔 스프링 부트 예외 처리 방식으로 예외 발생 시 API 응답 방식을 알아보자. 스프링 부트는 BasicErrorController가 예외 처리를 한다. (기본 예외 경로인 /error 처리)

 

아래는 BasicErrorController 코드의 일부분이다. 요청의 Accept 헤더 값이 text/html인 경우 뷰를 응답하고 그 외 경우 ResponseEntity로 JSON 데이터를 응답한다. 어떤 데이터를 응답하는지는 코드를 통해 확인하자. 만약 자신이 원하는 JSON 데이터를 응답하고 싶다면 BasicErrorController를 확장하면 된다.

@RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {}

@RequestMapping
public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {}

HandlerExceptionResolver

API 응답에서 위 두 방식보다 @ExceptionHandler을 사용하는 방식이 더 편리하다. @ExceptionHandler을 이해하기 위해서는 HandlerExceptionResolver을 먼저 알아야 한다.

 

요청 매핑, 요청 핸들 과정에서 DispatcherServlet까지 예외가 전파되면 DispatcherServlet는 우선순위의 HandlerExceptionResolver에게 예외를 처리하고 오류 응답을 하도록 위임한다. 지금까지 예외 발생 시 서블릿 컨테이너까지 전파시킨 후 서블릿 컨테이너가 재요청함으로써 예외를 처리했는데 이 과정이 너무 복잡하다. 이제 HandlerExceptionResolver를 사용해 예외를 서블릿 컨테이너까지 전파시키지 않고 스프링 MVC 내에서 바로 예외를 처리해 보자.

HandlerExceptionResolver로 예외를 해결해도 인터셉터의 postHandle() 은 호출되지 않는다.

 

HandlerExceptionResolver 인터페이스

public interface HandlerExceptionResolver {

	@Nullable
	ModelAndView resolveException(
			HttpServletRequest request, HttpServletResponse response, @Nullable Object handler, Exception ex);
}

예외를 처리하는 resolveException 메서드를 정의한다. HandlerExceptionResolver의 반환 값에 따른 DispatcherServlet의 동작 방식은 아래와 같다.

• 빈 ModelAndView: 비어있는 ModelAndView를 반환하면 뷰를 렌더링 하지 않고, 정상 흐름으로 서블릿이 리턴된다.
• ModelAndView 지정: ModelAndView에 View, Model 정보를 지정해서 반환하면 뷰를 렌더링 한다.
• null: null을 반환하면, 다음 ExceptionResolver를 찾아서 실행한다. 만약 처리할 수 있는 ExceptionResolver가 없으면 예외 처리가 안되고, 기존에 발생한 예외를 서블릿 밖으로 던진다.

 

HandlerExceptionResolver 사용

직접 HandlerExceptionResolver를 사용해 보자. 아래는 UserException을 처리하는 HandlerExceptionResolver이다.

package hello.exception.resolver;

import com.fasterxml.jackson.databind.ObjectMapper;
import hello.exception.exception.UserException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.servlet.HandlerExceptionResolver;
import org.springframework.web.servlet.ModelAndView;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

@Slf4j
public class UserHandlerExceptionResolver implements HandlerExceptionResolver {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        try {
            if(ex instanceof UserException) {
                log.info("UserException resolver to 400");
                String acceptHeader = request.getHeader("accept");
                response.setStatus(HttpServletResponse.SC_BAD_REQUEST);

                if("application/json".equals(acceptHeader)) {
                    Map<String, Object> errorResult = new HashMap<>();
                    errorResult.put("ex", ex.getClass());
                    errorResult.put("message", ex.getMessage());
                    String result = objectMapper.writeValueAsString(errorResult);

                    response.setContentType("application/json");
                    response.setCharacterEncoding("utf-8");
                    response.getWriter().write(result);
                    return new ModelAndView();
                }
                else {
                    return new ModelAndView("error/500");
                }
            }
        } catch (IOException e) {
            log.error("resolver ex", e);
        }

        return null;
    }
}

그런데 직접 HandlerExceptionResolver를 구현하려고 하니 복잡하다. 지금부터 스프링이 제공하는 HandlerExceptionResolver들을 알아보자.

스프링 부트의 HandlerExceptionResolver

스프링 부트는 아래의 순서로 HandlerExceptionResolverComposite에 HandlerExceptionResolver를 등록한다. 번호가 작을수록 우선순위가 높다.

1. ExceptionHandlerExceptionResolver → @ExceptionHandler처리
2. ResponseStatusExceptionResolver → 스프링 MVC의 예외 발생 시 HTTP 상태 코드 지정
3. DefaultHandlerExceptionResolver → HTTP 상태 코드 지정

ResponseStatusExceptionResolver

예외에 따라서 HTTP 상태 코드를 지정한다. @ResponseStatus가 달려있는 예외, ResponseStatusException 예외를 처리하며 HTTP 상태 코드를 지정한다. (response.sendError 메서드를 호출한다.)

package hello.exception.exception;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;

@ResponseStatus(code = HttpStatus.BAD_REQUEST, reason = "잘못된 요청 오류")
public class BadRequestException extends RuntimeException {

}

위의 BadRequestException가 DispatcherServlet까지 전파되면 DispatcherServlet은 우선순위의 ExceptionResolver (ResponseStatusExceptionResolver라 가정)에게 예외 처리를 위임한다. ResponseStatusExceptionResolver는 HTTP 상태 코드를 400으로 지정한다. (내부적으로 response.sendError를 호출하기에 WAS에서 /error 경로로 재요청한다.)

DefaultHandlerExceptionResolver

스프링 MVC의 예외를 처리하며 HTTP 상태 코드를 지정한다. (response.sendError 메서드를 호출한다.) 스프링 MVC의 예외가 DispatcherServlet까지 전파되면 DispatcherServlet은 우선 순위의 ExceptionResolver (DefaultHandlerExceptionResolver라 가정)에게 예외 처리를 위임한다. DefaultHandlerExceptionResolver는 각 예외에 맞는 HTTP 상태 코드를 지정한다. (내부적으로 response.sendError를 호출하기에 WAS에서 /error 경로로 재요청한다.)

 

ex)

TypeMismatchException → 400 코드로 지정

handleBindException → 400 코드로 지정

ExceptionHandlerExceptionResolver

@Controller 컨트롤러 안의 @ExceptionHandler 메서드 또는 @ControllerAdvice(@RestControllerAdvice)로 예외를 처리한다.

 

오류 페이지를 반환할 때는 BasicErrorController를 사용하는 게 편하다. 하지만 API 예외 응답을 할 때는 같은 예외라도 어떤 컨트롤러에서 발생했는가에 따라서 예외 응답을 내려주어야 할 수 있다. 한마디로 매우 세밀한 제어가 필요하다. 이때 ExceptionHandlerExceptionResolver을 사용하면 @ExceptionHandler 등으로 예외를 처리해 세밀한 예외 API 응답을 할 수 있을 뿐만 아니라 @ExceptionHandler 메서드의 편리한 기능을 사용할 수 있다. (스프링 컨트롤러처럼 다양한 파라미터와 응답을 지정할 수 있다. 아래 링크 참고)

Exceptions :: Spring Framework

Exceptions :: Spring Framework

 

아래는 RestController에서 @ExceptionHandler 메서드를 작성한 예이다. 해당 컨트롤러에서 IllegalArgumentException 또는 그 하위 자식 예외가 발생하면 아래의 @ExceptionHandler 메서드가 예외를 처리한다.

@ExceptionHandler(IllegalArgumentException.class)
public ErrorResult illegalExHandle(IllegalArgumentException e) {
 	log.error("[exceptionHandle] ex", e);
 	return new ErrorResult("BAD", e.getMessage());
}

 

스프링의 우선순위는 항상 자세한 것이 먼저다. 아래와 같이 코드가 작성되어 있을 때 자식 예외가 발생하면 자식 예외를 처리하는 @ExceptionHandler 메서드가 먼저 호출되고 그다음으로 부모 예외를 처리하는 @ExceptionHandler 메서드가 호출된다.

@ExceptionHandler(부모예외.class)
public String 부모예외처리()(부모예외 e) {}

@ExceptionHandler(자식예외.class)
public String 자식예외처리()(자식예외 e) {}

@ControllAdvice

모든 컨트롤러마다 공통된 예외 처리 코드를 @ExceptionHandler 메서드로 작성한다면 코드가 중복된다. 이때 공통 관심사(공통 예외 처리 코드)를 분리해 한 곳으로 모으면 편할 것이다. @ControllerAdvice 또는 @RestControllerAdvice가 이 기능을 제공한다. @ExceptionHandler와 @ControllerAdvice를 조합하면 예외를 깔끔하게 해결할 수 있다.

package hello.exception.exception.advice;

import hello.exception.exception.UserException;
import hello.exception.exhandler.ErrorResult;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@Slf4j
@RestControllerAdvice
public class ExControllerAdvice {

    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(IllegalArgumentException.class)
    public ErrorResult illegalExHandler(IllegalArgumentException e) {
        log.error("[exceptionHandler] ex", e);
        return new ErrorResult("bad", e.getMessage());
    }

    @ExceptionHandler
    public ResponseEntity<ErrorResult> userExHandler(UserException e) {
        log.error("[exceptionHandler] ex", e);
        ErrorResult errorResult = new ErrorResult("USER-EX", e.getMessage());
        return new ResponseEntity<>(errorResult, HttpStatus.BAD_REQUEST);
    }

    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler
    public ErrorResult exHandler(Exception e) {
        log.error("[exceptionHandler] ex", e);
        return new ErrorResult("EX", "내부 오류");
    }
}