[Spring] 실무에서의 Best Practices #2

@Controller에서 Exception 처리

---

@Controller에서 Exception 처리

Spring에서 제공하는 다양한 예외 처리 방법

Spring에서는 여러 가지 예외 처리 방법을 제공하며, 그 중 대표적인 방법이 ExcepitonHandler, ControllerAdvice, ResponseStatusException 등을 활용하는 것이다.

 

ExceptionResolver: Spring(WAS) 내 예외 처리

• BasicErrorController: Spring의 기본 에러 처리를 담당하는 컨트롤러로, 페이지 기반 에러를 처리한다.
• 예외 처리를 위한 try-catch를 사용하지 않고, 공통 관심사(cross-cutting concerns)를 메인 로직에서 분리
  • Spring의 HandlerExceptionResolver는 예외 처리 전략을 추상화한 인터페이스로, 발생한 예외를 처리하는 방법을 정의한다. Spring에서 예외 처리 순서:
    1. DefaultErrorAttributes: 에러 속성을 저장하지만, 예외 자체는 처리하지 않는다.
    2. ExceptionHandlerExceptionResolver: @ExceptionHandler를 통해 예외를 처리한다.
    3. ResponseStatusExceptionResolver: @ResponseStatus 또는 ResponseStatusException을 처리한다.
    4. DefaultHanlderExceptionResolver: 기본적으로 Spring 내부에서 발행하는 예외를 처리한다.

ResponseStatus / ResponseStatusException / ExceptionHandler

1. @ResponseStatus: 특정 예외에 대해 반환할 HTTP 상태 코드를 명시한다. 예외 클래스 자체 또는 @ControllerAdvice와 함께 사용할 수 있다.

• 단점: 응답 내용을 수정할 수 없고, 예외 클래스 단위로만 처리할 수 있어 세부적인 예외처리가 어렵다.

@ResponseStatus(HttpStatus.NOT_FOUND)
public class NoSuchElementFoundException extends RuntimeException {
	...
}

 

2. ResponseStatusException: 예외 발생과 동시에 HTTP 상태 코드를 명시할 수 있는 방식이다. 예외 발생 시 HTTP 상태 코드와 메세지를 함께 정의한다.

@GetMapping("/product/{id}")
public ResponseEntity<Product> getProduct(@PathVariable String id) {
    try {
        return ResponseEntity.ok(productService.getProduct(id));
    } catch (NoSuchElementFoundException e) {
        throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Item Not Found");
    }
}

 

3. ExceptionHandler: 특정 예외가 발생했을 때 그 예외를 처리하기 위한 메서드를 정의한다. 가장 유연한 예외 처리 방법으로, @ControllerAdvice와 함께 사용하여 중앙에서 처리할 수 있다.

@ExceptionHandler(NoSuchElementFoundException.class)
public ResponseEntity<String> handleNoSuchElement(NoSuchElementFoundException e) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
}

---

Custom Exception 생성하는 방법: 다양한 Exceptions

예외 처리를 세분화하기 위해 클래스 단위와 필드 단위로 예외를 생성 할 수 있다.

클래스 단위의 Custom Exception

• RuntimeException을 상속받아 다양한 사용자 정의 예외를 만들 수 있다. 예를 들어, 특정 사용자를 찾을 수 없을 때 UserNotFoundException을 정의하여 예외 상황을 처리할 수 있다.

public class UserNotFoundException extends RuntimeException {
	public UserNotFoundException(String message) {
    	super(message);
    }
}

필드 단위의 Custom Exception: Enum을 통한 관리

• 필드 단위의 예외 처리는 Enum을 사용하여 관리할 수 있다. 다양한 예외 상황에 따라 적절한 처리 방법을 명시하고, 이를 통해 예외 처리를 간결하게 구현할 수 있다. ExceptionType과 같은 Enum을 사용하면 예외 케이스마다 처리해야 할 내용들을 한 곳에서 관리할 수 있다. 이렇게 하면 각 예외에 따른 메세지와 HTTP 상태 코드를 Enum에 정의해 관리할 수 있다.

public enum ExceptionType {
    INVALID_REQUEST(HttpStatus.BAD_REQUEST, "잘못된 요청입니다."),
    NOT_EXIST(HttpStatus.NOT_FOUND, "존재하지 않는 리소스입니다.");

    private final HttpStatus status;
    private final String message;
}

@Controller에서 Exception 처리하지 않을 때, 500 표준 오류 반환

스프링에서 컨트롤러에서 예외를 처리하지 않으면 기본적으로 500 Internal Server Error가 반환된다.

이때 발생한 예외를 처리하지 않으면 기본적으로 스프링은 오류 페이지 또는 JSON 응답을 반환한다.

 

예시 코드

@GetMapping("/user/{id}")
public ResponseEntity<UserResponseDto> getUser(@PathVariable Long id) {
    UserResponseDto user = userService.findById(id);
    if (user == null) {
        throw new NoSuchElementFoundException("User not found");
    }
    return ResponseEntity.ok(user);
}

위 코드에서 userService.findById()가 null을 반환하고 예외 처리를 하지 않으면, 기본적으로 500 Internal Server Error가 발생한다.

 

@Controller에서 Exception 처리 및 ResponseEntity(Wrapper) 404 반환

스프링에서는 ExceptionHandler를 사용하여 예외를 처리하고, ResponseEntity를 통해 적절한 HTTP 응답을 반환할 수 있다.

@ExceptionHandler(NoSuchElementFoundException.class)
public ResponseEntity<String> handleNoSuchElementFoundException(NoSuchElementFoundException ex) {
    return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
}

@GetMapping("/user/{id}")
public ResponseEntity<UserResponseDto> getUser(@PathVariable Long id) {
    UserResponseDto user = userService.findById(id);
    if (user == null) {
        throw new NoSuchElementFoundException("User not found");
    }
    return ResponseEntity.ok(user);
}

위 코드에서 NoSuchElementFoundException 예외가 발생할 경우 404 Not Fount 응답을 반환한다.

 

@Controller에서 다양한 Exception 처리 필요성

다양한 Exception 처리할 때는 ExceptionHandler를 사용하여 각 예외에 맞는 응답을 제공하는 것이 중요하다. 모든 예외를 동일하게 처리하면 적절한 응답을 반환할 수 없으므로, 예외에 따라 다른 HTTP 응답 상태와 메세지를 클라이언트에게 제공해야한다.

 

• 다양한 종류의 Exception 처리 필요(한 종류의 Exception만 처리하는 코드)

@ExceptionHandler(NoSuchElementFoundException.class)
public ResponseEntity<String> handleNoSuchElementFoundException(NoSuchElementFoundException ex) {
    log.warn(ex.getMessage());
    ex.printStackTrace();
    return new ResponseEntity<>("Resource not found", HttpStatus.NOT_FOUND);
}

@GetMapping("/user/{id}")
public ResponseEntity<UserResponseDto> getUser(@PathVariable Long id) {
    UserResponseDto user = userService.findById(id);
    if (user == null) {
        throw new NoSuchElementFoundException("User not found");
    }
    return ResponseEntity.ok(user);
}

이 코드는 모든 예외를 404 Not Found로 반환하는 방식이므로, 실제 다양한 상황에 맞춰 적절한 응답을 제공하지 못한다.

• CustomException을 통한 다양한 Exception 처리

public class CustomException extends RuntimeException {
    private String type;

    public CustomException(String type, String message) {
        super(message);
        this.type = type;
    }

    public String getType() {
        return type;
    }
}

@ExceptionHandler(CustomException.class)
public ResponseEntity<String> handleCustomException(CustomException ex) {
    if ("INVALID_REQUEST".equals(ex.getType())) {
        log.warn(ex.getMessage());
        ex.printStackTrace();
        return new ResponseEntity<>("Invalid request", HttpStatus.BAD_REQUEST);
    } else if ("NOT_EXIST".equals(ex.getType())) {
        log.warn(ex.getMessage());
        ex.printStackTrace();
        return new ResponseEntity<>("Resource not found", HttpStatus.NOT_FOUND);
    } else {
        log.error(ex.getMessage());
        ex.printStackTrace();
        return new ResponseEntity<>("Internal server error", HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

이 코드는 CustomException을 사용하여 예외의 유형에 따라 적절한 상태 코드와 메세지를 반환한다. 예를 들어, INVALID_REQUEST 예외는 404 Bad Reqeust, NOT_EXIST 예외는 404 Not Found로 처리 된다.

 

• Enum을 사용한 Exception 처리

@Getter
@AllArgsConstructor
public enum ExceptionType {
    INVALID_REQUEST(HttpStatus.BAD_REQUEST, "잘못된 요청입니다."),
    NOT_EXIST(HttpStatus.NOT_FOUND, "존재하지 않는 리소스입니다.");

    private final HttpStatus status;
    private final String message;
}

public class CustomException extends RuntimeException {
    private final ExceptionType type;

    public CustomException(ExceptionType type) {
        super(type.getMessage());
        this.type = type;
    }

    public ExceptionType getType() {
        return type;
    }
}

@ExceptionHandler(CustomException.class)
public ResponseEntity<String> handleCustomException(CustomException ex) {
    return new ResponseEntity<>(ex.getMessage(), ex.getType().getStatus());
}

 

위 코드에서는 ExceptionType Enum을 사용하여 예외 유형에 따른 상태 코드와 메세지를 정의하고, CustomException이 발생하면 해당 Enum의 값을 사용하여 처리한다.

---

Exception 발생지(근원지)를 어디로 두어야 할까? + @JsonCreator 역직렬화

핵심 로직 내부에 Exception을 발생시켜야 하는 이유

Enum 타입 변환 시 발생하는 예외는 변환 로직에서 발생해야 한다. 변환 로직과 분리된 예외 처리는 잘못된 설계이다. 예를 들어 String에서 Enum으로 변환할 때 예외 발생 여부를 외부 로직에 맡기는 대신, 변환 메서드 내부에서 예외를 처리하면 더 명확하고 유지보수가 쉬워진다.

 

예시 코드(잘못된 방식) - 핵심 로직 외부에서 예외 발생

public enum Status {
    ACTIVE, INACTIVE;

    public static Status from(String status) {
        for (Status s : Status.values()) {
            if (s.name().equalsIgnoreCase(status)) {
                return s;
            }
        }
        return null; // 핵심 로직 외부에서 예외 처리
    }
}

public class UserController {
    public void processStatus(String status) {
        Status userStatus = Status.from(status);
        if (userStatus == null) {
            throw new CustomException("Invalid status");
        }
    }
}

 

 

해당 코드는 from() 메서드 외부에서 예외를 처리한다.

 

예시 코드(올바른 방식) - 핵심 로직 내부에서 예외 발생

public enum Status {
    ACTIVE, INACTIVE;

    public static Status from(String status) {
        return Arrays.stream(Status.values())
            .filter(s -> s.name().equalsIgnoreCase(status))
            .findFirst()
            .orElseThrow(() -> new CustomException("Invalid status: " + status));
    }
}

public class UserController {
    public void processStatus(String status) {
        Status userStatus = Status.from(status); // 예외는 내부에서 처리
    }
}

 

해당 코드에서는 Enum 변환 로직 내부에서 예외가 발생하므로 변환 로직을 사용할 때마다 일관된 방식으로 예외 처리가 이루어진다.

 

---

@RequestBody의 Null + Validation에 따른 Exception 발생

DTO 객체를 통해 Null 체크와 Validation을 중앙화하여 처리할 수 있다. 예를 들어, 요청 DTO에서 빈 값이나 잘못된 데이터를 받는 경우, 이를 일일이 컨트롤러에서 처리하는 대신 DTO 클래스 자체에서 처리하는 방식이다.

 

Null 및 Validation 로직을 외부에서 처리하는 잘못된 방식

@PostMapping("/product")
public ResponseEntity<String> createProduct(@RequestBody ProductRequestDto requestDto) {
    if (requestDto.getName() == null || requestDto.getName().isEmpty()) {
        throw new CustomException("Product name is required");
    }
    if (requestDto.getPrice() <= 0) {
        throw new CustomException("Price must be greater than zero");
    }
    productService.createProduct(requestDto);
    return ResponseEntity.ok("Product created");
}

 

DTO에서 Null 및 Validation 처리하는 올바른 방식

public class ProductRequestDto {
    @NotNull(message = "Product name is required")
    private String name;

    @Min(value = 1, message = "Price must be greater than zero")
    private int price;

    // getters and setters
}

@PostMapping("/product")
public ResponseEntity<String> createProduct(@Valid @RequestBody ProductRequestDto requestDto) {
    productService.createProduct(requestDto);
    return ResponseEntity.ok("Product created");
}

위 코드는 DTO 객체에서 바로 Validation을 처리하므로 컨트롤러에서는 Validation 로직을 신경쓰지 않아도된다.

---

@Controller의 반환 데이터에 대한 커스텀 Wrapper Class

@Controler에서 Exception에 따른 커스텀 Wrapper Class로 JSON 반환

문제 상황

 

프론트엔드 또는 API에 일관된 JSON 형태로 응답을 제공해야 한다. 기존 방식에서 API 메서드마다 반환하는 데이터 구조가 달라, 프론트엔드에서 일일이 처리가 필요했다. 또한, 다양한 예외 발생 시 일관성 없이 예외가 처리되었고, 에러 메세지의 관리와 처리 방식이 복잡해졌다.

 

해결 방안

 

모든 @ReponseBody에서 일관된 객체(JSON)형태로 반환하도록 커스텀 Wrapper 클래스를 사용하는 방식이다. 이를 통해 일관된 형태의 응답을 제공하고 성공과 실패에 대한 메세지 처리를 더욱 체계화할 수 있다.

• 예시 코드: 커스텀 Response 클래스 사용하여 일관된 JSON 응답

RequestResult 클래스 정의

public class RequestResult<T> {
    private boolean success;
    private T data;
    private String message;

    // 성공 시
    public static <T> RequestResult<T> success(T data) {
        RequestResult<T> result = new RequestResult<>();
        result.success = true;
        result.data = data;
        result.message = "Operation Successful";
        return result;
    }

    // 실패 시
    public static <T> RequestResult<T> failure(String message) {
        RequestResult<T> result = new RequestResult<>();
        result.success = false;
        result.data = null;
        result.message = message;
        return result;
    }

    // Getters and Setters
}

 

Controller에서 RequestResult 반환

@RestController
public class ProductController {

    @GetMapping("/product/{id}")
    public RequestResult<Product> getProduct(@PathVariable String id) {
        try {
            Product product = productService.getProductById(id);
            return RequestResult.success(product);
        } catch (NoSuchElementException e) {
            return RequestResult.failure("Product not found");
        }
    }
}

위 코드는 성공과 실패를 모두 RequestResult 객체로 처리하여, 일관된 형태로 JSON 응답을 제공한다.

 

커스텀 Wrapper Class(JSON)의 객체 생성을 위한 정적 팩토리 메서드 활용

정적 팩토리 메서드를 통해 성공 및 실패 시 객체를 간단히 생성하여, 객체 생성 시 모든 경우의 수를 생성자에 노출하지 않고 필요한 경우에 따라 객체를 쉽게 생성할 수 있다.

 

예시 코드

public class ApiResponse<T> {
    private boolean success;
    private T data;
    private String error;

    // 성공 응답
    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.success = true;
        response.data = data;
        return response;
    }

    // 실패 응답
    public static <T> ApiResponse<T> failure(String error) {
        ApiResponse<T> response = new ApiResponse<>();
        response.success = false;
        response.error = error;
        return response;
    }

    // Getters and Setters
}

이 방식은 Controller뿐 아니라 서비스 계층, DTO 등에서도 쉽게 활용할 수 있으며, 일관된 응답 구조를 유지하고 처리 로직을 단순화하는데 큰 도움이 된다.

---

Exception 공통 처리의 필요성

Spring에서 @Valid와 @Secured를 처럼 추상화된 처리는 try-catch 구문을 통해 개발자가 직접 처리할 수 없다.

 

이전 방식의 문제:

• 기존에는 예외를 처리하기 위해서 @Controller 내 try-catch 구문으로 방어했다.
  • 만약 @Controller에 수백 개의 API 메서드가 있다면, 각 메서드마다 try-catch를 반복적으로 작성해야 하므로, 중복 코드가 발생하고 유지 보수도 어려워진다.

이후 해결책: 

• @ControllerAdvice와 @ExceptionHandler를 사용하면 try-catch를 대신하여 예외 처리를 중앙에서 일관되게 관리할 수 있다.
  • @ExceptionHandler를 통해 어떤 예외를 처리할지 명확하게 지정할 수 있다.
  • 여러 예외를 한 번에 처리하려면 @ExceptionHandler({AException.class, BException.class})처럼 처리할 수 있따.
  • 또는 예외별로 개별 @ExceptionHandler 메서드를 정의할 수 있지만, 예외 클래스들이 공통된 부모 클래스를 상속받지 않으면 중복 코드가 발생할 수 있다.

추가 기능:

1. HttpServletRequest 객체를 통해 어떤 유저가, 어떤 URL에서 에러가 발생했는지 추적할 수 있다.
2. @ResponseBody와 @ControllerAdvice를 조합하면 @RestControllerAdvice를 사용할 수 있어, RESTful 방식으로 JSON응답을 쉽게 반환할 수 있다.
3. 특정 패키지의 @Controller에만 적용할 수 있도록 @ControllerAdvice에 패키지 필터릭 옵션을 추가할 수 있다.

---

@ControllerAdvice로 Controller의 Exception 처리를 책임 위임

기존에는 @Controller 내에서 try-catch문으로 처리해야 했지만, @ControllerAdvice를 사용하면 이를 중앙화 할 수 있다. 이를 통해 개발자는 각 Controller에서 예외 처리 코드를 반복하지 않고, 중앙에서 일관된 예외 처리를 할 수 있다.

• 이 방법은 Entity나 DTO 객체에도 적용할 수 있으며, 상황에 맞는 정적 팩토리 메서드를 통해 객체 생성 시 모든 전달 인자를 노출하지 않도록 한다.
• 만약 @ResponseBody를 명시하지 않으면 500에러가 발생하며 JSON으로 응답되지 않기 때문에 주의해야한다.

@RestControllerAdvice = @ControllerAdvice + @ResponseBody

• @RestControllerAdvice는 @ControllerAdvice와 @ResponseBody를 합친 형태로, @RestController가 @Controller와 @ResponseBody를 결합한 것과 동일한 개념이다.
• 이를 통해 @RestController처럼, 예외 처리시 JSON 응답을 간편하게 반환할 수 있다.

---

@FieldDefaults: 필드 정의 시 접근 제어자 및 final 사용

@FieldDefaults는 클래스의 필드 정의 시 접근 제어자와 final 키워드를 명시적으로 선언하는 수고를 덜어준다. 특히, Service나 DTO 같은 객체에서 유용하게 사용할 수 있다.

• 필드에 매번 private final을 붙이는 것이 번거로울 때, @FieldDefaults를 통해 한 번에 처리할 수 있다.
• @Autowired를 대체하기 위해 @RequiredArgsContsructor와 final을 사용하는 경우에도 유용하다.

@RequiredArgsConstructor
@FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE)
public class PostService {
    final PostRepository postRepository;
}

• 또한, 생성자 발생 시 Lombok에서 @NoArgsConstructor나 @AllArgsConstructor에 access = AccessLevel.PROTECTED를 추가하여 접근 제어를 설정할 수도 있다.

---

ℹ️ 참고

[ASAC 6기 강의자료]