[Spring Error] SpringBoot 예외 처리

최근 프로젝트 초기 구조를 잡는 일을 하면서 공통 응답과 에러 처리에 대해 고민하게 되었습니다.

지금까지는 이미 만들어진 서비스의 소스 코드를 수정하고 일부 신규 기능을 개발하는 업무를 주로 했기 때문에 기존에 사용하던 응답과 에러 처리 방식을 사용했고 해당 부분에 대해 고민하지 않았던 것 같습니다.

 

오늘은 프로젝트의 기본이 되는 예외 처리를 Spring Boot가 어떻게 처리하도록 지원하는지 정리해보겠습니다.

 

API 개발에서 최종적으로 저는 @ExceptionHandler 와 @RestControllerAdvice 를 사용할 예정이지만 그 전에 어떤 식으로 예외 처리가 될 수 있는지 차근차근 알아보겠습니다.

 

1. 스프링의 기본적인 예외 처리 방법

Spring은 만들어질 때(1.0)부터 에러 처리를 위한 BasicErrorController를 구현해두었고, 스프링 부트는 예외가 발생하면 기본적으로 /error로 에러 요청을 다시 전달하도록 WAS 설정을 해두었습니다. 그래서 별도의 설정이 없다면 예외 발생 시에 BasicErrorController로 에러 처리 요청이 전달됩니다. 참고로 이는 스프링 부트의 WebMvcAutoConfiguration를 통해 자동 설정이 되는 WAS의 설정입니다.

 

일반적인 요청 흐름은 다음과 같이 진행되는데

WAS(톰캣) -> 필터 -> 서블릿(디스패처 서블릿) -> 인터셉터 -> 컨트롤러

 

컨트롤러 하위에서 예외가 발생하였을 때, 별도의 예외 처리를 하지 않으면 WAS까지 에러가 전달됩니다.

그러면 WAS는 애플리케이션에서 처리를 못하는 예와라 exception이 올라왔다고 판단을 하고, 대응 작업을 진행한 뒤 스프링 부트가 등록한 에러 설정(/error)에 맞게 요청을 전달하는데, 이러한 흐름을 총 정리하면 다음과 같습니다.

WAS(톰캣) -> 필터 -> 서블릿(디스패처 서블릿) -> 인터셉터 -> 컨트롤러
-> 컨트롤러(예외발생) -> 인터셉터 -> 서블릿(디스패처 서블릿) -> 필터 -> WAS(톰캣)
-> WAS(톰캣) -> 필터 -> 서블릿(디스패처 서블릿) -> 인터셉터 -> 컨트롤러(BasicErrorController)

 

기본적인 에러 처리 방식은 결국 에러 컨트롤러를 한번 더 호출하는 것입니다.

그러므로 필터나 인터셉터가 다시 호출될 수 있는데, 이를 제어하기 위해서는 별도의 설정이 필요합니다. 서블릿은 dispatcherType로 요청의 종류를 구분하는데, 일반적인 요청은 REQUEST이며 에러 처리 요청은 ERROR입니다. 필터는 서블릿 기술이므로 필터 등록(FilterRegistrationBean) 시에 호출될 dispatcherType 타입을 설정할 수 있고, 별도의 설정이 없다면 REQUEST일 경우에만 필터가 호출됩니다. 하지만 인터셉터는 스프링 기술이므로 dispatcherType을 설정할 수 없어 URI 패턴으로 처리가 필요합니다.

 

스프링 부트에서는 WAS까지 직접 제어하게 되면서 이러한 WAS의 에러 설정까지 가능해졌습니다. 또한 이는 요청이 2번 생기는 것은 아니고, 1번의 요청이 전달되고 이후 내부 요청이 일어나는 것으로 클라이언트는 이러한 에러 처리 작업이 진행되었는지 알 수 없습니다.

 

[BasicErrorController]

BasicErrorController는 accept 헤더에 따라 에러 페이지를 반환하거나 에러 메세지을 반환합니다. 에러 경로는 기본적으로 /error로 정의되어 있으며 properties에서 server.error.path로 변경할 수 있습니다.

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {

    private final ErrorProperties errorProperties;
    ...

    @RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
    public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
        ...
    }

    @RequestMapping
    public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
        ...
        return new ResponseEntity<>(body, status);
    }
    
    ...
}

 

errorHtml()과 error()는 모두 getErrorAttributeOptions를 호출해 반환할 에러 속성을 얻는데, 기본적으로 DefaultErrorAttributes로부터 반환할 정보를 가져옵니다. DefaultErrorAttributes는 전체 항목들에서 설정에 맞게 불필요한 속성들을 제거합니다.

 

• timestamp: 에러가 발생한 시간
• status: 에러의 Http 상태
• error: 에러 코드
• path: 에러가 발생한 uri
• exception: 최상위 예외 클래스의 이름(설정 필요)
• message: 에러에 대한 내용(설정 필요)
• errors: BindingExecption에 의해 생긴 에러 목록(설정 필요)
• trace: 에러 스택 트레이스(설정 필요)

{
    "timestamp": "2021-12-31T03:35:44.675+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "path": "/product/5000"
}

 

위는 기본 설정으로 받는 에러 응답입니다.

추가적으로 다음과 같이 properties를 통해 에러 응답을 조정할 수 있습니다. 물론 운영 환경에서 구현이 노출되는 trace는 제공하지 않는 것이 좋습니다.

참고로 SpringBoot 2.3 이전에는 message를 기본적으로 제공하고 있었지만, SpringBoot 2.3부터는 클라이언트에게 너무 많은 정보가 노출되는 것을 방지하기 위해 기본적으로 제공하지 않게 되었습니다.

server.error.include-message: always
server.error.include-binding-errors: always
server.error.include-stacktrace: always
server.error.include-exception: false

 

하지만 설정을 변경했음에도 불구하고 status는 여전히 500이며, 유의미한 에러 응답을 전달하지 못합니다. (참고로 여기서 status가 500인 이유는 에러가 처리되지 않고 WAS가 에러를 전달받았기 때문입니다.) 또한 흔히 사용되는 API 에러 처리 응답으로는 보다 세밀한 제어가 요구되므로 별도의 에러 처리 전략을 통해 상황에 맞는 에러 응답을 제공할 필요가 있습니다.

{
    "timestamp": "2021-12-31T03:35:44.675+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "trace": "java.util.NoSuchElementException: No value present ...",
    "message": "No value present",
    "path": "/product/5000"
}

 

2. 스프링의 예외 처리 흐름

Java에서는 예외 처리를 위해 try-catch를 사용해야 하지만 try-catch를 모든 코드에 붙이는 것은 비효율적입니다. Spring은 에러 처리라는 공통 관심사(cross-cutting concerns)를 메인 로직으로부터 분리하는 다양한 예외 처리 방식을 고안하였고, 예외 처리 전략을 추상화한 HandlerExceptionResolver 인터페이스를 만들었습니다.

대부분의 HandlerExceptionResolver는 발생한 Exception을 catch하고 HTTP 상태나 응답 메세지 등을 설정합니다. 그래서 WAS 입장에서는 해당 요청이 정상적인 응답인 것으로 인식되며, 위에서 설명한 복잡한 WAS의 에러 전달이 진행되지 않습니다.

public interface HandlerExceptionResolver {
    ModelAndView resolveException(HttpServletRequest request, 
            HttpServletResponse response, Object handler, Exception ex);
}

 

위의 Object 타입인 handler는 예외가 발생한 컨트롤러 객체입니다. 예외가 던져지면 디스패처 서블릿까지 전달되는데, 적합한 예외 처리를 위해 HandlerExceptionResolver 구현체들을 빈으로 등록해서 관리합니다. 그리고 적용 가능한 구현체를 찾아 예외 처리를 하는데, 우선순위대로 아래의 4가지 구현체들이 빈으로 등록되어 있습니다.

 

• DefaultErrorAttributes: 에러 속성을 저장하며 직접 예외를 처리 x
• ExceptionHandlerExceptionResolver: 에러 응답을 위한 Controller나 ControllerAdvice에 있는 ExceptionHandler를 처리
• ResponseStatusExceptionResolver: Http 상태 코드를 지정하는 @ResponseStatus 또는 ResponseStatusException를 처리
• DefaultHandlerExceptionResolver:  스프링 내부의 기본 예외들을 처리

DefaultErrorAttributes는 직접 예외를 처리하지 않고 속성만 관리하므로 성격이 다르기 때문에 내부적으로 DefaultErrorAttributes를 제외하고 직접 예외를 처리하는 3가지 ExceptionResolver들을 HandlerExceptionResolverComposite로 모아서 관리합니다. 즉, 컴포지트 패턴을 적용해 실제 예외 처리기들을 따로 관리하는 것입니다.

 

예외가 발생하면 순차적으로 다음의 Resolver들이 처리가능한지 판별한 후에 예외가 처리됩니다.

 

1. ExceptionHandlerExceptionResolver가 동작
   - 예외가 발생한 컨트롤러 안에 적합한 @ExceptionHandler가 있는지 검사합니다.
   - 컨트롤러의 @ExceptionHandler에서 처리가능하다면 처리하고, 그렇지 않으면 ControllerAdvice로 넘어갑니다.
   - ControllerAdvice안에 적합한 @ExceptionHandler가 있는지 검사하고 없으면 다음 처리기로 넘어갑니다.
2. ResponseStatusExceptionResolver가 동작
   - @ResponseStatus가 있는지 또는 ResponseStatusException인지 검사합니다.
   - 맞으면 ServletResponse의 sendError()로 예외를 서블릿까지 전달하고, 서블릿이 BasicErrorController로 요청을 전달합니다.
3. DefaultHandlerExceptionResolver가 동작
   - Spring의 내부 예외인지 검사하여 맞으면 에러를 처리하고 아니면 넘어갑니다. 
   - 적합한 ExceptionResolver가 없으므로 예외가 서블릿까지 전달되고, 서블릿은 SpringBoot가 진행한 자동 설정에 맞게 BasicErrorController로 요청을 다시 전달합니다.

앞서 살펴보았듯 Spring은 BasicErrorController를 구현해두었습니다. ExceptionHandler나 ControllerAdvice처럼 직접 에러를 반환하는 경우에는 BasicErrorController를 거치지 않지만 @ResponseStatus, ResponseStatusException 등과 같이 직접 에러 응답을 반환하지 않는 경우에는 최종적으로 BasicErrorController를 거쳐 에러가 처리됩니다. 클라이언트 입장에서는 이를 모르지만 내부에서는 2번 컨트롤러로 요청이 전달되는 과정이 진행됩니다.

 

3. 스프링이 제공하는 다양한 예외 처리 방법

Spring이 제공하는 다양한 도구들을 사용하여 위에서 살펴본 ExceptionResolver에서 예외가 처리될 수 있게 하는 방법을 살펴보겠습니다.

 

ResponseStatusExceptionResolver에서 처리

[ @ResponseStatus ]

에러 HTTP 상태를 변경하도록 도와주는 어노테이션입니다. @ResponseStatus는 다음과 같은 경우들에 적용할 수 있습니다.

 

• Exception 클래스 자체
• 메소드에 @ExceptionHandler와 함께
• 클래스에 @RestControllerAdvice와 함께

 

예를 들어 우리가 만든 예외 클래스에 다음과 같이 @ResponseStatus로 응답 상태를 지정해줄 수 있습니다.

@ResponseStatus(value = HttpStatus.NOT_FOUND)
public class NoSuchElementFoundException extends RuntimeException {
  ...
}

 

그러면 ResponseStatusExceptionResolver가 지정해준 상태로 에러 응답이 내려가도록 처리됩니다.

{
    "timestamp": "2021-12-31T03:35:44.675+00:00",
    "status": 404,
    "error": "Not Found",
    "path": "/product/5000"
}

 

하지만 @ResponseStatus를 처리하는 ResponseStatusExceptionResolver는 WAS까지 예외를 전달시키며, 복잡한 WAS의 에러 요청 전달이 진행되고 응답에서 볼 수 있듯이 BasicErrorController에 의한 응답을 제공합니다.

이러한 @ResponseStatus는 다음과 같은 한계점들을 가지고 있습니다.

 

• 에러 응답의 내용(Payload)를 수정 x (DefaultErrorAttributes를 수정하면 가능)
• 예외 클래스와 강하게 결합되어 같은 예외는 같은 상태와 에러 메세지를 반환
• 별도의 응답 상태가 필요하다면 예외 클래스 추가 필요
• WAS까지 예외가 전달되고, WAS의 에러 요청 전달이 진행
• 외부에서 정의한 Exception 클래스에는 @ResponseStatus를 붙여줄 수 없음

물론 프로퍼티 설정이나 에러 응답 커스터마이징을 통해 일부 문제를 해결할 수 있고, 메세지 소스를 사용해 다국어 처리도 할 수 있습니다. 하지만 개발자가 원하는대로 에러를 처리하는 것은 어려운데, 이러한 문제를 해결하기 위해서는 다른 방법을 사용해야 합니다.

 

[ ResponseStatusException ]

외부 라이브러리에서 정의한 코드는 우리가 수정할 수 없으므로 @ResponseStatus를 붙여줄 수 없습니다. Spring5에는 @ResponseStatus의 프로그래밍적 대안으로써 손쉽게 에러를 반환할 수 있는 ResponseStatusException가 추가되었습니다. ResponseStatusException는 HttpStatus와 함께 선택적으로 reason과 cause를 추가할 수 있고, 언체크 예외을 상속받고 있어 명시적으로 에러를 처리해주지 않아도 됩니다. 이러한 ResponseStatusException은 다음과 같이 사용할 수 있습니다.

@GetMapping("/product/{id}")
public ResponseEntity<Product> getProduct(@PathVariable String id) {
    try {
        return ResponseEntity.ok(productService.getProduct(id));
    } catch (NoSuchElementFoundException e) {
        throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Item Not Found", new NoSuchElementFoundException());
    }
}

 

ResponseStatusException를 사용하면 다음과 같은 이점을 누릴 수 있습니다.

 

• 기본적인 예외 처리를 빠르게 적용할 수 있으므로 손쉽게 프로토타이핑 가능
• HttpStatus를 직접 설정하여 예외 클래스와의 결합도를 낮출 수 있음
• 불필요하게 많은 별도의 예외 클래스를 만들지 않아도 됨
• 프로그래밍 방식으로 예외를 직접 생성하므로 예외를 더욱 잘 제어할 수 있음

하지만 그럼에도 불구하고 ResponseStatusException는 다음과 같은 한계점들을 가지고 있습니다. 이러한 이유로 API 에러 처리를 위해서는 @ExceptionHandler를 사용하는 방식이 더 많이 사용됩니다.

 

• 직접 예외 처리를 프로그래밍하므로 일관된 예외 처리가 어려움
• 예외 처리 코드가 중복될 수 있음
• Spring 내부의 예외를 처리하는 것이 어려움
• 예외가 WAS까지 전달되고, WAS의 에러 요청 전달이 진행

 

ExceptionHandlerExceptionResolver에서 처리

[ @ExceptionHandler ]

매우 유연하게 에러를 처리할 수 있는 방법을 제공하는 기능입니다. @ExceptionHandler는 다음에 어노테이션을 추가함으로써 에러를 손쉽게 처리할 수 있습니다.

 

• 컨트롤러의 메소드
• @ControllerAdvice나 @RestControllerAdvice가 있는 클래스의 메소드

예를 들어 다음과 같이 컨트롤러의 메소드에 @ExceptionHandler를 추가함으로써 에러를 처리할 수 있습니다. @ExceptionHandler에 의해 발생한 예외는 ExceptionHandlerExceptionResolver에 의해 처리가 됩니다.

@RestController
@RequiredArgsConstructor
public class ProductController {

  private final ProductService productService;
  
  @GetMapping("/product/{id}")
  public Response getProduct(@PathVariable String id){
    return productService.getProduct(id);
  }

  @ExceptionHandler(NoSuchElementFoundException.class)
  public ResponseEntity<String> handleNoSuchElementFoundException(NoSuchElementFoundException exception) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(exception.getMessage());
  }
}

 

@ExceptionHandler는 Exception 클래스들을 속성으로 받아 처리할 예외를 지정할 수 있습니다. 만약 ExceptionHandler 어노테이션에 예외 클래스를 지정하지 않는다면, 파라미터에 설정된 에러 클래스를 처리하게 됩니다. 또한 @ResponseStatus와도 결합가능한데,  만약 ResponseEntity에서도 status를 지정하고 @ResponseStatus도 있다면 ResponseEntity가 우선순위를 갖습니다.

ExceptionHandler는 @ResponseStatus와 달리 에러 응답(payload)을 자유롭게 다룰 수 있다는 점에서 유연합니다. 예를 들어 응답을 다음과 같이 정의해서 내려준다면 좋을 것입니다.

 

• code: 어떠한 종류의 에러가 발생하는지에 대한 에러 코드
• message: 왜 에러가 발생했는지에 대한 설명
• erros: 어느 값이 잘못되어 @Valid에 의한 검증이 실패한 것인지를 위한 에러 목록

여기서 code로 E001, E002 등과 같이 내부적으로 정의한 값을 사용하는 것보다 BAD_REQUEST와 같은 Http 표준 상태와 같이 가독성 좋은 값을 사용하는 것이 클라이언트의 입장에서도 대응하기 좋고, 유지보수하는 입장에서도 좋습니다.

@RestController
@RequiredArgsConstructor
public class ProductController {

    ...

    @ExceptionHandler(NoSuchElementFoundException.class)
    public ResponseEntity<ErrorResponse> handleItemNotFoundException(NoSuchElementFoundException exception) {
        ...
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleMethodArgumentNotValid(MethodArgumentNotValidException ex) {
        ...
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleAllUncaughtException(Exception exception) {
        ...
    }
}

 

Spring은 예외가 발생하면 가장 구체적인 예외 핸들러를 먼저 찾고, 없으면 부모 예외의 핸들러를 찾습니다. 예를 들어 NullPointerException이 발생했다면, 위에서는 NullPointerException 처리기가 없으므로 Exception에 대한 처리기가 찾아집니다.

@ExceptionHandler를 사용 시에 주의할 점은 @ExceptionHandler에 등록된 예외 클래스와 파라미터로 받는 예와 클래스가 동일해야 한다는 것입니다. 만약 값이 다르다면 스프링은 컴파일 시점에 에러를 내지 않다가 런타임 시점에 에러를 발생시킵니다.

java.lang.IllegalStateException: No suitable resolver for argument [0] [type=...]
HandlerMethod details: ...

 

ExceptionHandler의 파라미터로 HttpServletRequest나 WebRequest 등을 얻을 수 있으며 반환 타입으로는 ResponseEntity, String, void 등 자유롭게 활용할 수 있습니다.

@ExceptionHandler는 컨트롤러에 구현하므로 특정 컨트롤러에서만 발생하는 예외만 처리됩니다. 하지만 컨트롤러에 에러 처리 코드가 섞이며, 에러 처리 코드가 중복될 가능성이 높습니다. 그래서 스프링은 전역적으로 예외를 처리할 수 있는 좋은 기술을 제공해줍니다.

 

[ @ControllerAdvice와 @RestControllerAdvice ]

Spring은 전역적으로 @ExceptionHandler를 적용할 수 있는 @ControllerAdvice와 @RestControllerAdvice 어노테이션을 각각 Spring3.2, Spring4.3부터 제공하고 있습니다. 두 개의 차이는 @Controller와 RestController와 같이 @ResponseBody가 붙어 있어 응답을 Json으로 내려준다는 점에서 다릅니다.

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

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

 

ControllerAdvice는 여러 컨트롤러에 대해 전역적으로 ExceptionHandler를 적용해줍니다. 위에서 보이듯 ControllerAdvice 어노테이션에는 @Component 어노테이션이 있어서 ControllerAdvice가 선언된 클래스는 스프링 빈으로 등록됩니다. 그러므로 우리는 다음과 같이 전역적으로 에러를 핸들링하는 클래스를 만들어 어노테이션을 붙여주면 에러 처리를 위임할 수 있습니다.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(NoSuchElementFoundException.class)
    protected ResponseEntity<?> handleNoSuchElementFoundException(NoSuchElementFoundException e) {
        final ErrorResponse errorResponse = ErrorResponse.builder()
                .code("Item Not Found")
                .message(e.getMessage()).build();

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(errorResponse);
    }
}

 

ControllerAdvice는 전역적으로 적용되는데, 만약 특정 클래스에만 제한적으로 적용하고 싶다면 @RestControllerAdvice의 basePackages 등을 설정함으로써 제한할 수 있습니다.

스프링 예외에는 대표적으로 잘못된 URI를 호출하여 발생하는 NoHandlerFoundException 등이 있습니다. Spring은 스프링 예외를 미리 처리해둔 ResponseEntityExceptionHandler를 추상 클래스로 제공하고 있습니다. ResponseEntityExceptionHandler에는 스프링 예외에 대한 ExceptionHandler가 모두 구현되어 있으므로 ControllerAdvice 클래스가 이를 상속받게 하면 됩니다.

만약 이 추상 클래스를 상속받지 않는다면 스프링 예외들은 DefaultHandlerExceptionResolver가 처리하게 되는데, 그러면 예외 처리기가 달라지므로 클라이언트가 일관되지 못한 에러 응답을 받으므로 ResponseEntityExceptionHandler를 상속시키는 것이 좋습니다. 또한 이는 기본적으로 에러 메세지를 반환하지 않으므로, 스프링 예외에 대한 에러 응답을 보내려면 아래 메소드를 오버라이딩 해야 합니다.

public abstract class ResponseEntityExceptionHandler {
    ...

    protected ResponseEntity<Object> handleExceptionInternal(
        Exception ex, @Nullable Object body, HttpHeaders headers, HttpStatus status, WebRequest request) {
            
        ...
    }
}

 

우리는 이러한 ControllerAdvice를 이용함으로써 다음과 같은 이점을 누릴 수 있습니다.

 

• 하나의 클래스로 모든 컨트롤러에 대해 전역적으로 예외 처리가 가능
• 직접 정의한 에러 응답을 일관성있게 클라이언트에게 내려줄 수 있음
• 별도의 try-catch문이 없어 코드의 가독성이 높아짐

이러한 이유로 API에 의한 예외 처리를 할 때에는 ControllerAdvice를 이용하면 됩니다. 하지만 ControllerAdvice를 사용할 때에는 항상 다음의 내용들을 주의해야 합니다. 여러 ControllerAdvice가 있을 때 @Order 어노테이션으로 순서를 지정하지 않는다면 Spring은 ControllerAdvice를 임의의 순서로 처리할 수 있으므로 일관된 예외 응답을 위해서는 이러한 점에 주의해야 합니다.

 

• 한 프로젝트당 하나의 ControllerAdvice만 관리하는 것이 좋습니다.
• 만약 여러 ControllerAdvice가 필요하다면 basePackages나 annotations 등을 지정해야 합니다.
• 직접 구현한 Exception 클래스들은 한 공간에서 관리합니다.

 

지금까지 스프링의 에러 처리 방식에 대해 살펴보았습니다. 다음 글에서는 @ExceptionHandler, @RestControllerAdvice와 함께 message properties 를 활용한 에러 메시지 전달에 대해 알아보도록 하겠습니다.

 

참고

• 스프링 MVC 2편 - 백엔드 웹 개발 활용 기술
• https://mangkyu.tistory.com/204