Spring Boot의 ControllerAdvice로 중앙집중식 예외 처리 구현하기

Spring Boot의 @ControllerAdvice로 중앙집중식 예외 처리 구현하기

Overview

Spring Boot에서 애플리케이션의 예외 처리를 효율적으로 관리하는 것은 매우 중요합니다. @ControllerAdvice를 사용하면 여러 컨트롤러에서 발생하는 예외를 중앙에서 처리할 수 있어 코드의 중복을 줄이고 유지보수를 쉽게 할 수 있습니다. 이번 글에서는 @ControllerAdvice의 작동 원리와 함께 실제 코드 예제를 통해 에러 처리 방법을 자세히 설명하겠습니다.

1. @ControllerAdvice란?

@ControllerAdvice는 스프링 MVC에서 제공하는 어노테이션으로, 모든 컨트롤러에 적용될 수 있는 전역적인 예외 처리기입니다. 이를 통해 특정 예외가 발생했을 때 공통된 방식으로 응답을 처리할 수 있습니다. 이는 특히 RESTful API를 개발할 때 유용합니다.

2. 기본적인 사용법

@ControllerAdvice를 사용하려면 먼저 해당 어노테이션을 클래스에 붙여줍니다. 그리고 이 클래스 안에서 @ExceptionHandler를 사용하여 특정 예외를 처리하는 메서드를 정의합니다.

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
public class GlobalExceptionHandler {

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<String> handleResourceNotFoundException(ResourceNotFoundException ex) {
return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
}

@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleGenericException(Exception ex) {
return new ResponseEntity<>("Internal Server Error", HttpStatus.INTERNAL_SERVER_ERROR);
}
}

위 코드에서 ResourceNotFoundException이라는 사용자 정의 예외가 발생할 경우, 해당 예외에 대한 처리 로직을 제공합니다. 또한, 모든 예외를 처리하는 일반적인 핸들러도 구현해놓았습니다.

3. 사용자 정의 예외 클래스 만들기

예외 처리의 첫 단계는 사용자 정의 예외 클래스를 만드는 것입니다. 다음과 같이 ResourceNotFoundException 클래스를 정의할 수 있습니다.

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

이 예외 클래스는 메시지를 매개변수로 받아 상위 클래스인 RuntimeException에 전달합니다. 이를 통해 필요한 에러 메시지를 사용자에게 제공할 수 있습니다.

4. 예외 발생시키기

이제 컨트롤러에서 이 예외를 발생시켜 보겠습니다. 예를 들어, 특정 리소스를 찾지 못할 경우 예외를 던질 수 있습니다.

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

@GetMapping("/resource/{id}")
public String getResource(@PathVariable String id) {
if ("1".equals(id)) {
return "Resource found!";
} else {
throw new ResourceNotFoundException("Resource not found with id: " + id);
}
}
}

위의 컨트롤러에서는 ID가 "1"인 경우에만 리소스를 반환하고, 다른 경우에는 ResourceNotFoundException을 발생시킵니다.

5. HTTP 응답 처리

에러가 발생할 경우 클라이언트에게 어떤 형태로 응답할지를 결정하는 것이 중요합니다. @ControllerAdvice를 통해 처리한 예외는 ResponseEntity를 사용하여 HTTP 응답을 커스터마이징할 수 있습니다.

위의 코드 예제에서, ResourceNotFoundException이 발생하면 클라이언트에게 404 상태 코드와 함께 에러 메시지를 반환하게 됩니다. 이를 통해 클라이언트는 문제의 원인을 명확히 알 수 있습니다.

6. 에러 처리 시 발생할 수 있는 오류

예외 처리 중에 발생할 수 있는 에러에는 여러 가지가 있습니다. 예를 들어, 잘못된 요청이 들어올 경우 클라이언트가 예상치 못한 오류 메시지를 받을 수 있습니다. 이를 방지하기 위해 @ExceptionHandler(Exception.class)를 추가하여 모든 예외를 포괄적으로 처리합니다.

7. 테스트하기

중앙 집중식 예외 처리를 구현한 후에는 이를 테스트하는 것이 중요합니다. 예를 들어, Postman을 사용하여 /resource/2와 같은 요청을 보내면 404 상태 코드와 함께 "Resource not found with id: 2"라는 메시지를 받을 수 있습니다. 이처럼 테스트를 통해 예외 처리 로직이 정상적으로 작동하는지 확인해야 합니다.

8. 참고 문서

• Spring Boot Documentation - Exception Handling
• Baeldung - @ControllerAdvice in Spring MVC

이와 같은 방식으로 Spring Boot의 @ControllerAdvice를 사용하여 중앙 집중식 예외 처리를 구현하면 코드의 가독성을 높이고, 유지 보수를 용이하게 할 수 있습니다.