🌱 Spring MVC (14) API 요청에 대한 예외처리 (@ExceptionHandler, @ControllerAdvice)

Github 소스코드

🔎 API 요청에 대한 예외 처리

API에 대한 예외는 HTML페이지에 대한 예외 처리와는 상당히 다르게 처리해주어야 합니다.

우리는 이전 포스트에서 MVC에서 에러 페이지를 처리하는 방법을 알아보았습니다. 예외 상황(에러코드)에 맞는 예외 페이지를 정책에 맞는 경로, 이름으로 지정해주는 것만으로 사용자에게 적합한 에러 페이지를 보여줄 수 있었죠.

API의 경우 에러에 대한 응답으로 HTML페이지를 보여줘선 안 됩니다.
일단 API요청은 View를 랜더링 받기 위한 목적이 아닙니다. 데이터를 조회하거나 가공처리된 데이터를 받기 위함이죠.
또한 API의 경우 엔드포인트 사용자가 조금 다른 성격을 갖는다고 생각합니다. 대부분 해당 API를 사용하는 클라이언트는 정확한 목적을 지니고 있습니다. 보통 웹 페이지를 사용하는 클라이언트도 목적을 지니고 있지만 보다 범용적이므로 조금 추상적일지라도 이해 가능한 범위의 에러 페이지를 보여주면 되는 것 입니다.

하지만 API는 해당 API의 스펙에 맞는 보다 정밀한 예외 처리를 필요로 합니다. 응답 방식도 당연히 HTML페이지가 아닌 JSON형식이 되어야 합니다.

이제 간단한 예외 상황을 가정하고 JSON형태로 API스펙에 맞는 예외를 발생시키는 예제를 해보겠습니다.

---

🔎 @ExceptionHandler를 이용한 API 예외 처리

클라이언트로부터 입력받은 memberId를 이용해 여러 에러를 발생시키는 메서드입니다.

@Slf4j
@RestController
public class ApiExceptionController {

    @GetMapping("/api/members/{memberId}")
    public String getMember(@PathVariable String memberId) {
        if (memberId.equals("bad"))
            throw new IllegalArgumentException("잘못된 입력입니다.");
            
        if (memberId.equals("user-ex"))
            throw new UserException("사용자 오류입니다.");
            
        if (memberId.equals("runtime"))
            throw new RuntimeException("잘못된 사용자입니다.");
            
        return "ok";
    }
}

가장 먼저 memberId가 "bad"로 요청되었을 때 발생하는 IllegalArgumentException에 대한 예외처리를 해주겠습니다.

• @ExceptionHandler로 IllegalArgumentException에 대한 예외를 핸들링 메서드라는 것을 알려줍니다.

이렇게 @ExceptionHandler로 설정해주면 컨트롤러 내에서 해당 예외 발생시 아래 메서드가 실행되게 됩니다.

예외 발생시 해당 클래스 내부에서만 모든 동작이 일어나는 것은 아닙니다.
일단 예외가 발생하면 일단 DispatcherServlet까지는 예외를 던집니다.
이때 @ExceptionHandler가 붙어있다면 ExceptionHandlerExceptionResolver에 의해 아래 메서드를 호출할 수 있게 되는 것 입니다.

마치 컨트롤러처럼 동작하기 때문에 리턴되는 타입은 얼마든지 변경할 수 있습니다.

추가로 파라미터로 전달되는 예외객체가와 @ExceptionHandler의 파라미터와 같다면 @ExceptionHandler의 파라미터는 생략 가능합니다.

@ResponseStatus(HttpStatus.BAD_REQUEST) 
@ExceptionHandler(IllegalArgumentException.class)
public ErrorResult illegalArgumentExceptionHandler(IllegalArgumentException e) {
    log.info("[ExceptionHandler: IllegalArgumentException", e);
    return new ErrorResult("BAD", e.getMessage());
}

[ ErrorResult ]
@Data
@AllArgsConstructor
public class ErrorResult {

    private String code;
    private String message;
}

두 번째 예외처리 방법 입니다. UserException이 발생했을 때입니다.
이번에는 @ExceptionHandler의 파라미터를 생략한 것을 확인할 수 있습니다.

또한 이번에는 ResponseEntity를 응답값으로 사용하였습니다.

@ExceptionHandler
public ResponseEntity<ErrorResult> userExceptionHandler(UserException e) {
    log.info("[ExceptionHandler: UserExceptionHandler", e);
    ErrorResult errorResult = new ErrorResult("USER-EXCEPTION", e.getMessage());
    return new ResponseEntity<ErrorResult>(errorResult, HttpStatus.BAD_REQUEST);
}

마지막으로 그외 Exception에 대한 에러 핸들링 메서드입니다.
위 두 개 예외를 비롯해 모든 예외는 Exception의 자식입니다.
이제는 뭔가 스프링의 대원칙이 되는 것 같습니다 ..
구체적인 것부터 덜 구체적인 것 순으로.
(구체적인 것->자식클래스, 덜 구체적인 것 -> 부모 클래스)

자식클래스로 정의된 예외는 해당 메서드에서 처리되고 그외 모든 예외는 Exception을 처리하는 아래 메서드로 처리됩니다.
예외코드는 500 서버 내부 에러로 설정하였습니다.
(HttpStatus.INTERNAL_SERVER_ERROR)

@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
@ExceptionHandler
public ErrorResult exceptionHandler(Exception e) {
    log.info("[ExceptionHandler: Exception", e);
    ErrorResult errorResult = new ErrorResult("EX", e.getMessage());
    return errorResult;
}

컨트롤러 전체 코드입니다.

@Slf4j
@RestController
public class ApiExceptionController {

    /**
     * 이 컨트롤러에서 IllegalArgumentException 발생시 바로 이 메서드가 실행되는 것은 아님
     * 일단 예외는 DispatcherServlet까지 전파되고 DispatcherServlet에서 적합한 ExceptionResolver를 찾음
     * @ExceptionHandler가 붙어있는 경우 ExceptionHandlerExceptionResolver를 사용
     * ExceptionHandlerExceptionResolver를가 어노테이션을 분석하여 알맞는 메서드를 실행시켜 주는 것.
     */
    @ResponseStatus(HttpStatus.BAD_REQUEST) // 따로 설정해주지 않으면 아래 메서드로 예외를 잡아 처리하여도 200 OK로 됨 (정상흐름이기 때문)
    @ExceptionHandler(IllegalArgumentException.class)
    public ErrorResult illegalArgumentExceptionHandler(IllegalArgumentException e) {
        log.info("[ExceptionHandler: IllegalArgumentException", e);
        return new ErrorResult("BAD", e.getMessage());
    }

    /**
     * 리턴값으로 ResponseEntity를 사용
     */
    @ExceptionHandler
    public ResponseEntity<ErrorResult> userExceptionHandler(UserException e) {
        log.info("[ExceptionHandler: UserExceptionHandler", e);
        ErrorResult errorResult = new ErrorResult("USER-EXCEPTION", e.getMessage());
        return new ResponseEntity<ErrorResult>(errorResult, HttpStatus.BAD_REQUEST);
    }

    /**
     * Exception을 상속하는 자식 예외 클래스 (디테일한 예외 클래스)가 없다면 Exception클래스를 핸들링하는 아래 메서드가 호출
     * @ExceptionHandler로 처리하지 않은 RunTImeException을 발생시키면 아래 메서드가 실행될 것임.
     */
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler
    public ErrorResult exceptionHandler(Exception e) {
        log.info("[ExceptionHandler: Exception", e);
        ErrorResult errorResult = new ErrorResult("EX", e.getMessage());
        return errorResult;
    }

    @GetMapping("/api/members/{memberId}")
    public String getMember(@PathVariable String memberId) {
        if (memberId.equals("bad"))
            throw new IllegalArgumentException("잘못된 입력입니다.");
        if (memberId.equals("user-ex"))
            throw new UserException("사용자 오류입니다.");
        if (memberId.equals("runtime"))
            throw new RuntimeException("잘못된 사용자입니다.");
        return "ok";
    }
}

각 예외 발생 요청에 대한 Postman 테스트 결과입니다.

---

🔎 @ControllerAdvice를 이용한 예외처리 코드 분리

예외처리를 위한 코드가 생각보다 길고 정상적인 코드와 함께 있는 것이 별로 보기 좋지 않습니다.. 분리해보겠습니다.

이전 컨트롤러에서 예외처리 코드만 딱 복사해서 새로운 클래스를 하나 생성합니다.

@RestControllerAdvice는 @ControllerAdvice에 @ResponseBody가 붙은 어노테이션입니다.
@RestController와 Controller와 동일한 관계네요.

이렇게 @ControllerAdvice만을 사용하면 정의한 예외 핸들링 메서드가 글로벌하게 적용됩니다. 모든 컨트롤러에 적용되는 것 입니다.

적용범위는 어노테이션 단위, 패키지 단위, 상속관계 단위 등 여러가지로 설정 가능합니다.

[ 어노테이션 단위 ]
@ControllerAdvice(annotations = RestController.class)
public class ExceptionControllerAdvice1 {}

[ 패키지 단위 ]
@ControllerAdvice("com.package.dhk22")
public class ExceptionControllerAdvice2 {}

[ 상속관계 단위 ]
@ControllerAdvice(
      assignableTypes = {ClassInterface.class,
      AbstractController.class})
public class ExceptionControllerAdvice3 {}

ControllerAdvice 전체 코드

@Slf4j
@RestControllerAdvice
public class ExceptionControllerAdvice {

    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(IllegalArgumentException.class)
    public ErrorResult illegalArgumentExceptionHandler(IllegalArgumentException e) {
        log.info("[ExceptionHandler: IllegalArgumentException", e);
        return new ErrorResult("BAD", e.getMessage());
    }

    @ExceptionHandler
    public ResponseEntity<ErrorResult> userExceptionHandler(UserException e) {
        log.info("[ExceptionHandler: UserExceptionHandler", e);
        ErrorResult errorResult = new ErrorResult("USER-EXCEPTION", e.getMessage());
        return new ResponseEntity<ErrorResult>(errorResult, HttpStatus.BAD_REQUEST);
    }

    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler
    public ErrorResult exceptionHandler(Exception e) {
        log.info("[ExceptionHandler: Exception", e);
        ErrorResult errorResult = new ErrorResult("EX", e.getMessage());
        return errorResult;
    }

}

인프런 김영한님의 스프링 MVC 2편 을 수강하고 정리한 내용입니다.