[TIL] 2025-01-27_@ExceptionHandler

🔫 일정관리 API 를 구현하며 겪은 문제점과 해결방법, 새로 알게된 점을 기록합니다.

@ExceptionHandler

어노테이션 하위 Controller 계층에서 발생하는 에러를 잡아서 메서드로 처리해주는 기능이다.

import java.io.IOException;

import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ExceptionHandler;

@Controller
public class SimpleController {

	@ExceptionHandler(IOException.class)
	public ResponseEntity<String> handle() {
		return ResponseEntity.internalServerError().body("Could not read file storage");
	}

}

메서드의 인자로 Exception 을 받고 특정 Exception 을 설정하여 처리할 수 있다.

@ControllerAdvice

@Controller 을 사용하는 모든 클래스에서 발생하는 에러들을 잡아준다.

범위 설정

일부 에러만 처리하고 싶을 경우 따로 설정한다.

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

1. 어노테이션: 특정 어노테이션 지정
2. Base Package (Base Classes): 탐색 패키지 지정
3. assignableTypes: 특정 클래스 지정

@ControllerAdvice 와 @ExceptionHandler 를 함께 사용하면 전체 Controller 에서 발생하는 에러를 잡아 메서드로 처리할 수 있다.

@RestControllerAdvice

@ControllerAdvice + @ResponseBody 을 가지고 있다.
@RestControllerAdvice 의 메서드로 HTTP Message Body에 문자열을 리턴할 수 있다.

프로젝트 리펙토링

예외 발생 처리

에러코드 정의

서버에서 발생 가능한 예외조건을 정리하여 Enum 클래스로 정의

@AllArgsConstructor
@Getter
public enum ErrorCode {
    INVALID_PARAMETER(HttpStatus.BAD_REQUEST, "001_INVALID_PARAMETER", "파라미터 값을 확인해주세요."),
    USER_NOT_FOUND(HttpStatus.NOT_FOUND, "002_USER_NOT_FOUND", "존재하지 않는 유저 ID 입니다."),
    SCHEDULE_NOT_FOUND(HttpStatus.NOT_FOUND, "003_SCHEDULE_NOT_FOUND", "존재하지 않는 일정 ID 입니다."),
    PASSWORD_INCORRECT(HttpStatus.BAD_REQUEST, "004_PASSWORD_INCORRECT", "비밀번호가 일치하지 않습니다."),
    ENTITY_DELETED(HttpStatus.BAD_REQUEST, "005_ENTITY_DELETED", "이미 삭제된 정보입니다."),
    UNKNOWN(HttpStatus.INTERNAL_SERVER_ERROR, "999_UNKNOWN", "알 수 없는 오류가 발생했습니다.");

    private final HttpStatus status;
    private final String code;
    private final String message;
}

• status: API로 반환될 HTTP 상태 코드
• code: 클라이언트 개발자가 에러 상황에 참조할 수 있는 서버 에러 코드
• message: 전달받은 에러 코드에 대한 설명

사용자 정의 예외 클래스 생성

예외를 전달할 때, 정의한 ErrorCode를 이용해 정보를 전달하기 위한 사용자 예외 클래스를 생성

@Getter
@Slf4j
public class CustomException extends RuntimeException {
    private final HttpStatus status;
    private final ErrorCode errorCode;
    private final String detail;

    public CustomException(ErrorCode errorCode) {
        this.status = errorCode.getStatus();
        this.errorCode = errorCode;
        this.detail = "";
    }

    public CustomException(ErrorCode errorCode, String detail) {
        this.status = errorCode.getStatus();
        this.errorCode = errorCode;
        this.detail = detail;
    }

    public CustomException(Exception exception) {
        if (exception.getClass() == CustomException.class) {
            CustomException customException = (CustomException) exception;
            this.status = customException.getStatus();
            this.errorCode = customException.getErrorCode();
            this.detail = customException.getDetail();
        } else {
            this.status = HttpStatus.INTERNAL_SERVER_ERROR;
            this.errorCode = ErrorCode.UNKNOWN;
            this.detail = "알 수 없는 오류 발생, 개발팀에 문의 바랍니다.";
            log.error(exception.getMessage(), exception);
        }
    }
}

사용자 예외 클래스에서 정의되지 않은 예외는 개발자가 예상하지 못한 오류로 예외 원인을 추적하고 해결할 수 있도록 로그를 남긴다. API 수신 측에서는 구체적인 Exception 을 알 수 없도록 에러메시지를 변환하여 응답 메시지에 보낸다.

@ExceptionHandler 공통 예외 처리 구현

Response(응답) 데이터로 예외 메세지를 보낼 수 있도록 ResponseEntity를 반환하는 DTO 생성

@Data
@Builder
public class ErrorResponseDto {
    private String code;
    private String message;
    private String detail;

    public static ResponseEntity<ErrorResponseDto> errResponseEntity(CustomException e) {
        ErrorCode errorCode = e.getErrorCode();
        String detail = e.getDetail();

        return ResponseEntity.status(e.getStatus())
                .body(ErrorResponseDto.builder()
                        .code(errorCode.getCode())
                        .message(errorCode.getMessage())
                        .detail(detail)
                        .build());
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(Exception.class)
    private ResponseEntity<ErrorResponseDto> handleException(Exception e) {
        return ErrorResponseDto.errResponseEntity(new CustomException(e));
    }
}

이때, 모든 클래스에서 공통 예외 처리가 가능하도록 @RestControllerAdvice 가 적용된 클래스를 생성하여 처리할 수 있다.

API 실행 및 결과 확인 (사용자 메시지 전달 확인)

예시) 데이터의 수정, 삭제 시 입력한 비밀번호와 기존 비밀번호가 일치하지 않는 경우

• Status: 400 Bad Request
• Response Body: ErrorResponseDto에 정의된 에러코드, 에러메세지를 JSON 형식으로 반환

🔗 참고자료
[스프링부트] @ExceptionHandler를 통한 예외처리
[Springboot] Custom exception 설정하기

➕) Swagger 적용 시 @RestControllerAdvice NoSuchMethodError

서버 로그에 다음과 같은 예외가 확인된다.

Caused by: java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'

How to use both @RestControllerAdvice and Swagger UI in Spring boot

위의 답변을 참고하여 @RestControllerAdvice 어노테이션을 사용한 컨트롤러에 @Hidden(io.swagger.v3.oas.annotations.Hidden) 을 추가하여 Swagger API 문서 생성 시 Fetch error 를 방지하였다.

@Hidden

Swagger 라이브러리에서 API 문서화 시 특정 API 엔드포인트나 모델을 문서화에서 제외하고 싶을 때 사용한다. 이 어노테이션을 사용하면 해당 API 메서드나 모델이 Swagger UI나 자동 생성된 API 문서에서 나타나지 않게 된다.

---

📝 TODO

1. 도전 과제 Lv6 구현
2. 프로젝트 통합테스트
3. Swagger 적용하기 🌳

💭 Diary

아직 요구사항을 읽고 정확한 사양을 뽑아내는게 어려워 요구사항 해석을 잘못하였다. 다행히 코드를 많이 수정하지는 않았지만 실무에서 이런 상황이 생겼다고 상상하니 아찔했다.😨 시간을 효율적으로 쓰려면 역시 기초 설계부터 탄탄해야한다는 것을 다시 깨달았다. 코드 작성을 마친 뒤 꼼꼼히 분석하고 여러 번 검토하여 최대한 완성도를 높여야겠다.