API에서의 예외 처리

애플리케이션에서 컨트롤러에서 예외가 발생했을 때 HTML 페이지의 경우에는 4xx, 400, 5xx .. 와 같은 오류페이지 설정을 통해 스프링 부트의 화이트라벨 페이지나 톰캣의 오류화면을 커스텀해서 클라이언트에게 보여줄 수 있었습니다.

 

하지만 API의 경우에는 각 오류 상황에 맞는 오류 응답 스펙을 정하고 , JSON으로 데이터를 내려주어야 하기 때문에 예외처리에 생각할 부분이 많습니다.

 

우선 API도 오류 페이지에서 했던 것처럼 서블릿 오류 페이지 방식을 먼저 사용해보겠습니다.

@Slf4j
@RestController
public class ApiExceptionController {

    @Data
    @AllArgsConstructor
    static class MemberDto
    {
        private String memberId;
        private String name;
    }

    @GetMapping("/api/members/{id}")
    public MemberDto getMember(@PathVariable("id") String id)
    {
        if(id.equals("ex"))
        {
            throw new RuntimeException("잘못된 사용자");
        }
        return new MemberDto(id,"hello "+id);
    }

예외발생 시 컨테이너에 등록된 WebServerCustomizer의 RuntimeException과 매핑된 에러페이지를 보여줍니다.

API를 요청했을 때

• 정상요청  : JSON 잘 반환됨
• 오류요청 : 미리 만들어둔 오류 페이지 HTML이 반환

 

클라이언트가 정상 요청이던, 오류 요청이던 JSON이 반환되길 기대할 때 어떻게 해야할까요?

 

API 응답을 추가해서 오류 요청일 때 오류 정보 JSON으로 반환

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

    log.info("errorPage 500 API");

    Map<String, Object> result = new HashMap<>();
    Exception ex = (Exception) request.getAttribute(ERROR_EXCEPTION);

    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));
}

• 매핑 정보에 produces 옵션을 JSON으로 지정하면 Request의 Accept헤더가 application/json일 경우에 해당 메소드가 호출됩니다.
  • Jackson 라이브러리는 ResponseEntity를 사용해서 응답하기 때문에 메시지 컨버터가 동작하면서 클라이언트 JSON이 반환.
  • ResponseEntity에 오류 상태코드, 메시지를 json 으로 반환했습니다. 

Postman 결과

 

스프링 부트가 제공하는 기본 오류 방식 사용 - BasicErrorController

Customizing 한 오류 페이지를 사용하지 않을 때는, 스프링 부트는 BasicErrorController를 기본으로 사용합니다.

BasicErrorController 사용했을 때

BasicErrorController를 사용 시

 

Accept헤더가 application/json 이면 json에 오류정보를 담아 리턴하고,

text/html이면 디폴트로 매핑된 /error 경로에 있는 뷰를 찾아 에러코드와 매칭되는 뷰를 찾아 렌더링합니다.

+ application.properties에 추가적으로 오류 정보를 추가할 수 있지만
server.error.include-binding-errors=always
server.error.include-exception=true
server.error.include-message=always
server.error.include-stacktrace=always

보안 상 위험하기 때문에 오류에 대해서는 간결한 메시지만 노출하고 로그를 통해서 확인하도록 합시다.

 

뒤에서 다룰 @ExceptionHandler가 제공하는 기능을 사용하는 것이 더 나은 방법이기 때문에 지금은 이 정도까지만 알아보겠습니다.

HandlerExceptionResolver

동작 순서

 

• 컨트롤러에 예외가 발생해서 WAS까지 예외가 전파되었을 때 HTTP 상태코드는 500 (서버 오류)로 처리되는데 예외에 따라 400, 404 등등 다른 상태코드로 처리하고 싶을 때
• 오류 메시지나 형식을 API마다 다르게 처리하고 싶을 때

HandlerExceptionResolver를 적용할 수 있습니다.

 

1. HandlerExceptionResolver를 상속받아 ExceptionReseolver 생성

@Slf4j
public class MyHandlerExceptionResolver implements HandlerExceptionResolver {
    @Override
    public ModelAndView resolveException(HttpServletRequest request, HttpServletResponse response,
                                         Object handler, Exception ex) {
        try
        {
            if(ex instanceof IllegalStateException)
            {
                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;
    }
}

 

2. WebConfig에 등록

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

이렇게 ExceptionResolver를 사용해서 예외를 처리하거나 예외정보를 바꾸어 클라이언트에게 넘길 수 있습니다.

• 빈 ModelAndView() 리턴 시 뷰를 렌더링 하지않고 정상 흐름으로 서블릿으로 리턴.
• null 리턴 : 다음 ExceptionResolver가 있을 경우 처리하지 못한 예외를 넘겨서 실행. 다음 ExceptionResolver가 없으면  예외를 서블릿 밖으로 던집니다.

ExceptionResolver를 잘 활용하면 이런 사안들을 처리할 수 있습니다. 

1. 예외 상태 코드 변환 (response.sendError(...) )
2. 뷰 템플릿 처리 ( 모델뷰에 값을 채워서 ) : WAS
3. API 응답처리 (response.getWriter().println("hello"); 처럼 HTTP 응답 바디에 직접 데이터를 넣어주는 것도 가능. 여기서 JSON으로 응답하면 API 응답처리를 할 수 있습니다.)  

추가로 컨트롤러에서 예외가 발생해도 ExceptionResolver를 사용하면 예외가 WAS까지 전파되지 않고 서블릿 선에서 해결되기 때문에 상당히 깔끔해진다는 메리트가 있습니다.

 

하지만 이렇게 인터페이스를 내려받아 구현하고 로직짜고 등록하는 과정 자체가 좀 귀찮은 일입니다.

 

스프링 부트가 제공하는 ExceptionResolver

1. DefaultHandlerExceptionResolver

• 스프링 내부에서 발생하는 스프링 예외를 해결
• 대표적으로 파라미터 바인딩 시점에 타입이 맞지 않으면 내부에서 TypeMistmatchException이 발생하는데, 이 경우 서블릿 컨테이너까지 오류가 올라가고, 결과적으로 500오류가 발생합니다.
• 하지만 사실 클라이언트가 입력값을 타입에 맞지 않게 입력했기 때문에 400 에러를 클라이언트에게 리턴 해주어야하는데 이런 역할을 기본적으로 수행 해주는 Resolver가 DefaultHandlerExceptionResolver

@GetMapping("/api/default-handler-ex")
public String defaultException(@RequestParam Integer data)
{
    return "ok";
}

로그를 보면 DefaultHandlerExceptionResolver가 실행된 것을 확인할 수 있습니다.

 

2. ResponseStatusExceptionHandler

• ResponseStatusExceptionHandler는 예외에 따라서 HTTP 상태코드를 지정해주는 역할을 합니다.
• @ResponseStatus가 달려있는 예외와 ResponseStatusException 예외 두 가지 경우를 처리합니다.

예외에 @ResponseStatus 어노테이션을 적용하면 HTTP 상태 코드를 변경할 수 있습니다.

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

• BadRequestException은 RuntimeException(500 서버 에러)를 상속받은 에러.
• 원래 같으면 마찬가지로 상속받았기 때문에 상태코드가 500대 여야 하지만 @ResponseStatus에서 상태코드를 원하는 대로 지정하면 ResponseStatusExceptionResolver가 해당 어노테이션을 확인하고 오류코드를 지정한 코드로 변경하고 reason을 통해 메시지을 담습니다.

예외에 @ResponseStatus를 달아 HTTP 상태코드 지정하기

@GetMapping("/api/response-status-ex1")
public String responseStatusEx1()
{
    throw new BadRequestException();
}

localhost:8080/api/response-status-ex1 호출

reason은 MessageSource에서 찾는 기능도 제공하기 때문에 messages.properties로 처리할 수도 있습니다.

ResponseStatusException 예외 던지기

@GetMapping("/api/response-status-ex2")
public String responseStatusEx2()
{
    throw new ResponseStatusException(HttpStatus.NOT_FOUND,"잘못된 요청 오류", new IllegalArgumentException());
}

ResponseStatusException에 직접 설정하고자 하는 상태코드와 지정한 오류를 매칭시켜 던지는 방법

 

 

3. ExceptionHandlerExceptionResolver - @ExceptionHandler

웹 브라우저에 HTML 화면오류를 제공할 때에는 스프링 부트는 기본적으로 BasicErrorController를 호출해 /error 경로에 만들어둔 뷰템플릿을 렌더링 한다고 했었습니다. 

 

하지만 API 오류의 경우에는 얘기가 좀 다릅니다. 각 API는 시스템마다 응답의 모양도, 스펙도 모두 다르죠. 따라서 예외 상황에 단순히 웹브라우저에 오류화면 HTML 을 보여주는 게 아니라 예외에 따라서 각각 다른 데이터를 출력해야 할 수도 있습니다.

또 같은 예외라고 해도 예외가 발생한 컨트롤러별로 다른 응답을 내려주어야 할 수도 있어요.( 예를 들면 상품 관리 컨트롤러와 회원 관리 컨트롤러에서의 RuntimeException 예외에 대해 서로 다른 방식으로처리하고 싶은 경우).

 

예외처리에 대한 세밀한 제어가 필요한 시점에 사용할 수 있는 해결책이 바로 ExceptionHandlerExceptionResolver가 제공하는 @ExceptionHandler 입니다!

 

@ExceptionHandler 장점

• 다른 예외처리 도구보다 우선순위가 높습니다.
• 구현이 간단합니다!
• 스프링의 컨트롤러처럼 다양한 파라미터와 응답 타입을 지정할 수 있습니다.

@ExceptionHandler에서 파라미터와 응답타입 

https://docs.spring.io/spring-framework/docs/current/reference/html/web.html#mvc-ann-exceptionhandler-args

Web on Servlet Stack

@ExceptionHandler // UserException.class 생략 가능
public ResponseEntity<ErrorResult> userExHandler(UserException e)
{
    log.error("[exceptionHandler] ex", e);
    ErrorResult result = new ErrorResult("USER-EX",e.getMessage());
    return new ResponseEntity(result,HttpStatus.BAD_REQUEST);
}

@GetMapping("/api2/members/{id}")
public ApiExceptionController.MemberDto getMember(@PathVariable("id") String id)
{

    if(id.equals("user-ex"))
    {
        throw new UserException("사용자 오류");
    }

사용법은 간단합니다.

• @ExceptionHandler 어노테이션을 선언하고 해당 컨트롤러에서 처리하고 싶은 예외를 지정.
• 이때 파라미터에 입력한 예외와 @ExceptionHandler에 지정한 예외가 같으면 @ExceptionHandler에 예외 클래스 이름 지정 생략 가능.
  @ExceptionHandler({AException.class, BException.class}) 다양한 예외를 한번에 처리도 가능합니다.
• 상위 예외 클래스를 @ExceptionHandler로 지정하면 하위 예외 클래스를 아우를 수 있습니다.

@ExceptionHandler(상위예외.class)
public ~ 부모예외처리(상위 예외 e) 
{}

@ExceptionHandler(하위예외.class)
public ~ 하위예외처리(하위 예외 e)
{}

- 스프링의 우선순위는 항상 자세한 것이 우선권을 가지기 때문에 하위 예외 처리가 호출됩니다.
- 이 우선순위를 잘 활용해 처리하지 못한 모든 예외들을 모든 예외의 부모 예외인 Exception을 @ExceptionHandler로 처리해서 남은 예외들을 처리할 수 있습니다.

 

+ @ControllerAdvice

@Slf4j
@RestControllerAdvice(annotations = RestController.class)
public class ExControllerAdvice {

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

    @ExceptionHandler // UserException.class 생략 가능
    public ResponseEntity<ErrorResult> userExHandler(UserException e)
    {
        log.error("[exceptionHandler] ex", e);
        ErrorResult result = new ErrorResult("USER-EX",e.getMessage());
        return new ResponseEntity(result,HttpStatus.BAD_REQUEST);
    }

    // 처리하지 못하고 남은 예외들 처리
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler
    public ErrorResult exHandler(Exception e)
    {
        log.error("[exceptionHandler] ex", e);
        return new ErrorResult("EX","내부 오류");
    }
}

 

@ControllerAdvice

• 대상으로 지정한 여러 컨트롤러에 @ExceptionHandler를 적용할 수 있습니다.
• 대상으로 지정하지 않으면 모든 컨트롤러에 적용
• @RestControllerAdvice = @ResponseBody + @ControllerAdvice

<참고자료>

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