[스프링 MVC] API 예외 처리

스프링 MVC 2편의 강의 내용을 정리한 포스팅입니다.

---

API 예외 처리

HTML 페이지의 경우 그에 맞는 오류 페이지만 있으면 대부분의 문제를 해결할 수 있지만, API의 경우 고려해야 할 점이 더 많다. 오류 페이지는 단순히 클라이언트에게 오류 화면을 보여주고 끝이지만, API는 각 오류 상황에 맞는 오류 응답 스펙을 정하고 JSON으로 데이터를 내보내야 한다.

 

@RequestMapping 애노테이션의 produces 옵션을 MediaType.APPLICATION_JSON_VALUE으로 설정하면, HTTP 헤더의 Accept 값이 application/json일 때만 해당 메서드를 호출하게 된다.

 

 

스프링 부트 기본 오류 처리

스프링 부트가 제공하는 기본 오류 방식(BasicErrorController)을 이용할 수도 있는데, 코드를 보면 아래와 같다.

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

@RequestMapping 
public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {}

두 메서드는 동일한 경로를 처리하는데, HTTP 헤더의 Accept 값이 text/html인 경우에만 errorHtml() 메서드를 적용하고 그 외의 경우에는 error() 메서드를 적용한다.

 

 

HandlerExceptionResolver

스프링 부트가 제공하는 BasicErrorController는 HTML 페이지를 제공하는 경우 편리하게 이용할 수 있지만, API 오류 처리는 API마다 혹은 각각의 컨트롤러나 예외마다 서로 다른 응답 결과를 출력해야 할 수도 있다. 따라서 API 오류는 BasicErrorController가 아닌 @ExceptionHandler를 이용하는 것이 더욱 편리하다.

 

요구사항

서블릿을 넘어 WAS까지 예외가 전달되면 HTTP 상태코드가 500으로 처리되지만 발생하는 예외에 따라서 400, 404 등 다른 상태코드로 처리하거나 오류 메시지, 형식 등을 API마다 다르게 처리하는 것

 

위의 요구사항을 충족시키기 위해서는 HandlerExceptionResolver, 줄여서 ExceptionResolver를 이용하면 된다.

ExceptionResolver를 적용하고 나서 예외가 발생하게 되면 아래와 같은 흐름을 가진다.

1. 핸들러(컨트롤러)에서 예외가 발생하면 디스패처 서블릿으로 예외 전달

2. ExceptionResolver에서 예외 처리를 시도

3. ExceptionResolver에서는 ModelAndView를 반환하는데, 반환 값에 따른 디스패처 서블릿의 동작 방식은 다음과 같다.

3-1 빈 ModelAndView - 뷰를 렌더링 하지 않고, 정상 흐름으로 서블릿이 리턴된다.

3-2 ModelAndView 지정 - 지정된 뷰를 렌더링 한다.

3-3 null - 다음 ExceptionResolver를 찾아서 실행하는데, 없을 경우 예외 처리가 이루어지지 못한 채 서블릿 밖으로 기존 예외를 던진다.

 

 

HandlerExceptionResolver - 활용

1. 예외 상태 코드 변환

- 예외를 sendError() 호출로 변경해서 서블릿에서 상태 코드에 따른 오류를 처리하도록 위임

2. 뷰 템플릿 처리

- ModelAndView에 값을 채워서 예외에 따른 새로운 오류 화면 뷰를 렌더링 해서 제공

3. API 응답 처리

- getWriter().println() 처럼 HTTP 응답 바디에 직접 데이터를 넣어줄 수도 있다. 여기에 JSON으로 응답하면 API 응답 처리를 할 수 있다.

 

ExceptionResolver를 사용하면 컨트롤러에서 예외가 발생해도 ExceptionResolver에서 예외를 처리하기 때문에 예외가 발생해도 서블릿 컨테이너까지 예외가 전달되지 않고, 스프링 MVC에서 예외 처리가 끝나게 된다. 결과적으로 WAS 입장에서는 정상적으로 처리가 된 것이다. 이렇게 예외를 모두 처리할 수 있다.

서블릿 컨테이너까지 예외가 올라가면 복잡하게 추가 단계가 실행되지만, 그에 비해 ExceptionResolver를 사용하면 깔끔하게 예외처리를 할 수 있다.

 

그런데 ExceptionResolver를 이용하기 위해서는 해당 인터페이스를 직접 구현해야 하기 때문에 다소 복잡한 면이 있다. 이러한 부분은 스프링이 제공하는 ExceptionResolver를 이용해 해결할 수 있다.

 

 

스프링이 제공하는 ExceptionResolver

스프링 부트가 기본으로 제공하는 ExceptionResolver는 다음과 같고, HandlerExceptionResolverComposite에 순서대로 등록된다.

1. ExceptionHandlerExceptionResolver - @ExceptionHandler를 처리하며, 대부분의 API 예외 처리는 대부분 이 기능으로 해결

2. ResponseStatusExceptionResolver - HTTP 상태코드 지정

3. DefaultHandlerExceptionResolver - 스프링 내부 기본 예외 처리

 

 

 

스프링이 제공하는 ExceptionResolver - ResponseStatusExceptionResolver, DefaultHandlerExceptionResolver

ResponseStatusExceptionResolver

ResponseStatusExceptionResolver는 예외에 따라서 HTTP 상태코드를 지정해 주는 역할을 하는데, 다음 두 가지 경우를 처리한다.

1. @ResponseStatus가 달려있는 예외

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

@ResponseStatus 애노테이션을 적용하면 HTTP 상태 코드를 변경해 준다. BadRequestException 예외가 컨트롤러 밖으로 넘어가면 ResponseStatusExceptionResolver 예외가 해당 애노테이션을 확인해서 오류 코드를 변경하고, 메시지도 담는다.

+) reason 옵션의 메시지는 MessageSource에서 찾을 수도 있다.

 

2. ResponseStatusException 예외

@ResponseStatus는 개발자가 직접 변경할 수 없는 예외에는 적용할 수 없고, 애노테이션을 사용하기 때문에 조건에 따라 동적으로 변경하는 것에도 어려움이 있다. 이러한 경우 ResponseStatusException 예외를 사용하면 된다.

@GetMapping("/api/response-status-ex") 
public String responseStatus() {     
    throw new ResponseStatusException(HttpStatus.NOT_FOUND, "error.bad", new IllegalArgumentException()); 
}

{     
  "status": 404,     
  "error": "Not Found",     
  "exception": "org.springframework.web.server.ResponseStatusException",     
  "message": "잘못된 요청 오류입니다. 메시지 사용",     
  "path": "/api/response-status-ex" 
}

 

DefaultHandlerExceptionResolver

DefaultHandlerExceptionResolver는 스프링 내부에서 발생하는 스프링 예외를 해결하는데, 대표적인 예시로 TypeMismatchException 상황이 있다.

파라미터 바인딩 시점에 타입이 맞지 않으면 예외가 발생하는데, 별도의 처리를 해주지 않으면 서블릿 컨테이너까지 오류가 올라가고 결과적으로 500 오류가 발생한다. 그런데 파라미터 바인딩은 대부분 클라이언트에게 문제가 있는 상황이기 때문에 DefaultHandlerExceptionResolver는 이를 500 오류가 아닌 400 오류로 변경해 준다.

 

 

@ExceptionHandler

API 오류 응답의 경우 앞선 방식을 이용하기에는 response에 직접 데이터를 넣어야 해서 번거롭기도 하고, ModelAndView를 반환해야 하는 것도 API에는 잘 맞지 않는다. 또한 동일한 에러에 대해 특정 컨트롤러에서만 발생하는 예외를 별도로 처리하기가 어려웠다. 스프링은 이 문제를 해결하기 위해 @ExceptionHandler라는 예외 처리 기능을 제공하는데, 이것이 바로 ExceptionHandlerExceptionResolver이다.

@Data 
@AllArgsConstructor 
public class ErrorResult { //예외가 발생했을 때 API 응답으로 사용할 객체
    private String code;     
    private String message; 
}

@RestController
public class ApiExceptionController {
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(IllegalArgumentException.class)
    public ErrorResult illegalExHandle(IllegalArgumentException e) { //IllegalArgumentException 및 자식 클래스까지 모두 처리(자식 예외가 지정되지 않은 경우)
        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);
    }

    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler
    public ErrorResult exHandle(Exception e) { //자식 클래스까지 모두 처리(자식 예외가 지정되지 않은 경우)
        return new ErrorResult("EX", "내부 오류");
    }

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

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

실행 흐름

컨트롤러를 호출하고 예외가 발생했을 때 ExceptionResolver가 작동되고, 가장 우선순위가 높은 ExceptionHandlerExceptionResolver가 실행된다.

ExceptionHandlerExceptionResolver는 해당 컨트롤러에 오류를 처리할 수 있는 @ExceptionHandler가 있는지 확인하고 있는 경우에 그에 해당하는 메서드를 실행하여 응답한다. 만약 @ExceptionHandler에 지정된 예외가 없을 경우 발생한 예외와 메서드의 파라미터 간 매칭을 통해 메서드를 실행한다.

 

 

@ControllerAdvice

@ExceptionHandler를 통해 예외를 깔끔하게 처리할 수 있지만 정상 코드와 예외 처리 코드가 하나의 컨트롤러에 섞여있는 상태이다.

 @ControllerAdvice 또는 @RestControllerAdvice를 사용하면 두 코드를 분리할 수 있다.

@RestControllerAdvice
public class ExControllerAdvice {
    @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);
    }

    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler
    public ErrorResult exHandle(Exception e) {
        return new ErrorResult("EX", "내부 오류");
    }
}

@RestControllerAdvice는 @ControllerAdvice에 @ResponseBody가 추가되어 있다는 점에서 차이가 있다.

@RestController
public class ApiExceptionController {
    @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 기능을 부여해 주는 역할을 한다. 만약 대상을 지정하지 않으면 그 범위가 모든 컨트롤러에 대해 적용되며, 지정할 때는 특정 애노테이션이 있는 컨트롤러를 지정하거나 특정 패키지를 직접 지정할 수도 있다. 

// 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 {}