API 예외 처리

API는 각 오류 상황에 맞는 오류 응답 스펙을 정하고, JSON으로 데이터를 내려주어야 한다.

 

스프링 부트가 제공하는 BasicErrorController는 HTML 페이지를 제공하는 경우에는 편리하지만, API 오류 처리는 각각의 컨트롤러나 예외마다 서로 다른 응답 결과를 출력해야 할 수도 있기 때문에 복잡하다. 

 

'IllegalArgumentException'이 일어나고 아무런 처리를 안해주면 500 에러가 발생하는데 이것을 400에러로 바꾸어 주려면 'ExceptionResolver'를 활용해야 한다.

HandlerExceptionResolver 활용

• 예외 상태 코드 반환
  • 예외를 response.sendError(xxx)로 변경해서 서블릿에서 상태 코드에 따른 오류를 처리하도록 함
  • 이후 WAS는 서블릿 오류 페이지를 찾아서 내부 호출, 예를 들어서 스프링 부트가 기본으로 설정한 /error가 호출됨.
• 뷰 템플릿 처리
  • ModelAndView에 값을 채워서 예외에 따른 새로운 오류 화면의 뷰를 렌더링해서 사용자에게 제공
• API 응답 처리
  • response.getWrite().println("hello")처럼 HTTP 응답 바디에 직접 데이터를 넣어주는 것도 가능하다.

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

}

 

return 값

• 빈 ModelandView : new ModelAndView()처럼 빈 ModelAndView를 반환하면 뷰를 렌더링하지 않고 정상 흐름으로 서블릿이 리턴
• ModelAndView 지정: ModelAndView에 View, Model 등의 정보를 지정해서 반환하면 뷰를 렌더링
• null: 다음 ExceptionResolver를 찾아서 실행. 처리할 수 있는 ExceptionHandler가 없으면 예외처리가 안되고, 기존에 발생한 예외를 서블릿 밖으로 던짐.

 

하지만 이렇게 하면 번거롭기 때문에 스프링이 제공하는 ExceptionResolver를 사용해야함.

---

스프링이 제공하는 ExceptionResolver

HandlerExceptionResolverComposite에 등록하는 순서

1. ExceptionHandlerResolverComposite
   1. @ExceptionHandler를 처리한다.
2. ResponseStatusExceptionResolver
   1. 예외에 따라서 HTTP 상태 코드를 지정해준다.
3. DefaultHandlerExceptionResolver
   1. 스프링 내부 기본 예외를 처리한다.

 

ResponseStatusExceptionResolver

@ResponseStatus가 달려있는 예외, ResponseStatusException 예외를 처리해준다.

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

이렇게 Exception을 정의하고,

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

이렇게 컨트롤러를 만들면 에러코드가 BAD_REQUEST로 나온다.

 

또, reason에 적는 에러메시지를 코드화할 수 있다. 

messages.properties에 정의하면 된다.

 

@ResponseStatus는 개발자가 직접 변경할 수 없는 예외에는 적용할 수 없다. 애노테이션을 직접 넣어야하는데 라이브러리에 있는 예외 코드 같은 곳에는 적용할 수 없기 때문이다. 이런 경우에는 ResponseStatusException를 사용하면 된다.

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

이렇게 이미 정의된 예외를 받아서 사용할 수 있다.

 

DefaultHandlerExceptionResolver

스프링 내부에서 발생하는 스프링 예외를 해결한다.

대표적으로 파라미터 타입이 맞지않으면 발생하는 'TypeMismatchException'이 발생한 경우다. 이 예외가 발생했을 때 그냥 두면 결과적으로 500 오류가 발생하는데 TypeMismatchException은 클라이언트가 발생시킨 오류이므로 500오류가 발생하면 안된다. 400 오류가 발생해야 한다. DefaultHandlerExceptionResolver는 500 오류가 아니라 400오류로 변경한다.

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

 

ExceptionHandlerResolverComposite - @ExceptionHandler

 

HTML 화면 오류 vs API 오류

HTML 화면을 제공할 때 오류는 BasicErrorController를 사용하면 단순히 5xx, 4xx에 대한 오류 화면만 제공하면 된다.

API는 각 시스템마다 응답의 모양도 다르고, 스펙도 달라서 예외 상황에서 단순히 오류 화면을 보여주는 것이 아니라, 예외에 따라서 각각 다른 데이터를 출력해야 할 수도 있다. 같은 예외라도 어떤 컨트롤러인지에 따라 다른 예외 응답을 내려주어야 할 수도 있다. 복잡한 제어가 필요하다.

 

@ExceptionHandler 애노테이션을 선언하고, 해당 컨트롤러에서 처리하고 싶은 예외를 지정해주면 된다. 해당 컨트롤러에서 예외가 발생하면 이 메소드가 호출된다. 지정한 예외와 그 자식 예외까지 모두 잡을 수 있다.

@Slf4j
@RestController
public class ApiExceptionV2Controller {
    @ResponseStatus(HttpStatus.BAD_REQUEST) //없으면 정상흐름이 200이 됨.
    @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", "내부 오류");
    }

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

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

이런 방식으로 다양한 예외도 한번에 처리 가능하다.

 

 

---

@ControllerAdvice

이전 코드에서 정상 코드와 예외 코드가 섞여있는 것을 따로따로 분리할 수 있다.

@ControllerAdvice는 대상으로 지정한 컨트롤러에 @ExceptionHandler, @InitBinder 기능을 부여해주는 역할을 한다. 대상을 지정해주지 않으면 모든 컨트롤러에 적용된다.

@RestControllerAdvice는 @ControllerAdvice에 @ResponseBody가 추가된 것이다. 

 

대상 컨트롤러 지정

 

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

 

이렇게 @ExceptionHandler와 @ControllerAdvice를 잘 조합하면 깔끔하게 예외를 해결할 수 있다.