Spring 예외처리 - API, @ExceptionHandler

2021.08.30 - [Backend/Spring MVC] - Spring 예외처리 - 오류페이지(404,500)

Spring 예외처리 - 오류페이지(404,500)

 

고객에게 보여줄 HTML 오류페이지는 스프링부트의 BasicErrorController를 사용하면 쉽게 구현 가능했다. 그렇다면 JSON등의 API에 오류가 발생했다면 어떻게 처리할까?

 

 

# API의 예외처리

궁금하니까 일단 예외를 던지면 스프링에서 어떻게 동작하는지 알아보자.

api 반환값에 HTML 오류페이지가 반환된다...어? 이래도 되나?

@Slf4j
@RestController
public class ApiExceptionController {

  @GetMapping("/api/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);
  }
}

 

---

@ 오류페이지 대신 오류 API로 전환하기

API 데이터를 요청했는데 HTML을 보내버리면 안된다. 다행히도 스프링 @RequestMapping 어노테이션에는 HTP 헤더를 분석해 JSON API 요청이 왔을 때 다른 결과를 반환하도록 만들 수 있다. 

 ➡ @RequestMapping(value = "/error-page/500", produces = MediaType.APPLICATION_JSON_VALUE)

// ErrorController 를 직접 구현한 경우

@RequestMapping(value = "/error-page/500", produces = MediaType.APPLICATION_JSON_VALUE)
  public ResponseEntity<Map<String, Object>> errorPage500Api(
      HttpServletRequest request, HttpServletResponse response) {

    log.info("API errorPage 500");

    
    // RequestDispatcher.ERROR_EXCEPTION, ERROR_STATUS_CODE 상수
    Exception ex = (Exception) request.getAttribute(ERROR_EXCEPTION);
    
    Map<String, Object> result = new HashMap<>();
    result.put("status", request.getAttribute(ERROR_STATUS_CODE));
    result.put("message", ex.getMessage());

    Integer statusCode = (Integer) request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
    return new ResponseEntity<>(result, HttpStatus.valueOf(statusCode));
  }
}

 

그러면 HTML 오류 페이지와 같은 메커니즘으로 WAS는 컨트롤러 다시 호출한다.

 

 

---

# 스프링 부트의 BasicErrorController

앞에서 에러용 컨트롤러를 따로 만들지않아도, 웹 페이지에서는 BasicErrorController를 이용해 개발자는 error/404.html만 작성하면 간단하게 오류 페이지를 제공 할 수있었다. API는 어떻게 처리할 수 있을까?

스프링부트에서 생성하는 BasicErrorContorller 객체

 

• 사실 BasicErrorController는 HTTP 요청 Header에 있는 Accept를 보고 오류페이지를 선택해준다.
  ➡ Accept = text/html 라면 404.html을, Accept = application/json 이라면 Json 에러를 반환한다.

Accept 헤더값에 따라 다르게 동작하도록 이미 정의되어있다.

앞에서 했던 것처럼, 예외 메시지를 반환하지 않게 설정할 수도 있다.

 

• 이는 BasicErrorController 코드를 보면 쉽게 이해할 수 있다.
  ➡ text/html이라면 ModelAndView를 반환하지만, 그 외의 요청에 대해서는 ResponeEntity<>를 반환한다.

BasicErrorController에 적혀있는 코드

 

 

@ BasicController 만으로는 API 오류 처리에 한계가 있다.

HTML 요청의 오류페이지는 단순하게 404, 500 코드에 따라 다른 오류페이지를 반환해주면 되었다.

 

하지만 API는 정말 다양한 형태가 나온다. 클라이언트, 서버마다 API 스펙이 다를수도있고, 같다고 하더라도 [Item API, Order API]등 요청마다 다른 오류 JSON 메시지를 전송해야 한다. 이를 어떻게 처리할 수 있을까?

 

---

# API 예외처리 - HandlerExceptionResolver

스프링 MVC는 컨트롤러 밖으로 예외가 발생한 경우, 이 예외를 처리할 수 있는 HandlerExceptionResolver 인터페이스를 제공해준다. 만약 예외처리를 WAS로 던지지 않고 중간에 처리하고 싶다면 이를 구현하면 된다.

 ➡  ExceptionResolver를 사용하면 굳이 WAS를 거쳐서 돌아올 필요가 없다. 그냥 예외를 try-catch처럼 잡으면 된다.

참고로 ExceptionResolver를 사용해도 예외가 터지면 인터셉터의 postHandle(...)가 동작하지 않는건 변함없다.

 

• 예외가 발생한 경우 중간에 낚아채서 지정한 반환값이 나오도록 만들 수 있다.
  ➡ ExceptionResolver는 여러개 등록할 수 있다. 즉 null을 반환하면 다음 리졸버로 넘긴다.

@Slf4j
public class MyHandlerExceptionResolver implements HandlerExceptionResolver {
  @Override
  public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response,
      Object handler, Exception ex) {

    try {
      if (ex instanceof IllegalArgumentException) {
        // API의 경우 이렇게 응답데이터를 보낼 수 있음.
        // 직접 메시지를 입력하고싶다면 => response.getWriter().println("hello"); 
        response.sendError(HttpServletResponse.SC_BAD_REQUEST, ex.getMessage());
        
        // View가 필요없는 경우, 그냥 비어있는 ModelAndView를 반환하면 뷰가 렌더링 되지않음.
        return new ModelAndView();
      }
    } catch (IOException e) {
       // response.writer 에서 발생할 수 있는 예외처리
    }

    return null; // 단 해당 예외(Exception ex)를 처리할 리졸버가 없다면 WAS로 넘김.
  }
}

 

이렇게 만든 핸들러는 필터, 인터셉터처럼 @Configuration에서 등록하면 된다.

@Configuration
public class WebConfig implements WebMvcConfigurer {

  @Override
  public void extendHandlerExceptionResolvers(List<HandlerExceptionResolver> resolvers) {
    // configureHandler...메서드는 기존의 스프링 예외핸들러를 삭제해버린다. 이 메서드를 사용하자.
    resolvers.add(new MyHandlerExceptionResolver());
    resolvers.add(new UserHandlerExceptionResolver());
  }


  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new LogInterceptor())
        .order(1)
        .addPathPatterns("/**")
        .excludePathPatterns("/css/**", "*.ico", "/error/**", "/error-page/**");
  }
}

 

 

---

# HandlerExceptionResolver 활용방법

• 예외상황에 따라 다르게 처리해야하므로 서비스에서 사용할 Exception을 정의한다.

public class UserException extends RuntimeException {
  /* RuntimeException의 생성자만 오버라이딩 해주면 된다. 코드는 생략 */
}

 

• 해당 예외를 처리할 ExceptionResolver를 만들고, @Configuration 객체에 리졸버를 추가한다.

@Configuration
public class WebConfig implements WebMvcConfigurer {

  @Override
  public void extendHandlerExceptionResolvers(List<HandlerExceptionResolver> resolvers) {
    resolvers.add(new UserHandlerExceptionResolver());
  }
}

@Slf4j
public class UserHandlerExceptionResolver implements HandlerExceptionResolver {

  private final ObjectMapper objectMapper = new ObjectMapper();

  @Override
  public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response,
      Object handler, Exception ex) {

    try {
      // 내가 만든 예외가 발생한 경우
      if (ex instanceof UserException) {
        response.setStatus(HttpServletResponse.SC_BAD_REQUEST); // 400 에러로 지정
        String acceptHeader = request.getHeader("accept");

        if ("application/json".equals(acceptHeader)) { // JSON 응답인 경우
          Map<String, Object> errorResult = new HashMap<>();
          errorResult.put("ex", ex.getClass());
          errorResult.put("message", ex.getMessage());

          // 객체를 문자열(JSON)으로 변경함.
          String result = objectMapper.writeValueAsString(errorResult);
          
          // response body 를 작성함.
          response.setContentType("application/json");
          response.setCharacterEncoding("utf-8");
          response.getWriter().write(result);
          return new ModelAndView();

        } else { // 그냥 HTML 응답을 요구한 경우
          return new ModelAndView("error/500");
        }
      }

    } catch (IOException e) {
      // response.writer 에서 발생할 수 있는 예외처리
    }

    return null; // 그 외 에러는 다음 리졸버(없다면 WAS)에 넘김.
  }
}

 

예외처리를 할 수 있는건 좋지만 매번 리졸버를 만들어 사용하기에는 번거롭다. 더 편하게 사용하는 방법은 없을까?

 

 

---

# 스프링부트의 ExceptionResolver

역시나 스프링 부트에서는 사용하기 편하게 아래의 ExceptionResolver를 미리 만들어두고 자동으로 등록해준다.

아래 3개의 기본 리졸버가 순서대로 동작한다. 현재 리졸버에서 null을 반환하는 경우 다음 리졸버가 실행된다.

• 1. ExceptionHandlerExceptionResolver
  ➡ 스프링의 @ExceptionHandler를 처리하는 리졸버이다. 스프링 API 예외는 대부분 이걸 사용한다.
• 2. ResponseStatusExceptionResolver
  ➡ @ResponseStatus(HttpStatus.NOT_FOUND) 같은 걸 읽어 예외에 따라 HTTP 상태코드를 변경하는 리졸버이다.
  ➡ 참고로 reason에 스프링의 메시지("error.bad")를 이용할 수도 있다. 등록된게 없다면 그냥 문자열로 처리한다.

@ResponseStatus 태그를 이용해서 해당 예외가 발생했을 때 반환할 HTTP 상태코드와 메시지를 지정해줄 수 있다.

• 3. DefaultHandlerExceptionResolver ( 우선순위가 가장 낮은 리졸버 )
  ➡ 그 외 스프링 내부에 발생할 수 있는 예외들을 처리하는 기본 리졸버이다.
  ➡ 예) 요청 메시지 자료형이 이상해서(TypeMismatchException) 처리가 불가능한 경우 HTTP 400을 반환한다. 
  

- @ResponseStatus(...)의 경우 코드를 직접 수정해야 사용가능하다는 단점이 있다. 

- 참고로 @ResponseStatus(...)를 사용하면, 기존 예외를 ResponseStatusException으로 감싸서 리졸버가 처리하도록 만든다. 즉 어노테이션을 사용하지 않고 직접 throw Resp...Exception을 던져도 해당 리졸버가 예외를 처리해준다.

 

 

---

# API 처리와 @ExceptionHandler

한번 더 복습하자면, HTML 화면 오류는 그냥 BasicErrorController를 이용해서 404 페이지를 보여주면 해결된다.

하지만 API의 경우에는 다르다. Item-API, Order-API등 서비스 종류에 따라 오류 메시지를 다르게 처리해줘야하고 심지어는 클라이언트에 따라 API의 스펙 자체가 달라지기도 한다. 물론 필요하다면 HTML 화면도 리졸버로 처리해도 된다.

 

➡ 그래서 API의 예외처리는 보통 어노테이션을 이용한 ExceptionHandlerExceptionResolver를 이용한다.
➡ 물론 리졸버는 순서대로 실행되기 때문에, 다른 ExceptionResolver를 함께 사용할 수 있다.

@ExceptionHandler 어노테이션 사용

ExceptionResolver는 예외가 발생하면, 컨트롤러 안에 @ExceptionHandler 를 사용하는 메서드가 있는지 확인한다.

그리고 예외를 해당 메서드가 처리하도록 만들어주고 HTTP 요청에 정상 응답(200)한다.

➡ 만약 HTTP 오류코드를 400을 반환하고 싶다면 예외처리 메서드에 @ResponseStatus를 추가로 사용하면 된다.

@Slf4j
@RestController
public class ApiExceptionV2Controller {
  
  // 예외가 발생하는 Mapping 메서드
  @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);
  }
  
  
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  @ExceptionHandler(IllegalArgumentException.class)
  public ErrorResult illegalExHandle(IllegalArgumentException e) {
    return new ErrorResult("BAD", e.getMessage());
  }


  @ExceptionHandler
  public ResponseEntity<ErrorResult> userExHandle(UserException e) {
    ErrorResult errorResult = new ErrorResult("USER-EX", e.getMessage());
    return new ResponseEntity<>(errorResult, HttpStatus.BAD_REQUEST);
  }
}

 

---

@ExceptionHandler의 추상화

놀랍게도 스프링의 @ExceptionHandler는 SpringMVC 컨트롤러처럼 추상화되어있다. 그래서 아래의 예시들처럼 파라메타, 리턴타입을 다양하게 가질 수 있다. 아마 예상했겠지만, DispatcherServlet에서 @ExceptionHandler 또한 리졸버들을 이용해 추상화한다.

 

• 위의 예제처럼 파라메타의 타입이 예외 타입과 같다면 @ExceptionHandler( 예외.class ) 를 생략해도 된다.

  @ExceptionHandler // @ExceptionHandler(UserException.class)와 같은 동작 
  public ResponseEntity<ErrorResult> userExHandle(UserException e) {
    ErrorResult errorResult = new ErrorResult("USER-EX", e.getMessage());
    return new ResponseEntity<>(errorResult, HttpStatus.BAD_REQUEST);
  }

 

• ExceptionResolver는 해당 예외의 자식 객체까지 처리한다. 즉 아래와 같은 default 예외처리를 만들 수 있다.
  ➡ 다만 @ExceptionHandler가 [부모, 자식] 예외가 다 있다면 더 디테일한 객체, 즉 자식 예외부터 먼저 매핑한다.

  // 메서드 선언 순서는 상관없다. 더 자세한(자식) 예외부터 메서드가 매핑된다.
  // 모든 Exception을 받는 예외처리. 실수로 놓치는 예외 발생을 방지해준다.
  @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
  @ExceptionHandler
  public ErrorResult exHandle(Exception e) {
    log.error("[exceptionHandle] ex", e);
    return new ErrorResult("EX", "내부 오류");
  }

 

• 물론 여러 개의 예외를 하나의 메서드에 지정할 수도 있다.

@ExceptionHandler( {AException.class, BException.class} )
public String ex(Exception e) {
  log.info("exception e", e);
}

 

• 위에도 언급했지만, 꼭 API에만 사용하라는 법은 없다. 아래와 같이 View를 반환해줘도 된다.
  ➡ 물론 @ResponseBody나 @RestController 태그가 있으면 뷰 리졸버가 실행되지않아 사용할 수 없다.

// 다만 API 컨트롤러에 @RestController를 붙이므로, 거의 사용하지 않는 방법이긴하다.
@ExceptionHandler(ViewException.class)
public ModelAndView ex(ViewException e) {
    log.info("exception e", e);
    return new ModelAndView("error"); // 뷰 리졸버 실행됨
}

 

---

# @ControllerAdvice를 이용한 API 예외처리

@ExceptionHandler는 너무나 편리한 기능이지만, 해당 컨트롤러 객체에만 적용된다는 단점이 있다.

즉 컨트롤러마다 @ExceptionHandler를 하나하나 작성해줘야하는데, 이를 모든 컨트롤러 공통으로 묶을 순 없을까?

 

➡ Spring AOP에서 제공해주는 @ControllerAdvice, @RestControllerAdvice 를 이용하면 된다.

* 참고로 @RestControllerAdvice는 그냥 기존태그에 @ResponseBody가 추가로 붙어있는 태그이다. 즉 return을 했을 때 뷰리졸버가 동작하지 않는다.

 

 

📑 ErrorResult  📑 ExControllerAdvice ➡  @ExceptionHandler 부분의 코드를 분리해 따로 작성한다.

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

@Slf4j
@RestControllerAdvice(basePackages = "hello.exception.api")
public class ExControllerAdvice {

  @ResponseStatus(HttpStatus.BAD_REQUEST)
  @ExceptionHandler(IllegalArgumentException.class)
  public ErrorResult illegalExHandler(IllegalArgumentException e) {
    log.error("[exceptionHandler] ex", e);
    return new ErrorResult("BAD", e.getMessage());
  }

  @ExceptionHandler
  public ResponseEntity<ErrorResult> userExHandler(UserException e) {
    log.error("[exceptionHandler] 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 exHandler(Exception e) {
    log.error("[exceptionHandler] ex", e);
    return new ErrorResult("EX", "내부 오류");
  }

}

그냥 AOP보다 사용법이 더 간단하다. JoinPoint 같은 거 필요없이 @ControllerAdvice만 붙여주면 된다.

• (basePackages ="...")를 지정해주면 해당 패키지안에 있는 모든 @Controller에 적용된다.
• 따로 적지않는다면 프로젝트 경로에 있는 모든 컨트롤러에 적용된다. (Spring 공식문서)

 

이를 사용하면 이제 컨트롤러에서 예외코드를 작성하지 않아도 된다. 객체의 책임이 분리되었다. 

@Slf4j
@RestController
public class ApiExceptionV3Controller {

  @GetMapping("/api3/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);
  }
}


// 참고로 MemberDto는 이렇게 생겼다.
@Data
@AllArgsConstructor
class MemberDto {

  private String memberId;
  private String name;
}