Spring - API 예외 처리 (ExceptionHandler, ControllerAdvice)

 

2024.01.01 - [Spring] - Spring - API 예외 처리 (HandlerExceptionResolver, ExceptionResolver ) 이론

Spring - API 예외 처리 (HandlerExceptionResolver, ExceptionResolver ) 이론

@ExceptionHandler 와 @ControllerAdvice 의 장점을 명확히 알기 위해선, 이를 사용하지 않았을 때 얼마나 불편한지 알아야한다.

위의 게시글을 타고 들어가면, @ExceptionHandler 와 @ControllerAdvice 의 진가를 더 잘 알 수 있을 것이다.

---

@ExceptionHandler를 사용하지 않는다면?

HandlerExceptionResolver 를 직접 사용하는데 복잡한 과정이 필요하다.

 

API 오류 응답의 경우 response 에 직접 데이터를 넣어야 하고, ModelAndView 를 반환해야 한다.

이는 다양한 상황과 조건에 맞게 오류에 대처해야하는 API에는 잘 맞지 않는다.

 

특정 컨트롤러에서만 발생하는 예외를 별도로 처리하기 어렵다.

예를 들어서 회원을 처리하는 컨트롤러에서 발생하는 RuntimeException 예외와 상품을 관리하는 컨트롤러에서 발생하는 동일한 RuntimeException 예외를 서로 다른 방식으로 처리하고 싶다면 어떻게 해야할까?

---

@ExceptionHandler

스프링은 ExceptionHandlerExceptionResolver 를 기본으로 제공하고, 기본으로 제공하는 ExceptionResolver 중에 우선순위도 가장 높다. 실무에서 API 예외 처리는 대부분 이 기능을 사용한다.

 

@ExceptionHandler 예외 처리 방법

@ExceptionHandler 애노테이션을 선언하고, 해당 컨트롤러에서 처리하고 싶은 예외를 지정해주면 된다.

해당 컨트롤러에서 예외가 발생하면 이 메서드가 호출된다.

참고로 지정한 예외 또는 그 예외의 자식 클래스는 모두 잡을 수 있다.

 

예시 코드를 살펴보자.

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

@ExceptionHandler
public ResponseEntity<ErrorResult> userExHandle(UserException e) {
 log.error("[exceptionHandle] 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 exHandle(Exception e) {
 log.error("[exceptionHandle] ex", e);
 return new ErrorResult("EX", "내부 오류");
}

여기서 ErrorResult는 String code, String message를 생성자로 가지고 있는 테스트를 위해 정의한 객체이다.

 

@ExceptionHandler() 괄호 안에 지정할 오류 클래스를 정의하면 되는데, 이는 생략이 가능하다.

생략하면 메서드 파라미터의 예외가 지정된다.

 

또한 다음과 같이 다양한 예외를 지정할 수 있다.

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

 

 

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

자세한 파라미터와 응답은 다음 공식 메뉴얼을 참고하자.

https://docs.spring.io/spring-framework/docs/current/reference/html/web.html#mvc-ann-exceptionhandler-args

Redirecting...

 

@ExceptionHandler를 통해 예외를 잡아서 해결하면 WAS가 다시 sendError()를 통해 오류 페이지를 재호출할 필요가 없어진다. 자세한 실행 흐름을 봐보자.

 

예시 - IllegalArgumentException 처리

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

이를 호출해서, IllegalArgument 오류를 호출해보자.

실행 흐름

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

 

결과

{
 "code": "BAD",
 "message": "잘못된 입력 값"
}

 

---

@ExceptionHandler의 문제점

@ExceptionHandler를 통해서 우리는 api 예외 처리를 간단히 해결할 수 있었다.

그러나 해당 애노테이션은 사용되는 해당 컨트롤러에서만 적용이 가능하다는 문제점을 가지고 있다.

즉, 모든 컨트롤러에 글로벌하게 적용할 수 없다는 뜻이다.

스프링은 이를 해결할 수 있는 기능을 제공한다.

 

@ControllerAdvice

@ExceptionHandler 를 사용해서 예외를 깔끔하게 처리할 수 있게 되었지만, 정상 코드와 예외 처리 코드가 하나의 컨트롤러에 섞여 있다. @ControllerAdvice 또는 @RestControllerAdvice 를 사용하면 둘을 분리할 수 있다.

AOP와 같이 한 곳에서 모든 api 예외 처리를 글로벌하게 해결할 수 있게 된다.

 

코드로 살펴보자.

 

ExControllerAdvice를 새로 만들어준 뒤, 기존에 컨트롤러에 작성해두었던 api 예외 처리 부분을 가져온다.

@Slf4j
@RestControllerAdvice
public class ExControllerAdvice {

 @ResponseStatus(HttpStatus.BAD_REQUEST)
 @ExceptionHandler(IllegalArgumentException.class)
 public ErrorResult illegalExHandle(IllegalArgumentException e) {
 log.error("[exceptionHandle] ex", e);
 return new ErrorResult("BAD", e.getMessage());
 }
 
 @ExceptionHandler
 public ResponseEntity<ErrorResult> userExHandle(UserException e) {
 log.error("[exceptionHandle] 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 exHandle(Exception e) {
 log.error("[exceptionHandle] ex", e);
 return new ErrorResult("EX", "내부 오류");
 }
}

 

기존에 사용했던 컨트롤러에는 해당 예외 처리 부분을 제거해준다.

이렇게 작성한 뒤, 위에서 했던 illegalArgument 예외를 호출하면 그 전과 똑같이 작동하는 것을 알 수 있다.

(@RestControllerAdvice = ControllerAdvice + @ResponseBody)

 

@ControllerAdvice 정리

• @ControllerAdvice 는 대상으로 지정한 여러 컨트롤러에 @ExceptionHandler , @InitBinder 기능을 부여해주는 역할을 한다.
• @ControllerAdvice 에 대상을 지정하지 않으면 모든 컨트롤러에 적용된다. (글로벌 적용)
  • 대상을 따로 지정하면, 해당 부분에만 적용이 가능함.
• @RestControllerAdvice 는 @ControllerAdvice 와 같고, @ResponseBody 가 추가되어 있다. @Controller , @RestController 의 차이와 같다.

 

대상 컨트롤러 지정 방법

// Target all Controllers annotated with @RestController
@ControllerAdvice(annotations = RestController.class)
public class ExampleAdvice1 {}

// Target all Controllers within specific packages
@ControllerAdvice("org.example.controllers")
public class ExampleAdvice2 {}

// Target all Controllers assignable to specific classes
@ControllerAdvice(assignableTypes = {ControllerInterface.class,
AbstractController.class})
public class ExampleAdvice3 {}

▶ 특정 애노테이션이 있는 컨트롤러를 지정할 수 있다.

▶ 특정 패키지를 직접 지정할 수도 있다. 패키지 지정의 경우 해당 패키지와 그 하위에 있는 컨트롤러가 대상이 된다.

▶ 특정 클래스를 지정할 수도 있다.

 

---

정리

@ExceptionHandler 와 @ControllerAdvice 를 조합하면 api 예외를 깔끔하게 해결할 수 있다.