Spring MVC 2편 - API 예외 처리 (@ControllerAdvice, ExceptionHandler)

본 게시글은 인프런 김영한 선생님 강의 스프링 MVC 2편을 완강하고 배운 것을 남기고자 적은 포스팅입니다.

강의 링크는 아래와 같습니다.

https://www.inflearn.com/course/%EC%8A%A4%ED%94%84%EB%A7%81-mvc-2/dashboard

스프링 MVC 2편 - 백엔드 웹 개발 활용 기술 - 인프런 | 강의

본격적으로 시작하겠습니다.

SSR(서버 사이드 렌더링, 템플릿 엔진)에서는 4xx, 5xx 같은 오류 페이지만 있으면 예외 처리를 할 수 있다.

그러나 API를 사용하는 경우에는 생각 할 내용이 훨씬 많다.

CSR의 경우 다양한 오류 응답 스펙을 정해야 하고, 서버 간 통신에서도 API를 사용하면 다양한 오류 응답 스펙을 정해 JSON으로 응답 데이터를 보내야 한다. 이제 본격적인 API 예외 처리에 대해 알아보자.

API 예외 처리 - 시작

먼저 저번 시간에 배운 방식으로 API 예외를 처리할 수 있다. 두 가지를 배웠다.

1. 첫 번째 방법은 WebServerCustomizer 클래스를 스프링 빈으로 등록한다. 
   여기서 중요한 점은 WebServerFactoryCustomizer<ConfigurabWebServerFactory>를 implements 하는 것이다. 이렇게 implements를 하면 customize 메소드를 오버라이드해 에러 페이지를 등록한다. 그러면 이제 에러 페이지를 등록할 때, 설정한 예외나 HTTP 상태코드가 발생하면 에러 페이지의 URL에 해당하는 컨트롤러로 다시 매핑되어 에러 페이지가 보여진다.
   RequestMapping(produces = "MediaType.APPLICATION_JSON_VALUE")를 추가해 사용하면 된다.
2. 두 번째 방법은 스프링 부트가 제공하는 기본 오류 방식을 사용하는 것이다. 스프링 부트가 제공하는 BasicErrorController를 사용한다. BasicController 클래스의 error 메서드가 ResponseEntity로 HTTO BODY에 JSON 데이터를 반환한다.
3. 자세한 코드와 해설은 강의를 보시면 좋을 것 같습니다. 모든 내용을 담을 수 없고 부가적인 내용이라 코드는 생략하겠습니다.

결론적으로 말하자면 API예외를 BasicErrorController과 서블릿 에러 처리 방식으로 해결할 수 있지만, API 예외는 컨트롤러나 예외마다 각각 다른 응답 JSON 데이터를 보내주어야 한다. 매우 세밀하고 복잡하므로 위 두 가지 방식으로 해결하는 것은 옳지 않다.
이제 복잡한 API는 오류를 어떻게 처리해야하는지 알아보겠다.

HandlerExceptionResolver 시작

스프링 MVC는 컨트롤러 밖으로 예외가 던져진 경우 예외를 해결하고, 동작을 새로 정의하고 싶다면 HandlerExceptionResolver를 사용해야 한다. 줄여서 ExceptionResolver라고 한다.

ExceptionResolver 적용 전과 후

참고로 ExceptionResolver로 예외를 해결해도 postHandle()은 호출되지 않는다.

HandlerExceptionResolver 인터페이스 코드는 아래와 같다.

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

• handler : 컨트롤러의 정보다.
• Exception ex : 컨트롤러에서 발생한 예외다.
• ExceptionResolver가 ModelAndView를 반환하는 이유는 마치 try,catch를 하듯이, Exception을 처리해서 정상 흐름처럼 변경하는 것이 목적이다.
• 반환 값(ModelAndView)에 따른 DispatcherServlet의 동작 방식은 다음과 같다.
  • 빈 ModelAndView : 뷰를 렌더링하지 않고, 정상 흐름으로 서블릿이 리턴된다.
  • ModelAndView 지정 : ModelAndView에 View, Model 등의 정보를 지정해서 반환하면 뷰를 렌더링
  • null : null을 반환하면, 다음 ExceptionResolver을 찾아서 실행한다. 만약 처리할 수 잇는 ExceptionResolver가 없으면 예외 처리가 안되고, 기존에 발생한 예외가 서블릿 밖으로 던져진다.

ExceptionResolver을 활용한 방법은 3가지가 있다.

• 예외 상태 코드 변환 : 예외를 response.sendError(xxx) 호출로 변경해서 서블릿에서 상태 코드에 따른 오류를 처리하도록 위임한다. 이후WAS는서블릿 오류 페이지를 찾아서 내부호출을 하고, (예시)스프링 부트가 기본으로 설정한 / error 가 호출된다.
• 뷰 템플릿으로 처리한다. 기존에 4xx, 5xx 방식이다.
• API 응답 처리 : HTTP 응답 바디에 직접 데이터를 넣어준다. 여기서 JSON 으로 응답하면 API 응답 처리를 할 수 있다.

이제 ExceptionResolver을 한 번 등록해보겠다. 아래와 같이 본인이 정의한 HandlerExceptionResolver가 있다.

@Slf4j
  public class MyHandlerExceptionResolver implements HandlerExceptionResolver {
@Override
      public ModelAndView resolveException(HttpServletRequest request,
  HttpServletResponse response, Object handler, Exception ex) {
          try {
              if (ex instanceof IllegalArgumentException) {
                  log.info("IllegalArgumentException resolver to 400");
                  response.sendError(HttpServletResponse.SC_BAD_REQUEST, ex.getMessage());
                  return new ModelAndView();
              }
          } catch (IOException e) {
              log.error("resolver ex", e);	
		}
          return null;
      }
}

 이제 이것을 등록해보자. 아래와 같이 진행하면 된다.

@Configuration
  public class WebConfig implements WebMvcConfigurer {
      //위 코드는 생략
    @Override
  public void extendHandlerExceptionResolvers(List<HandlerExceptionResolver>resolvers) {   
       	resolvers.add(new MyHandlerExceptionResolver());
  }
}

이러면 우리가 정의한 ExceptionResolvers가 등록되고 사용할 수 있다.
ExceptionResolver를 사용하면 컨트롤러에서 예외가 발생해도, ExceptionResolver에서 예외를 처리해버린다.
따라서 예외가 발생해도 서블릿 컨테이너에까지 예외가 전달되지 않고, 스프링 MVC에서 예외 처리는 끝난다.

결과적으로는 예외처리가 깔끔해졌지만, 직접 수많은 예외들을 정의해 ExceptionResolver을 구현하자니 복잡하고 번거로울 것 같다.

지금부터 스프링이 제공하는 ExceptionResolver에 대해 알아보자.

 

스프링이 제공하는 ExceptionResolver 

스프링 부트가 기본적으로 제공하는 ExceptionResolvers는 다음과 같으며,
HandlerExceptionResolverComposite에 다음 순서로 등록된다.
제일 중요한 ExceptionHandlerExceptionResolver는 마지막에 다루겠다.

1. ExceptionHandlerExceptionResolver (대부분 이걸로 다 처리한다고 한다.)
2. ResponseStatusExceptionResolver
3. DefaultHandlerExceptionResolver -> 우선 순위가 제일 낮다.

ResponseStatusException

ResponseStatusException는 예외에 따라 상태 코드를 지정해주는 역할을 하며, 다음 두 가지를 처리한다.

1. @ResponseStatus
2. ResponStatusException 예외

@ResponseStatus(code = HttpStatus.BAD_REQUEST, reason = "잘못된 요청 오류") 
public class BadRequestException extends RuntimeException {
}

BadRequestException 예외가 컨트롤러 밖으로 넘어가면,
ResponseStatusExceptionResolver 예외가 해당 애노테이션을 확인해서 오류 코드를 HttpStatus.BAD_REQUEST (400)으로 변경하고, 메시지도 담는다.
ResponseStatusExceptionResolver 코드를 확인해보면 결국 response.sendError(statusCode, resolvedReason) 를 호출하는 것을 확인할 수 있다. sendError(400) 를 호출했기 때문에 WAS에서 다시 오류 페이지( /error )를 내부 요청한다.

참고

reason 을 MessageSource 에서 찾는 기능도 제공한다. reason = "error.bad"

@ResponseStatus(code = HttpStatus.BAD_REQUEST, reason = "error.bad") 
public class BadRequestException extends RuntimeException {
}

/*
 *messages.properties
 *error.bad=잘못된 요청 오류입니다. 메시지 사용
 */

@ResponseStatus 는 개발자가 직접 변경할 수 없는 예외에는 적용할 수 없다.
(애노테이션을 직접 넣어야 하는데, 내가 코드를 수정할 수 없는 라이브러리의 예외 코드 같은 곳에는 적용할 수 없다.)
추가로 애노테이션을 사용하기 때문에 조건에 따라 동적으로 변경하는 것도 어렵다.
이때는 ResponseStatusException 예외를 사용하면 된다.

DefaultHandlerExceptionResolver

DefaultHandlerExceptionResolver 는 스프링 내부에서 발생하는 스프링 예외를 해결한다.
대표적으로 파라미터 바인딩 시점에 타입이 맞지 않으면 내부에서 TypeMismatchException 이 발생하는데, 이 경우 예외가 발생했기 때문에 그냥 두면 서블릿 컨테이너까지 오류가 올라가고, 결과적으로 500 오류가 발생한다.
그런데 파라미터 바인딩은 대부분 클라이언트가 HTTP 요청 정보를 잘못 호출해서 발생하는 문제이다. HTTP 에서는 이런 경우 HTTP 상태 코드 400을 사용하도록 되어 있다. DefaultHandlerExceptionResolver 는 이것을 500 오류가 아니라 HTTP 상태 코드 400 오류로변경한다. 스프링 내부 오류를 어떻게 처리할지 수 많은 내용이 정의되어 있다.

코드를 확인을 해보면 DefaultHandlerExceptionResolver.handleTypeMismatch 를 보면,

다음과 같은 코드를 확인할 수 있다.response.sendError(HttpServletResponse.SC_BAD_REQUEST) (400)

결국 response.sendError() 를 통해서 문제를 해결한다.  sendError(400) 를 호출했기 때문에 WAS에서 다시 오류 페이지( /error )를 내부 요청한다.

 

위와 같은 스프링이 제공하는 ExceptionResolver 2개를 학습했다.

그러나 결국에는 ExceptionHandlerExceptionResolver을 사용한다고 한다. 여기서부터가 정말 중요하다.

 

@ExceptionHandler과 @ControllerAdvice

결국 위에서는 BasicErrorController를 사용하거나 HandlerExceptionResolver를 직접 구현해서 API 예외를 다루어야 했는데, 이게 쉽지 않다. 몇 가지 문제인 부분이 있다.

• HandlerExceptionResolver를 떠올려 보면 ModelAndView 를 반환해야 했다. 이것은 API 응답에는 필요하지 않다.
• API 응답을 위해 HttpServletResponse에 직접 응답 데이터를 넣었는데, 이는 매우 불편하다.
• 특정 컨트롤러에서만 발생하는 예외를 처리하기 어렵다. 예를 들어서 회원을 처리하는 컨트롤러에서 발생하는 RunTimeException 예외와 상품을 관리하는 컨트롤러에서 발생하는 동일한 RunTimeException을 예외로 서로 다른 방식으로 처리하고 싶다면 어떻게 해야할까?

이를 위해 존재하는 것이 @ExceptionHandler이다. 바로 이것이 ExceptinHandlerExceptionResolver이다.
스프링의 ExceptionResolver에서 우선 순위가 제일 높으며, 실무에서 API 예외 처리는 대부분 이 기능을 사용한다고 한다.
중요하니까 예제를 통해 확인해보자.

에러를 전달할 DTO 코드다.

@Data
  @AllArgsConstructor
  public class ErrorResult {
      private String code;
      private String message;
  }

이제 Api의 Exception 테스트 할 Controller이다.

 @Slf4j
@RestController
public class ApiExceptionV2Controller {

    @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", "내부 오류");
    }
    
    
    @GetMapping("/api2/members/{id}")
    public MemberDto getMember(@PathVariable("id") String id) {
        if (id.equals("ex")) {
            throw new RuntimeException("잘못된 사용자"); }
        if (id.equals("bad")) {
            throw new IllegalArgumentException("잘못된 입력 값");
        }
        if (id.equals("user-ex")) {
	    throw new UserException("사용자 오류"); 
        }
           return new MemberDto(id, "hello " + id);
      }
      
      @Data
      @AllArgsConstructor
      static class MemberDto {
          private String memberId;
          private String name;
      }
}

이제 포스트맨을 사용해서, Get 메서드를 지정하고 /api/members/user-ex로 요청을 보내면 
userExHandler이 호출되고 응답 데이터가 JSON으로 리턴된다.

 

@Exception 애노테이션을 선언하고, 해당 컨트롤러에서 처리하고 싶은 예외를 지정하면 된다.
해당 컨트롤러에서 예외가 발생하면 이 메서드가 호출된다. 참고로 지정한 예외 또는 그 예외의 자식 클래스는 모두 잡을 수 있다.
스프링의 우선 순위는 항상 자세한 것이 우선권을 가지므로, 만약 자식 예외 터지고 아래 코드와 같이 예외 처리가 있다면, 자식 예외 처리가 호출된다. 당연히 부모 예외가 터지면 부모 예외 처리가 호출된다.

@ExceptionHandler(부모예외.class) public String 부모예외처리()(부모예외 e) {}
@ExceptionHandler(자식예외.class) public String 자식예외처리()(자식예외 e) {}

 

 참고로 다양한 예외도 한 번에 처리할 수 있다.

 

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

@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", "내부 오류"); 
      }
}

아래는 예외 처리 코드를 뺀 이전 Controller 코드다.

@Slf4j
@RestController
public class ApiExceptionV2Controller {

    
    @GetMapping("/api2/members/{id}")
    public MemberDto getMember(@PathVariable("id") String id) {
        if (id.equals("ex")) {
            throw new RuntimeException("잘못된 사용자"); }
        if (id.equals("bad")) {
            throw new IllegalArgumentException("잘못된 입력 값");
        }
        if (id.equals("user-ex")) {
	    throw new UserException("사용자 오류"); 
        }
           return new MemberDto(id, "hello " + id);
      }
      
      @Data
      @AllArgsConstructor
      static class MemberDto {
          private String memberId;
          private String name;
      }
}

• @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 {}

 

이렇게 API 예외 처리에 대해 알아봤고 중요한, @ExceptionHandler와 @ControllerAdvice에 대해 알아봤다.

 

이상으로 포스팅을 마치겠습니다. 감사합니다!