[MVC] 예외 처리 - API 예외 처리 (@ExceptionHandler, @ControllerAdvice)

 

이전까지의 예외 처리 포스팅에서는 API 방식이 아닌 기본적인 화면을 반환하는 방식의 예외 처리를 다루었다.

그러나 API 통신에서 예외가 발생할 경우, 화면을 반환하는 것은 아무런 쓸모가 없다.

따라서 API 통신에서 예외가 발생했을 경우에는 어떤 식으로 예외 메세지를 반환할 것인지를 정하고, 그에 맞게  json으로 예외 메세지를 반환해 주어야 한다.

 

 

---

 

스프링 부트가 제공하는 기본 예외 처리

스프링 부트는 BasicErrorController를 통해 기본적인 예외처리를 수행한다고 했었다.

API 예외 또한 이곳에서 기본적으로 처리해 주는데, 반환해주는 json은 다음과 같은 형식이다.

 

 

Accept 헤더가 application/json인 경우

{
    "timestamp": "2022-01-07T13:17:21/064+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "exception": "java.lang.RuntimeException",
    "path": "api/member/ex",
}

 

그러나 API 오류 처리는 위와 같은 기본적인 예외 메세지로는 부족하다. 각각의 컨트롤러나 요청마다 상세한 예외 메세지를 보여주어야 하는 경우가 많다.

이제 이와같은 API 예외 메세지를 커스텀하여 처리하는 방법에 대해서 알아보자.

 

 

---

 

HandlerExceptionResolver

예외가 발생해서 서블릿을 넘어 WAS까지 전달된다면, 이전에 알아봤던 것과 같이 HTTP 상태코드 500으로 처리된다.

발생하는 예외에 따라서 상태코드를 변경하고 싶은 경우가 있을 것이다.

 

스프링은 컨트롤러 밖으로 예외가 던져진 경우 해당 예외를 해결하고 동작을 새롭게 정의할 수 있는 방법을 제공한다.

이런 경우에 사용할 수 있는 것이 바로 HandlerExceptionResolver이다. 줄여서 ExceptionResolver라고 한다.

 

ExceptionResolver가 적용되기 전에는, 컨트롤러에서 예외가 발생하면, WAS까지 예외가 전달되어 500을 반환한다.

그러나 ExceptionResolver가 적용된다면, 컨트롤러에서 발생한 예외를 ExceptionResolver가 처리한 후, WAS에는 정상 응답으로 넘어가게 된다.

 

(참고로 ExceptionResolver로 예외를 처리한다고 하더라도 인터셉터의 postHandle은 작동하지 않으니 주의하자)

 

 

사용

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

위 예시에서는 IllegalArgumentException이 발생한다면, 이를 HTTP 상태코드 400으로 처리하는 예시이다.

 

 

 

빈 ModelAndView를 반환한 이유?

빈 ModelAndView를 반환하면 뷰를 렌더링 하지 않으면서 정상 흐름으로 서블릿이 리턴된다.

 

 

 

이제 이를 등록해보자.

WebMvcConfigurer를 통해 등록

@Configuration
public class WebConfig implements WebConfigurer{
	@Override
	public void extendHandlerExceptionResolvers(List<HandlerExceptionResolver> resolvers) {
		resolvers.add(new MyHandlerExceptionResolver());
	}
}

 

 

 

 

---

 

 

스프링이 제공하는 ExceptionResolver

우리는 위에서 ExceptionResolver를 직접 구현해보았다. 

스프링 부트는 예외처리를 좀 더 편하게 할 수 있도록 기본으로 몇가지 ExceptionResolver를 제공하는데 다음과 같다.

 

1. ExceptionHandlerExceptionResolver
2. ResponseStatusExceptionResolver
3. DefaultHandlerExceptionResolver -> 우선순위가 가장 낮다

 

 

 

ExceptionHandlerExeptionResolver

@ExceptionHandler를 처리한다. API 예외 처리는 대부분 이것으로 해결한다.

 

 

 

ResponseStatusExceptionResolver

HTTP 상태 코드를 지정해준다.

(예: @ResponseStatus(value = HttpStatus.NOT_FOUND))

 

 

 

DefaultHandlerExceptionResolver

스프링 내부 기본 예외를 처리한다.

 

 

 

---

 

 

ResponseStatusExceptionResolver

가장 쉬운 ResponseStatusExceptionResolver부터 알아보도록 하자.

ResponseStatusExceptionResolver는 다음 두 가지 경우의 예외를 처리한다.

• @ResponseStatus가 달려있는 예외
• ResponseStatusException 예외

 

//@ResponseStatus가 달려있는 예외
@ResponseStatus(code = HttpStatus.BAD_REQUEST, reason = "잘못된 요청 오류")
public class BadRequestException extends RuntimeException {}



//ResponseStatusException 예외
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "error.bad", new IllegalArgumentException());

 

 

 

---

 

DefaultHandlerExceptionResolver

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

예를 들어 파라미터 바인딩 시점에 타입이 맞지 않으면 내부에서 TypeMismatchException이 발생하는데, 이 경우에는 예외가 발생한 것이기 때문에 그냥 두면 서블릿 컨테이너까지 오류가 전달되고, 결과적으로 500오류가 발생한다.

그러나 파라미터 바인딩을 대부분 클라이언트의 실수이므로 DefaultHandlerExceptionResolver에서는 이것을 500오류가 아니라 HTTP 상태코드 400오류로 변경한다.

 

위는 하나의 예시였고, 위의 예시 말고도 여러 예외를 변환해주니, 궁금하다면 한번 확인해 보는 것도 좋을 것 같다.

 

 

 

---

 

@ExceptionHandler

스프링은 API예외 처리 문제를 해결하기 위해서 @ExceptionHandler라는 애노테이션을 사용하는 예외 처리 기능을 제공하며, 이를 처리하는 것이 바로 ExceptionHandlerExceptionResolver이다.

 

사용 예시를 보며 알아보자.

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

 

@Slf4j
@RestController
public class ApiExceptionV2Controller {

	@ResponseStatus(HttpStatus.BAD_REQUEST)
	@ExceptionHandler(IllegalArgumentException.class)
	public ErrorResult illegalExHandle(IllegalArgumentException e) {
		log.error("[exceptionHandle] ex", e);
		return new ErrorResult("BAD", e.getMessage());
	}
    
	@ExceptionHandler
	public ResponseEntity<ErrorResult> userExHandle(UserException e) {
		log.error("[exceptionHandle] 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 exHandle(Exception e) {
		log.error("[exceptionHandle] 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에는 해당 컨트롤러에서 처리하고 싶은 예외를 지정해주면 된다.

해당 컨트롤러에서 예외가 발생하면 이 메시드가 호출된다.

지정한 예외와, 그 하위 예외는 모두 잡을 수 있다.

그리고 부모 예외와 자식 예외를 모두 지정한다면, 당연히 자식 예외를 우선순위가 높게 처리한다.

 

 

 

아래와 같이 다양한 예외를 잡거나, 예외를 생략할 수도 있다.

(예외를 생략하면 메서드 파라미터의 예외가 지정된다.)

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

@ExceptionHandler
public ResponseEntity<ErrorResult> userExHandle(UserException e) {}

 

 

중요한 점은 @ExceptionHandler는 하나의 컨트롤러 내부에서 발생하는 예외만 처리한다는 것이다.

그럼 정상 코드와 예외 처리 코드를 분리하는 방법이 없을까?

그럴 때 사용하는 것이 바로 @ControllerAdvice 혹은 @RestControllerAdvice이다.

 

 

---

 

 

@ControllerAdvice

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

 

 

적용방법

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

 

 

 

 

 

📔 Reference

스프링 MVC 2편 - 백엔드 웹 개발 활용 기술 - 인프런 | 강의