Spring Boot와 예외 처리 완벽 가이드: 글로벌 예외 처리 전략과 커스텀 에러 메시지 구현

 

Spring Boot 애플리케이션 개발에서 중요한 부분 중 하나는 에러 처리(예외 처리) 입니다. 적절한 예외 처리를 통해 사용자에게 유용한 에러 메시지를 제공 하고, 서비스의 안정성을 높일 수 있습니다. 이번 포스팅에서는 @ControllerAdvice 와 @ExceptionHandler 를 활용한 예외 처리 , 글로벌 예외 처리 전략 , 그리고 API 응답에 커스텀 에러 메시지를 전달하는 방법 을 알아봅니다.

 

---

 

 

목차

1. Spring Boot 예외 처리의 기본 개념
2. @ControllerAdvice 와 @ExceptionHandler 를 활용한 예외 처리
3. 글로벌 예외 처리 전략
4. API 응답에 커스텀 에러 메시지 전달하기
5. 에러 처리의 중요성과 최신 트렌드

 

---

 

1. Spring Boot 예외 처리의 기본 개념

애플리케이션이 실행 도중 예기치 않은 예외(Exception) 를 만나면, 이를 적절히 처리하지 않으면 서버가 중단되거나 잘못된 응답을 반환할 수 있습니다. Spring Boot는 스프링 시큐리티 와 함께 예외 처리를 위한 도구를 제공하며, 대표적으로 @ControllerAdvice 와 @ExceptionHandler 가 있습니다.

예외 처리의 필요성

• 사용자 경험 향상 : 직관적인 에러 메시지 제공
• 서비스 안정성 보장 : 에러가 발생해도 애플리케이션이 중단되지 않도록 보호
• 디버깅 용이 : 로그에 상세한 에러 정보를 기록하여 문제를 빠르게 해결

 

---

 

2. @ControllerAdvice 와 @ExceptionHandler 를 활용한 예외 처리

 

@ControllerAdvice 란?

@ControllerAdvice 는 모든 컨트롤러에서 발생하는 예외를 전역적으로 처리 할 수 있도록 도와주는 애너테이션입니다. 각 컨트롤러에서 개별적으로 예외 처리를 구현할 필요 없이, 전역 예외 처리 클래스 에서 처리할 수 있습니다.

예제 코드: 예외 처리 구현하기

 

UserNotFoundException.java (커스텀 예외)

package com.example.demo.exception;

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

 

GlobalExceptionHandler.java (글로벌 예외 처리)

package com.example.demo.handler;

import com.example.demo.exception.UserNotFoundException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<Map<String, Object>> handleUserNotFoundException(UserNotFoundException ex) {
        Map<String, Object> response = new HashMap<>();
        response.put("timestamp", LocalDateTime.now());
        response.put("message", ex.getMessage());
        response.put("status", HttpStatus.NOT_FOUND.value());

        return new ResponseEntity<>(response, HttpStatus.NOT_FOUND);
    }
}

코드 설명

1. @ControllerAdvice : 모든 컨트롤러의 예외를 처리하는 클래스임을 선언합니다.
2. @ExceptionHandler : 특정 예외를 처리하는 메서드에 사용합니다.
3. ResponseEntity : HTTP 상태 코드와 함께 커스텀 에러 메시지를 반환합니다.

 

---

 

3. 글로벌 예외 처리 전략

Spring Boot에서는 모든 컨트롤러에서 발생할 수 있는 예외를 글로벌하게 처리 할 수 있습니다. 이때 사용되는 전략은 아래와 같습니다:

예외 처리 전략	설명	예시
글로벌 예외 처리	@ControllerAdvice 로 모든 예외를 처리함	모든 컨트롤러의 예외를 하나의 클래스에서 처리
특정 예외 처리	@ExceptionHandler 로 특정 예외를 처리함	UserNotFoundException 처리
HTTP 상태 코드 매핑	예외에 맞는 상태 코드를 반환	404: 리소스 없음
커스텀 에러 메시지	에러 메시지에 사용자 정의 정보 추가	사용자 ID가 없는 경우 “사용자 없음” 메시지

---

 

4. API 응답에 커스텀 에러 메시지 전달하기

 

커스텀 에러 메시지 포함 예제

아래는 사용자 조회 API에서 존재하지 않는 사용자 ID로 요청할 경우 예외를 처리하고, 커스텀 메시지를 응답으로 보내는 예제입니다.

 

UserController.java (사용자 API 컨트롤러)

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.exception.UserNotFoundException;
import com.example.demo.repository.UserRepository;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

import java.util.Optional;

@RestController
public class UserController {

    private final UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        return userRepository.findById(id)
                .orElseThrow(() -> new UserNotFoundException("사용자를 찾을 수 없습니다. ID: " + id));
    }
}

입출력 예제

요청 :
GET /users/999

응답 :

{
    "timestamp": "2024-10-13T12:34:56.789",
    "message": "사용자를 찾을 수 없습니다. ID: 999",
    "status": 404
}

 

---

 

5. 에러 처리의 중요성과 최신 트렌드

• 에러 처리는 사용자 경험에 직결 됩니다. 적절한 메시지를 제공하지 않으면 사용자는 혼란을 느낄 수 있습니다.
• API 응답 일관성 : 모든 에러 메시지를 일관된 형식으로 제공하는 것이 중요합니다.
• 로그와 모니터링 : 에러를 로그에 기록하고 모니터링 도구와 연동해 실시간으로 확인하는 것이 트렌드입니다.
• 커스텀 예외 처리 와 함께 Spring Boot Actuator 를 사용해 에러 정보를 실시간으로 모니터링하는 사례도 늘어나고 있습니다.

 

---

 

관련 링크

Spring 공식 문서👆

Spring Boot 예외 처리 가이드👆

Spring Boot Actuator로 모니터링 하기👆

JUnit을 사용한 예외 처리 테스트👆

ResponseEntity 사용법👆

HTTP 상태 코드 설명👆

---

FAQ

 

1. 글로벌 예외 처리와 개별 예외 처리의 차이점은 무엇인가요?

• 글로벌 예외 처리는 모든 컨트롤러의 예외 를 한 곳에서 처리하고, 개별 예외 처리는 특정 컨트롤러에서만 처리합니다.

2. API 응답에 JSON 형식으로 에러를 반환하려면 어떻게 하나요?

• ResponseEntity 를 사용해 JSON 형식의 커스텀 메시지를 반환할 수 있습니다.

3. @ExceptionHandler 를 여러 번 사용할 수 있나요?

• 네, 한 클래스에서 여러 종류의 예외를 처리하기 위해 여러 개의 @ExceptionHandler 메서드 를 선언할 수 있습니다.

4. 커스텀 예외를 언제 사용해야 하나요?

• 비즈니스 로직에 맞는 명확한 에러 처리가 필요할 때 커스텀 예외를 정의 해 사용하는 것이 좋습니다.

5. Spring Boot에서 발생한 예외를 로그에 기록하려면 어떻게 하나요?

• Logger 를 사용해 예외 발생 시 로그를 남기고, 모니터링 도구와 연동해 실시간으로 확인할 수 있습니다.

 

---

 

마무리

이번 포스팅에서는 Spring Boot의 예외 처리 전략 을 상세히 살펴보았습니다. 글로벌 예외 처리 와 커스텀 예외 메시지 는 애플리케이션의 안정성 과 사용자 경험 을 개선하는 중요한 요소입니다. Spring Boot와 Spring Security 를 사용하는 경우에도, 다양한 예외 상황에 맞춘 정교한 예외 처리 전략 은 필수적입니다.

이제 여러분의 프로젝트에 글로벌 예외 처리와 커스텀 메시지 를 도입해보세요. 이를 통해 API 응답의 일관성 을 유지하고, 사용자가 명확하게 이해할 수 있는 에러 메시지를 제공할 수 있습니다. 적절한 로그 관리와 모니터링 도 함께 도입하면 서비스의 안정성을 한층 더 높일 수 있습니다.