API 예외처리 - @ExceptionHandler

HTML 화면 오류 VS API 오류

웹 브라우저에 HTML 화면을 제공할 때는 오류가 발생하면 BasicErrorController를 사용하는게 편하다.
이때는 단순히 5xx,4xx 관련된 오류 화면을 보여주면 된다. BasicErrorController는 이런 메커니즘을 모두 구현해 두었기 때문이다.

하지만 API는 각 시스템마다 응답의 모양도 다르고, 스펙도 모두 다르다. 예외 상항에 단순히 오류 화면을 보여주는 것이 아니라,
예외에 따라서 각각 다른 데이터를 출력해야 할 수도 있다.
그리고 같은 예외라고 해도 어떤 컨트롤러에서 발생했는가에 따라서 다른 예외 응답을 내려주어야 할 수 있다.
한마디로 매우 세밀한 제어가 필요하다.

때문에 BasicErrorController를 사용하거나 HandlerExceptionResolver를 직접 구현하는 방식으로 API 예외를 다루기는 쉽지 않다.

API 예외처리의 어려운점

• HandlerExceptionResolver를 떠올려 보면 ModelAndView를 반환해야 했다. 이것은 API응답에는 필요하지 않다.
• API 응답을 위해서 HttpServletResponse에 직접 응답 데이터를 넣어주었다. 이것은 매우 불편하다. 스프링 컨트롤러에 비유하면 마치 과거 Servelt을 사용하던 시절로 돌아간 것 같다.
• 특정 컨트롤러에서만 발생하는 예외를 별도로 처리하기 힘들다.
  - 예를 들어서 회원을 처리하는 컨트롤러에서 발생하는 RuntimeException예외가 상품을 관리하는 컨트롤러에서 발생하는 동일한 RuntimeException예외를 서로 다른 방식으로 처리하고 싶다면 어떻게 해야할까?

@ExceptionHandler

스프링은 API 예외 처리 문제를 해결하기 위해 @ExceptionHandler라는 애노테이션을 사용하는 매우 편리한 예외 처리 기능을 제공하는데 이것이 바로 ExceptionHandlerExceptionResolver이다.
스프링은 ExceptionHandlerExceptionResolver를 기본으로 제공하고, 기본으로 제공하는 ExceptionResolver중에 우선순위도 가장 높다.
실무에서는 대부분 이 기능을 사용한다.

ErrorResult

@Data
@AllArgsConstructor
public class ErrorResult {

    private String code;
    private String message;
}

API Controller

@Slf4j
@RestController
public class ApiExceptionV2Controller {


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


    @GetMapping("/api2/members/{id}")
    public MemberDto getMember(@PathVariable("id") String id) {
        if ("ex".equals(id)) {
            throw new RuntimeException("잘못된 사용자");
        }

        if ("bad".equals(id)) {
            throw new IllegalArgumentException("잘못된 입력값");
        }

        if ("user-ex".equals(id)) {
            throw new UserException("사용자 오류");
        }

        return new MemberDto(id, "hello " + id);
    }
}

Controller에서 IllegalArgumentException 예외가 발생하면 ExceptionResolver에서 예외 해결을 시도한다.
ExceptionResolver의 가장 우선순위에 있는 ExceptionHandlerExceptionResolver에서 먼저 해결을 시도한다.
ExceptionHandlerExceptionResolver는 Controller에서 @ExceptionHandler 애노테이션이 있는지 찾는다.
만약 찾았다면 @ExceptionHandler의 특성들을 살려서 코드를 호출한다.
이떄는 정상적인 흐름으로 바꿔서(Http Message Converting해서) 정상적으로 리턴해준다.
하지만 이때 정상 흐름으로 반환해주므로 HTTP의 상태코드는 200이다.

만약 이 때 HTTP의 상태코드 또한 바꾸고 싶다면

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

위의 코드와 같이 @ResponseStatus 애노테이션을 추가해주면 된다.

이렇게 @ExceptionHandler를 사용하면 API응답에서 세밀한 제어가 가능할 뿐만 아니라 ExceptionResolver에서 예외 처리를 해결해줌으로써 WAS까지 예외를 전달하지않아 WAS에서 다시 내부 요청하는 일이 발생하지 않는다.

ResponseEntity 사용

@ResponseStatus로 HTTP 상태코드를 바꿀 수도 있지만 ResponseEntity를 이용해서도 바꿀 수 있다.

    @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);
    }

캐치 하지 못한 Exception 처리

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

위의 코드와 같이 최상단의 Exception으로 정의하면 @ExceptionHandler에 정의되지 않은 예외들이 발생 시 해당 Exception 예외 처리가 발생한다. (가장 넓은 범위의 Exception)

@ExceptionHandler 예외 처리 방법 정리

@ExceptionHandler 애노테이션을 선언하고, 해당 컨트롤러에서 처리하고 싶은 예외를 지정해주면 된다. 해당 컨트롤러에서 예외가 발생하면 이 메소드가 호출된다.
참고로 지정한 예외 또는 그 예외의 자식 클래스는 모두 잡을 수 있다.

우선순위

스프링의 우선순위는 항상 자세한 것이 우선권을 가진다.
예를 들어서 부모,자식 클래스가 있고 다음과 같이 예외가 처리된다.

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

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

@ExceptionHandler에 지정한 부모 클래스는 자식 클래스까지 처리할 수 있다. 따라서 자식예외가 발생하면 부모예외처리(), 자식 예외처리() 둘다 호출 대상이 된다. 그런데 둘 중 더 자세한 것이 우선권을 가지므로 자식예외처리()가 호출된다.
물론 부모예외가 호출되면 부모예외처리()만 호출대상 이므로 부모예외처리()가 호출된다.

다양한 예외

다음과 같이 다양한 예외를 한번에 처리할 수 있다.

@ExceptionHandler({AException.class, BException.class})
public String ex(Exception e) {
	log.info("exception e", e);
}

예외 생략

@ExceptionHandler에 예외를 생략할 수 있다. 생략하면 메소드 파리머터의 예외가 지정된다.

@ExceptionHandler
public ResponseEntity<ErrorResult> userExHandler(UserException e) {}

파라미터와 응답

@ExceptionHandler에는 마치 스프링의 컨트롤러의 파라미터 응답처럼 다양한 파라미터와 응답을 지정할 수 있다.

IllegalArgumentException 처리 실행 흐름 정리

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

1. 컨트롤러를 호출한 결과 IllegalArguemntException 예외가 컨트롤러 밖으로 던져진다.
2. 예외가 발생했으므로 ExceptionResolver가 작동한다. 가장 우선순위가 높은 ExceptionHandlerExceptionResolver가 실행된다.
3. ExceptionHandlerExceptionResolver는 해당 컨트롤러에 IllegalArgumentException을 처리할 수 있는 @ExceptionHandler가 있는지 확인한다.
4. illegalExHandler()를 실행한다. @RestController이므로 illegalExHandler()에도 @ResponseBody가 적용된다.
   따라서 HTTP 컨버터가 사용되고, 응답이 다음과 같은 JSON으로 반환된다.
5. @ResponseStatus(HttpStatus.BAD_REQUEST)를 지정했으므로 HTTP 상태코드 400으로 응답한다.

기타 - HTML 오류 화면 (잘 사용하지 않음)

ModelAndView를 사용해서 오류 화면을 응답하는데 사용할 수도 있다.

@ExceptionHandler(ViewException.class)
public ModelAndView ex(ViewException e) {
	return new ModelAndView("error");
}