[Spring Boot] @ExceptionHandler, @ControllerAdvice (Exception 공통 처리)

🚀 Exception 공통 처리

보통 예외는 3가지 방법으로 처리할 수 있다.

• 예외 복구 : 예외가 발생하면 예외 상황에 알맞게 처리하여 복구한다. (try, catch)
• 예외 회피 : 예외를 직접 처리하지 않고 예외를 상위 메소드에 위임한다. (throw)
• 예외 전환 : 예외를 위임하되 발생한 예외를 그대로 위임하는 것이 아닌 적절한 예외로 전환하여 위임한다. (restTemplate.doExecute)

이때 예외 복구에 대한 범위는 아래와 같다.

• 메소드 영역 : 메소드 영역은 종속된 복구 기능으로 단순히 try, catch 사용하면 된다.
• 클래스 영역 : 클래스 내 공통 예외 복구는 @ExceptionHandler를 사용하면 된다.
• 전역 영역 : 여러 클래스의 공통 예외 복구는 @ControllerAdvice를 사용하면 된다.

즉, '@ ExceptionHandler'을 사용하면 하나의 클래스 내에 있는 Exception에 대한 처리가 가능하다.

하지만 위와 같은 방법은 모든 클래스/함수에서 예외 처리에 대한 코드를 작성해야 하기 때문에 코드의 중복이 발생하고 예외 처리에 대한 통일성이 없을 수 있다.

`@ExceptionHandler`, `@ControllerAdvice`를 함께 사용하면 Exception을 전역적으로 처리할 수 있다.

(HandlerExceptionResolver를 사용해도 공통 처리할 수 있지만 사용법이 약간 복잡하고 응답에 message를 담을 수 없기 때문에 SpringBoot에선 주로 `@ExceptionHandler`, `@ControllerAdvice`를 사용해서 처리한다.)

---

🚀 @ExceptionHandler

`@ExceptionHandler`는 `@Controller`, `@ControllerAdvice`가 적용된 클래스에서 사용할 수 있다.

`@Controller`가 적용된 Controller 클래스 안에서 `@ExceptionHandler`를 사용하면 해당 Controller 안에서 발생하는 Exception만 처리할 수 있다.

 
@RestController
@RequestMapping("/api")
public class SampleController {
 
    @GetMapping("/example")
    public String exampleEndpoint() {
        throw new RuntimeException("This is a sample exception");
    }
 
    @ExceptionHandler(RuntimeException.class)
    public ErrorResponse handleRuntimeException(RuntimeException ex) {
        return new ErrorResponse("Runtime Error: " + ex.getMessage());
    }
}
 

따라서 Controller 클래스가 여러 개라면 모든 클래스 안에 `@ExceptionHandler`에 대한 코드를 작성해서 처리해야 하기 때문에 코드가 중복되고 일관적인 에러 처리가 어려워진다.

반면에 '@ControllerAdvice'가 적용된 클래스 안에서 사용하면 모든 Controller 클래스에 대해 전역적으로 Exception 처리가 가능해진다.

---

🚀 @ControllerAdvice

`@ControllerAdvice`는 `@Controller`가 사용된 모든 클래스에서 발생하는 모든 Exception을 공통적으로 처리할 수 있다.

(`@RestController`가 사용된 클래스에 대한 Exception도 처리한다.)

이때 `@ControllerAdvice`를 선언한 클래스 안에서 `@ExceptionHandler`를 정의하여 원하는 Exception별로 분류하여 Exception 처리를 진행한다.

'@ControllerAdvice'를 사용하는 예제는 아래와 같다.

@ControllerAdvice
public class ExceptionAdvisor {
   
    @ExceptionHandler(Exception.class)
    public ResponseEntity<CommonResponseVO> customExceptionHandler(Exception exception) {
      log.error(exception.getMessage(), exception);
      return ResponseUtil.createFailResponse(StatusCodeMessageConstant.BAD_REQUEST, HttpStatus.BAD_REQUEST);
    }
 
    @ExceptionHandler(ApplicationException.class)
    public ResponseEntity<CommonResponseVO> applicationExceptionHandler(ApplicationException applicationException){
      log.error(applicationException.getMessage(), applicationException);
      return ResponseUtil.createFailResponse(applicationException.getStatusCodeMessage());
    }
 
   @ExceptionHandler({
          ConstraintViolationException.class
          , MethodArgumentTypeMismatchException.class
          , HttpMessageNotReadableException.class
   })
    public ResponseEntity<CommonResponseVO> invalidParameterValueExceptionHandler(Exception exception) {
      log.error(exception.getMessage(), exception);
      return ResponseUtil.createFailResponse(StatusCodeMessageConstant.PARAMETER_VALUE_ERROR, HttpStatus.BAD_REQUEST);
   }
 
   @ExceptionHandler({
          MissingServletRequestParameterException.class
          , MethodArgumentNotValidException.class
          , BindException.class
   })
   public ResponseEntity<CommonResponseVO> invalidMandatoryParameterExceptionHandler(Exception exception) {
      log.error(exception.getMessage(), exception);
      return ResponseUtil.createFailResponse(StatusCodeMessageConstant.MANDATORY_PARAMETER_ERROR, HttpStatus.BAD_REQUEST);
   }
}

'@RestControllerAdvice'를 사용하는 예제는 아래와 같다.

 
// 모든 예외를 처리하는 RestControllerAdvice 클래스
@RestControllerAdvice
public class ExceptionHandlerController {
 
    // CustomException 발생 시 처리
    @ExceptionHandler(CustomException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleCustomException(CustomException ex) {
        return new ErrorResponse("Custom Error: " + ex.getMessage());
    }
 
    // 모든 기타 예외를 처리
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ErrorResponse handleException(Exception ex) {
        return new ErrorResponse("Internal Server Error");
    }
 
}
 

---

🚀 ResponseStatusException

Spring 5 버전부터는 ResponseStatusException 클래스를 사용할 수 있다고 한다.

간단하게 HTTP 응답 코드와 메세지를 만들어서 사용할 수 있는 장점이 있지만 공통 처리를 위해 사용하기에는 적합하지 않다고 한다.

@GetMapping("/user/{id}")
public ResponseEntity method(@PathVariable Long id){
    try{
        return service.metohd(id);
    }catch(Exception e)
        throw new ResponseStatusException(HttpStatus.NOT_FOUND,"error");
    }
}

---

🚀 ResponseUtility

RESTful API는 ResponseEntity를 갖으며 여러 HTTP 상태 코드와 메세지를 만들기 위해서 ResponseUtility를 사용하기도 한다.

상황에 따라 success와 fail을 나누어서 사용하기도 한다. fail은 Exception을 발생시키지 않고 내부적으로 응답 안에 status를 만들어 성공, 실패 여부를 반환한다.

✔️ @UtilityClass를 사용하면 (1) final 클래스로 생성하고 (2) private 생성자를 자동으로 생성하고 (3) 내부 함수를 정적 메서드로 사용할 수 있다.

@UtilityClass
public class ResponseUtility {
     
    public ResponseEntity<CommonResponseVO> createSuccessResponse() {
        return this.createSuccessResponse(null, HttpStatus.OK);
    }
     
    public ResponseEntity<CommonResponseVO> createSuccessResponse(CommonResponseVO commonResponseVO) {
        return this.createSuccessResponse(commonResponseVO, HttpStatus.OK);
    }
     
    public ResponseEntity<CommonResponseVO> createSuccessResponse(HttpStatus httpStatus) {
        return this.createSuccessResponse(null, httpStatus);
    }
 
    public ResponseEntity<CommonResponseVO> createSuccessResponse(CommonResponseVO commonResponseVO, HttpStatus httpStatus) {
        return ResponseEntity.status(httpStatus).body(commonResponseVO);
    }
}

---

🚀 참고. @RestController vs @Controller / @RestControllerAdvice VS @ControllerAdvice

@Controller와 @RestController, @ControllerAdvice와 @RestControllerAdvice 비슷한 2개의 어노테이션은 비슷한 기능을 수행하지만 약간의 차이점이 존재한다.

각 어노테이션의 코드를 따라가보면 `@RestController`는 `@Controller` + `@ResponseBody`이고 `@RestControllerAdvice`는 `@ControllerAdvice` + `@ResponseBody`인 것을 볼 수 있다.

Controller와 ControllerAdvice 내부를 보면 아래와 같다.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Controller { ... }
 
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface ControllerAdvice { ... }

RestController와 RestControllerAdvice 내부를 보면 아래와 같다.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController { ... }
 
 
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ControllerAdvice
@ResponseBody
public @interface RestControllerAdvice { ... }

즉, @Rest~로 시작하는 어노테이션에는 `@ResponseBody`를 포함되어 있고 이는 주로 RESTful API의 응답 데이터를 만드는데 사용된다는 것을 알 수 있다.

@Controller

• 주로 전통적인 Spring MVC의 Controller를 나타낸다.
• View를 반환하며, 주로 JSP, Thymeleaf, Freemarker 등과 같은 템플릿 엔진을 이용하여 HTML 페이지를 생성한다.
• 반환되는 데이터가 주로 모델(Model)을 통해 View에 전달되어 화면을 렌더링하는 데 사용된다.
  
  

@RestController

• 주로 RESTful 웹 서비스를 처리할 때 사용된다.
• `@ResponseBody` 어노테이션을 포함하고 있고 메서드 자체가 응답 데이터를 반환하며, 주로 JSON 또는 XML 형식으로 데이터를 반환한다.

 

하지만 RESTful API에서 반드시 @Rest~를 사용해야 하는 것은 아니다.

예를들어 `@ExceptionHandler`는 어떠한 응답 객체도 가질 수 있기 때문에 `@ControllerAdvice`로 예외를 수집하고 RESTful API처럼 ResponseEntity 객체를 만들어서 사용할 수 있다.

@ControllerAdvice
public class ExceptionAdvice {
    @ExceptionHandler({RuntimeException.class, Exception.class})
    protected CommonResponseEntity handleRuntimeException(RuntimeException e) {
        return CommonResponseEntity.builder()
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .code("INTERNAL_SERVER_ERROR")
                .message(e.getMessage())
                .build();
    }
}