[Spring] Spring에서 `@RestControllerAdvice` 를 이용하여 전역적으로 중앙 집중화하여 에러 처리하기

관련 글을 먼저 읽어서 예외를 이해하고 진행하자

• 자바 예외 이해
• API 예외 처리

@RestControllerAdvice를 사용하는 이유

1. 전역 예외 처리 : @RestControllerAdvice는 애플리케이션에서 발생하는 모든 예외를 전역적으로 처리할 수 있다. 즉, 모든 컨트롤러에서 발생하는 예외를 일괄적으로 처리할 수 있으며, 중복된 예외 처리 코드의 작성을 피할 수 있다.

2. 중앙 집중식 예외 처리 : @RestControllerAdvice를 사용하면 예외 처리 로직을 한 곳에 집중시킬 수 있다. 예외 처리기를 하나의 클래스로 구현하고, 해당 클래스에 @ExceptionHandler 어노테이션을 사용하여 각 예외에 대한 처리 메서드를 정의할 수 있다. 이렇게 하면 예외 처리 로직을 효율적으로 관리하고 유지보수할 수 있다.

3. 커스텀 응답 처리 : @RestControllerAdvice를 사용하면 예외 발생 시 반환되는 응답을 커스터마이징 할 수 있다. 예외 처리 메서드에서 ResponseEntity 를 반환하여 상태 코드, 응답 본문 등을 자유롭게 조작할 수 있다. 이를 통해 클라이언트에게 일관된 형식의 응답을 제공하거나, 에러 메시지를 포함한 상세한 정보를 전달할 수 있다.

4. 다양한 예외 상황 처리 : @RestControllerAdvice를 사용하면 여러 예외 상황을 처리할 수 있다. 특정 예외 타입에 대한 처리뿐만 아니라, 특정 패키지, 컨트롤러, 메서드 등에 대한 예외 처리도 구현할 수 있다. 이를 통해 예외 처리의 범위를 세밀하게 제어할 수 있다.

5. RESTful API와의 호환성 : @RestControllerAdvice는 RESTful API를 개발할 때 더 적합한 기능과 특성을 제공한다. 예외 처리기에서 JSON 형식의 응답을 반환할 수 있으며, HTTP 상태 코드와 함께 예외 정보를 전달할 수 있다. 이는 클라이언트와의 통신에서 일관성을 유지하고, API의 안정성과 사용성을 향상시키는 데 도움이 된다.

@RestControllerAdvice 로 예외 처리하기

• @RestControllerAdvice 적용

@Slf4j
@RestControllerAdvice
public class ExceptionAdvice {

    @ExceptionHandler(NotFoundException.class)
    public ResponseEntity<?> notFoundException(NotFoundException e) {
        log.error("Error occurs {}", e.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
    }
}

먼저, 클래스에 @RestControllerAdvice 어노테이션을 선언해주어야 한다. 이렇게 하면 해당 클래스가 예외 처리를 담당하는 어드바이스 클래스로 동작하게 된다.

그리고 어떤 종류의 예외를 처리할 것인지를 정의해야 한다.

• @ExceptionHandler(NotFoundException.class)

  • 이 어노테이션을 사용하면 NotFoundException 클래스의 예외를 처리하는 메소드를 정의할 수 있다.
  • NotFoundException 클래스는 RuntimeException을 상속받아 재정의한 커스텀 예외로, 에러 메시지를 포함하고 있다.

    public class NotFoundException extends RuntimeException {
      public NotFoundException(String message) {
          super(message);
      }
    }

  • 해당 예외가 발생하면 notFoundException 메소드에 정의된 로직이 실행된다.
  • 이 예제에서는 간단히 log.error 를 사용하여 에러 메시지를 기록하고, ResponseEntity 객체를 생성하여 상태 코드와 에러 메시지를 반환하고 있다.

• 에러 발생 로직 과정

  public SurveyDocument getSurveyDocument(Long surveyDocumentId) {
  	return surveyDocumentRepository.findById(surveyDocumentId)
    			.orElseThrow(() -> new NotFoundException("No SurveyDocument found with ID: " + surveyDocumentId));
  }

  • 위의 로직을 보면 DB에서 지정한 id 의 surveyDocument를 찾지 못하면 커스텀한 NotFoundException 에 메시지를 담아서 발생시킨다.
  • 그러면 @RestControllerAdvice 의 @ExceptionHandler 에서 정의된 로직을 실행한다.

결론

@RestControllerAdvice 를 사용하면 try-catch 문을 사용하지 않아도 되므로 비즈니스 로직의 가독성이 향상되며, 전역적으로 예외 처리를 할 수 있어 편리하다. 또한, 비즈니스 로직과 예외 처리 로직을 분리할 수 있어 유지 보수성도 더욱 좋다.

이와 같은 방식으로 @RestControllerAdvice 를 활용하면 예외 처리를 효율적으로 관리할 수 있다.