Spring Boot 공통 Global Exception Handler

 

🎈 Spring에서 전역적으로 Exception을 처리하는 방법을 포스팅한다.

 

예외를 처리하는 방법은 다양하게 있다.

1. 메서드 내 예외 상황을 예측하여 try-catch문 사용
2. 요구사항에 대한 예외 처리 (validation)
3. Intercepter에서 선 예외 처리
4. HandlerExceptionResolver
5. ExceptionHandlerExceptionResolver
6. DefaultHandlerExceptionResolver
7. ResponseStatusExceptionResolver

 

위와 같은 방법들 말고도 다양한 예외 처리 방법이 존재한다.
하지만 각각의 에러에 일일이 처리하다보면,
비즈니스 로직에 집중을 할 수 없고, 코드가 복잡해지는 상황이 발생한다.

궁극적으로, 공통적으로 발생하는 에러가 있다면 공통적으로 처리해주는게 효율적인 방안이다.

 

그 방법으로, @Controller와 @ControllerAdvice, @ExceptionHandler를
이용한 컨트롤러단에서 전역적으로 예외를 처리하는 방법을 소개한다.

---

📌 @ExceptionHandler

• 해당 어노테이션은 @Controller, @RestController가 적용된 Bean내에서 발생하는 예외를 잡아서 하나의 메서드에서 처리해주는 기능을 한다.
• 아래의 예시처럼 해당 메서드에 어노테이션과 Exception Class를 선언해주면 해당 Exception이 발생했을때 원하는 로직을 처리할 수 있다.
• TestController에 해당하는 Bean에서 NullPointerException이 발생한다면, @ExceptionHandler(NullPointerException.class)가 적용된 메서드가 호출될 것이다.

@RestController
public class TestController {
    ...
    ...
    @ExceptionHandler(NullPointerException.class)
    public String nullpointers(Exception e) {
        System.err.println(e.getClass());
        return "error message";
    }
}

하지만, @ExceptionHandler를 등록한 Controller에만 적용된다. 다른 Controller에서 NullPointerException이 발생하더라도 예외를 처리할 수 없다는 단점이 있다.

---

📌 @ControllerAdvice

@ExceptionHandler가 하나의 클래스에 대한 것이라면, @ControllerAdvice는 모든 @Controller 즉, 전역에서 발생할 수 있는 예외를 잡아 처리해주는 annotation이다.

이 중에서도, @RestControllerAdvice와 @ControllerAdvice 2가지 유형이 있다.
@RestControllerAdvice는 @ResponseBody가 추가 되어 있다는 차이가 있다.
본 포스팅에서는 @ControllerAdvice를 쓰되, 필요한 부분에만 @ResponseBody를 붙여 준다.

 

이 글에서 보여주고자 하는것들은 대략 이렇다.

발생하는 에러들을 잡아서 HttpCode 500 같은 에러를 응답하지 않고 200을 응답하되,
선언한 에러 Code와 Message를 내려주고 화면에서 그에 맞춰서 대응을 할 수 있다.

공통적으로 발생하는 Error들에 대해 정의해둔 Error Code와 Message를 응답한다.

ServiceException을 정의해서 각 서비스에서 원하는 Error를 던져줄 수 있다.

---

🎈 실습 전에 필요한 Class들을 생성 해본다.

📌 ResultCode.class

public enum ResultCode {
    SUCCESS(200, ResultMessage.SUCCESS),
    UNAUTHORIZED(401, ResultMessage.UNAUTHORIZED),
    NO_AUTH(403, ResultMessage.NO_AUTH),
    INTERNAL_ERROR(500, ResultMessage.INTERNAL_ERROR),
    ACCESS_NO_AUTH(1_000, ResultMessage.ACCESS_NO_AUTH),
    ACCESS_TOKEN_EXPIRED(1_001, ResultMessage.ACCESS_TOKEN_EXPIRED),
    REFRESH_TOKEN_EXPIRED(1_002, ResultMessage.REFRESH_TOKEN_EXPIRED),
    VALID_NOT_PHONE_NUM(1_007, ResultMessage.VALID_NOT_PHONE_NUM),
    VALID_NOT_PASSWORD(1_008, ResultMessage.VALID_NOT_PASSWORD),
    MEMBER_NOT_EXIST(1_012, ResultMessage.MEMBER_NOT_EXIST),
    LOGIN_REQUIRED(1_019, ResultMessage.LOGIN_REQUIRED),
    PARAM_NOT_VALID(2_000, ResultMessage.PARAM_NOT_VALID),
    ;

    private final int resultCode;
    private final String resultMessage;

    ResultCode(int resultCode, String resultMessage) {
        this.resultCode = resultCode;
        this.resultMessage = resultMessage;
    }

    public int getResultCode() {
        return resultCode;
    }

    public String getResultMessage() {
        return resultMessage;
    }

    public interface ResultMessage {
        String SUCCESS = "완료 되었습니다.";
        String UNAUTHORIZED = "인증에 실패하였습니다.";
        String NO_AUTH = "접근 권한이 없습니다.";
        String ACCESS_NO_AUTH = "접근 권한이 없습니다.";
        String ACCESS_TOKEN_EXPIRED = "Access Token이 만료 되었습니다.";
        String REFRESH_TOKEN_EXPIRED = "Refresh Token이 만료 되었습니다.";
        String VALID_NOT_PHONE_NUM = "가입되지 않은 핸드폰 번호 입니다.";
        String VALID_NOT_PASSWORD = "잘못된 비밀번호 입니다.";   
        String MEMBER_NOT_EXIST = "존재하지 않는 사용자 입니다.";
        String LOGIN_REQUIRED = "로그인이 필요합니다.";
        String PARAM_NOT_VALID = "파라미터 오류입니다.";
        String INTERNAL_ERROR = "시스템 오류가 발생하였습니다. 다시 시도해주세요.";
    }
}

• Error Code와 Message를 정의한 Common Enum Class를 생성한다.
• 필요한 Code와 Message들을 추가 하여 사용하면 된다.

---

📌 BaseResDto.class

• Error Code와 Message를 담을 Dto Class를 생성한다.
• 이 Class는 Error가 발생시 Return할 Common Response Class이다.

@Getter @Setter
public class BaseResDto {
    private int resultCode = ResultCode.SUCCESS.getResultCode();
    private String resultMessage = ResultCode.SUCCESS.getResultMessage();
}

---

📌 ServiceException.class

@RequiredArgsConstructor
public class ServiceException extends Exception {

    private final int resultCode;
    private final String resultMessage;

    public ServiceException(@NonNull ResultCode resultCodeEnum) {
        this.resultCode = resultCodeEnum.getResultCode();
        this.resultMessage = resultCodeEnum.getResultMessage();
    }

    public ServiceException(@NonNull ResultCode resultCodeEnum, @NonNull Map<String, Object> params) {
        this.resultCode = resultCodeEnum.getResultCode();
        String messageTemplate = resultCodeEnum.getResultMessage();

        for (Map.Entry<String, Object> entry : params.entrySet()) {
            messageTemplate = messageTemplate.replaceAll(String.format("\\$\\{%s\\}", entry.getKey()), String.valueOf(entry.getValue()));
        }

        this.resultMessage = messageTemplate;
    }

    public int getResultCode() {
        return resultCode;
    }

    public String getResultMessage() {
        return resultMessage;
    }
}

• Exception을 상속 받은 공통 Exception Class이다.
• 원하는 서비스단 로직에서 이 Exception을 throw 해주면 된다.
• 두 번째 생성자는 ResultCode Enum Class에서 메세지를 ${field}와 같이 정의하여
  쓸 수 있다.
  Ex) ${field} 필드는 필수 값입니다.

---

📌 GlobalExceptionHandler.class

💡 Points

@ControllerAdvice, @RestController를 선언하고, ExceptionHandler를 정의한 Class

@ExceptionHandler: Catch할 Exception을 선언

ExceptionHandler에 선언한 Class를 Parameter로 받는다.

이 Handler Method들의 Return Class는 위에서 정의한 BaseResDto를 사용
-> Common Response Class를 사용하기 위함

 

💡 동작 순서
ControllerAdvice가 ExceptionHandler에 선언한 Exception 발생시 각 Method를 호출한다.
@ResponseStatus에 HttpStatus.OK를 선언해서 HTTP Code 200을 응답하게 하고,
BaseResDto에 전달 받은 ResultCode, ResultMessage를 Set해서 Return하는 형태이다. 이렇게 하면 화면에서는 500 Error 가 아니라 200 Code를 응답 받고, 각 ResultCode에 따라 ResultMessage를 출력해주는 등, 사용자 정의 처리를 할 수 있다.

 

@Slf4j
@ControllerAdvice
@RestController
public class GlobalExceptionHandler {
	private static final String field = "${field}";

	1️⃣
    @ExceptionHandler(com.package.common.exception.ServiceException.class)
	@ResponseStatus(HttpStatus.OK)
	public BaseResDto exception(com.package.common.exception.ServiceException e) {
		BaseResDto baseResDto = new BaseResDto();
		baseResDto.setResultCode(e.getResultCode());
		baseResDto.setResultMessage(e.getResultMessage());

		log.error("[{}]ServiceException: code[{}], message[{}]", ContextUtil.reqInfo.get().getUuid(), baseResDto.getResultCode(), baseResDto.getResultMessage());

		return baseResDto;
	}

	2️⃣
	@ExceptionHandler(BindException.class)
	@ResponseStatus(HttpStatus.OK)
	public BaseResDto exception(BindException e) {
		BaseResDto baseResDto = new BaseResDto();
		FieldError fieldError = e.getBindingResult().getFieldError();

		if (fieldError == null) {
			baseResDto.setResultCode(ResultCode.INTERNAL_ERROR.getResultCode());
			baseResDto.setResultMessage(ResultCode.INTERNAL_ERROR.getResultMessage());

			log.error("[{}]Internal Exception: {}", ContextUtil.reqInfo.get().getUuid(), ExceptionUtils.getStackTrace(e));

			return baseResDto;
		}

		String code = fieldError.getCode();

		if ("NotNull".equals(code) || "NotEmpty".equals(code) || "NotBlank".equals(code)) {
			baseResDto.setResultCode(ResultCode.VALID_NOT_NULL.getResultCode());
			baseResDto.setResultMessage(ResultCode.VALID_NOT_NULL.getResultMessage().replace(field, fieldError.getField()));
		} else if ("Pattern".equals(code)) {
			baseResDto.setResultCode(ResultCode.VALID_NOT_REGEXP.getResultCode());
			baseResDto.setResultMessage(ResultCode.VALID_NOT_REGEXP.getResultMessage().replace(field, fieldError.getField()));
		} else if ("MaxByte".equals(code)) {
			baseResDto.setResultCode(ResultCode.PARAM_NOT_VALID.getResultCode());
			baseResDto.setResultMessage(String.format("%s 값이 %dbyte 보다 큽니다.", fieldError.getRejectedValue(), fieldError.getArguments()[1]));
		} else {
			baseResDto.setResultCode(ResultCode.PARAM_NOT_VALID.getResultCode());
			baseResDto.setResultMessage(ResultCode.PARAM_NOT_VALID.getResultMessage());
		}

		log.error("[{}]ValidationException: message[{}]", ContextUtil.reqInfo.get().getUuid(), e.getMessage());

		return baseResDto;
	}

	3️⃣
	@ExceptionHandler(MissingServletRequestParameterException.class)
	@ResponseStatus(HttpStatus.OK)
	public BaseResDto exception(MissingServletRequestParameterException e) {
		BaseResDto baseResDto = new BaseResDto();
		baseResDto.setResultCode(ResultCode.VALID_NOT_NULL.getResultCode());
		baseResDto.setResultMessage(ResultCode.VALID_NOT_NULL.getResultMessage().replace(field, e.getParameterName()));

		log.error("[{}]ValidationException: message[{}]", ContextUtil.reqInfo.get().getUuid(), ExceptionUtils.getStackTrace(e));

		return baseResDto;
	}

	4️⃣
	@ExceptionHandler(Exception.class)
	@ResponseStatus(HttpStatus.OK)
	public BaseResDto exception(Exception e) {
		BaseResDto baseResDto = new BaseResDto();
		baseResDto.setResultCode(ResultCode.INTERNAL_ERROR.getResultCode());
		baseResDto.setResultMessage(ResultCode.INTERNAL_ERROR.getResultMessage());

		log.error("[{}]Internal Exception: {}", ContextUtil.reqInfo.get().getUuid(), ExceptionUtils.getStackTrace(e));

		return baseResDto;
	}
}

• 1️⃣: 위에서 생성한 ServiceException을 통해 전달 받은 ResultCode, ResultMessage를 BaseResDto에 set 해준 뒤 Return. (필요시 코드와 같이 log 출력)
• 2️⃣: BindException은 보통 Parameter에 잘못된 데이터를 전달 받거나, @NotNull @NotEmpty 같은 조건에 걸렸을때 발생한다. BindingResult 메서드를 통해 FieldError를 가져온 뒤 분기처리를 통해 원하는 ResultCode와 ResultMessage를 set 해준다.
• 3️⃣, 4️⃣도 동일한 형태이다. 이렇게 원하는 Exception에 응답하고 싶은 ResultCode와 Message를 Return 해주면 된다.

---

📌 예시

@Getter
public class UserResDto extends BaseResDto {
	private String userId;
    private String name;
    
    public UserResDto(User user) {
    	this.userId = user.getUserId();
        this.name = user.getName();
    }
}

 

@GetMapping("user-info/{userId}")
public BaseResDto getUserInfo(@PathVariable("userId") String userId) {
        return userService.getUserInfo(userId);
}

 

public BaseResDto getUserInfo(String userId) {
     User user = userRepository.findById(userId)
       .orElseThrow(() -> new ServiceException(ResultCode.USER_NOT_EXIST));
     
     return new UserResDto(user);
}

• BaseResDto를 상속 받은 User의 정보를 가지고 있는 Dto Class를 생성 한다.
• 해당 유저의 정보를 조회하는 API를 호출 했을 때, UserService의 getUserInfo함수를 호출한다. JPA로 User Entity를 조회하는 동시에 orElseThrow를 통해 해당 유저 데이터가 존재하지 않을때 ServiceException에 미리 정의 해놓은 ResultCode를 담아서 throw한다.
• 그러면 ControllerAdvice Annotation을 선언해놓은 GlobalExceptionHandler가
  @ExceptionHandler(ServiceException.class)가 선언 되어 있는 Method를 호출한다.
• 전달 받은 ResultCode.USER_NOT_EXIST의 ResultCode, ResultMessage를 BaseResDto에 set해서 Return한다.
  
  

📌 서비스 함수의 Return Type이 BaseResDto인 이유는 UserResDto가 해당 클래스를  상속(Is a) 받았기 때문에 가능한 것이다. 이런식으로 Response Dto에 BaseResDto를 상속받아서 각 API마다 Return Class를 BaseResDto로 선언 하면 된다.