아래는 개발 블로그에 바로 올려도 될 퀄리티로 정리한 @RestControllerAdvice 완전 이해 가이드야. Spring Boot + Kotlin/Java 개발자가 꼭 알아야 할 핵심 개념들만, 실무 스타일로 정리했어.
⸻
🚀 Spring Boot에서 @RestControllerAdvice 완벽 가이드
— “컨트롤러 예외 처리의 정석”
웹 애플리케이션을 만들다 보면 컨트롤러마다 이런 코드가 반복된다.
try { ... } catch (Exception e) { jsonData.put("result", "fail"); }
문제는? • 모든 API마다 try-catch 반복 → 지저분함 • 예외가 각각 다르게 처리됨 → 일관성 없음 • 에러 메시지 포맷 관리 불가 → 클라이언트 혼란 • 유지보수 난이도 ↑
Spring Boot에서는 이런 문제를 해결하기 위해 전역 컨트롤러 예외 처리기(Global Exception Handler)를 제공한다. 그 핵심이 바로 @RestControllerAdvice 이다.
⸻
1️⃣ @RestControllerAdvice란 무엇인가?
한마디로,
컨트롤러에서 발생하는 모든 예외를 한 곳에서 처리하는 전역 예외 처리기
다른 말로 하면… • 컨트롤러 예외를 하나의 클래스에서 처리 • API 응답 포맷을 통일 • 중복 try-catch 제거 • 공통 로깅·추가 작업 가능
✔ @ControllerAdvice + @ResponseBody 의 조합
@RestControllerAdvice는 아래 두 어노테이션을 합쳐 놓은 것과 같다.
어노테이션 의미 @ControllerAdvice 전역적으로(모든 컨트롤러에) 적용 @ResponseBody 반환 객체를 JSON으로 응답
그래서 API 개발에서는 사실상 필수라고 보면 된다.
⸻
2️⃣ 예외 처리의 기본 구조
예외 핸들러는 아래처럼 만든다.
import org.springframework.http.HttpStatus
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.ResponseStatus
import org.springframework.web.bind.annotation.RestControllerAdvice
@RestControllerAdvice
class GlobalExceptionHandler {
@ExceptionHandler(Exception::class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
fun handleException(e: Exception): ApiResponse<Unit> {
return ApiResponse(
success = false,
message = "시스템 오류가 발생했습니다.",
errorCode = "INTERNAL_ERROR"
)
}
}
ApiResponse는 5번에서 정의하는 공통 DTO다. 응답 본문의 success = false만으로 HTTP 상태가 바뀌지는 않아서, 위 예제는 @ResponseStatus로 500을 지정했다.
⸻
3️⃣ 동작 방식 (Internals)
Spring MVC는 컨트롤러에서 예외가 발생하면 다음 순서로 처리한다: 1. 컨트롤러 내부에서 try-catch로 처리? → 여기서 끝. 2. 처리되지 않은 예외 발생 → DispatcherServlet이 @ExceptionHandler를 탐색한다. 3. 가장 맞는 타입의 예외 핸들러 메서드를 호출한다.
즉, 아래처럼 다양한 예외를 구분할 수도 있다. 여기서는 선언 형태만 보고, 실제 본문과 상태 코드는 4번에서 채워본다.
@ExceptionHandler(IllegalArgumentException::class)
fun handleBadRequest(e: IllegalArgumentException): ApiResponse<Unit> { ... }
@ExceptionHandler(NoSuchElementException::class)
fun handleNotFound(e: NoSuchElementException): ApiResponse<Unit> { ... }
⸻
4️⃣ 실무에서 가장 많이 쓰는 예외 유형별 처리
✔ 잘못된 요청 (400)
아래 메서드들은 GlobalExceptionHandler 안에 넣는다. HttpStatus와 ResponseEntity는 각각 org.springframework.http에서 가져온다.
@ExceptionHandler(IllegalArgumentException::class)
fun badRequest(e: IllegalArgumentException) =
ResponseEntity.status(HttpStatus.BAD_REQUEST).body(
ApiResponse<Unit>(false, message = e.message ?: "잘못된 요청입니다.")
)
✔ 찾을 수 없음 (404)
@ExceptionHandler(NoSuchElementException::class)
fun notFound(e: NoSuchElementException) =
ResponseEntity.status(HttpStatus.NOT_FOUND).body(
ApiResponse<Unit>(false, message = "데이터를 찾을 수 없습니다.")
)
✔ 서버 오류 (500)
@ExceptionHandler(Exception::class)
fun internal(e: Exception) =
ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(
ApiResponse<Unit>(false, message = "시스템 오류가 발생했습니다.")
)
ResponseEntity로 HTTP 상태와 본문을 함께 정한다. 데이터가 없는 오류 응답은 ApiResponse<Unit>로 타입을 명시해, Kotlin이 T를 추론할 수 없는 문제도 피한다. 2번의 기본 핸들러와 여기의 internal은 같은 예외를 처리하므로 둘 중 하나만 사용한다.
이렇게 해두면 컨트롤러는 예외를 던지기만 해도 OK:
if (list.isEmpty()) throw NoSuchElementException()
⸻
5️⃣ 실제 실무 스타일 예제 (Response Wrapper 포함)
ApiResponse라는 공통 응답 DTO를 만들어서 통합 관리한다.
data class ApiResponse<T>(
val success: Boolean,
val data: T? = null,
val message: String? = null,
val errorCode: String? = null
)
그리고… 2번의 기본 핸들러 대신 아래 형태를 사용할 수도 있다.
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.RestControllerAdvice
@RestControllerAdvice
class GlobalExceptionHandler {
@ExceptionHandler(Exception::class)
fun handle(e: Exception): ResponseEntity<ApiResponse<Unit>> {
// 로그
e.printStackTrace()
return ResponseEntity
.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(
ApiResponse<Unit>(
success = false,
message = "시스템 오류가 발생했습니다.",
errorCode = "INTERNAL_ERROR"
)
)
}
}
⸻
6️⃣ 기존 코드가 어떻게 깔끔해지는지 비교해보기
🔥 Before (try-catch 반복)
@RequestMapping(...) public Map<String, Object> readSomething() { Map<String,Object> json = new HashMap<>(); try { json.put("data", service.read()); json.put("result", "ok"); } catch (Exception e) { e.printStackTrace(); json.put("message", "오류"); json.put("result", "fail"); } return json; }
⸻
🌟 After (@RestControllerAdvice 적용)
@GetMapping("/something")
fun readSomething(): ApiResponse
실수로 예외가 발생해도: • try-catch 필요 없음 • 응답 포맷 자동 정리 • 로그도 자동 • 일관성 유지
⸻
7️⃣ 흔히 쓰는 고급 패턴들
✔ 비즈니스 예외 직접 생성하기
class BizException(
val code: String,
override val message: String
) : RuntimeException(message)
핸들러:
@ExceptionHandler(BizException::class)
fun handleBizException(e: BizException) =
ResponseEntity.status(HttpStatus.BAD_REQUEST).body(
ApiResponse<Unit>(false, message = e.message, errorCode = e.code)
)
여기서는 아래의 유효성 검사 실패를 400으로 처리한다. 다른 비즈니스 예외는 서비스의 오류 정책에 맞게 상태 코드를 나눠야 한다.
컨트롤러에서는 그냥 던지면 됨:
if (!valid) throw BizException("VALID_FAIL", "유효하지 않은 값입니다.")
⸻
8️⃣ 왜 실무에서 무조건 쓰는가?
장점 설명 중복 제거 모든 try-catch 제거 유지보수성 에러 정책 변경이 매우 쉬움 일관성 모든 API 응답 패턴을 통일 확장성 예외 종류별 처리 가능 보안 내부 에러 스택을 클라이언트에 노출하지 않음
특히 MES/ERP 같이 화면이 수십~수백개인 시스템에서는 한 줄당 1초씩만 절약되어도 몇 시간 절약됨.
⸻
9️⃣ 실제 현업에서 사용하는 패턴 조합 • @RestControllerAdvice • @ExceptionHandler • 공통 Response DTO (ApiResponse) • Custom BizException • ValidationException 처리 • Authentication/Authorization Exception 처리
이 세트를 템플릿화하면 새로운 프로젝트 시작할 때 바닥공사 80%는 이미 끝난 상태가 된다.
⸻
🔟 마무리
@RestControllerAdvice는 “Spring Boot API 개발의 필수 인프라”다.
이걸 적절히 설계해두면: • 컨트롤러는 “정상 로직”만 작성 • 예외는 자동 관리 • 응답도 자동 통일 • 유지보수 시간 절약 • 코드 가독성 상승
결국 개발자가 본질적인 업무 로직에 집중할 수 있게 해주는 핵심 기술이다.
⸻
원하면: 🛠 Kotlin + Spring Boot 기반으로 “전역 예외처리 모듈 세트(파일 3개)”를 완성 형태로 생성해서 제공해줄게. Junha MES 프로젝트 형태에 맞추어 바로 사용할 수 있는 수준으로.
확인한 공식 문서
2026-11-04에 예제의 오류 응답 타입과 HTTP 상태 지정을 정리했다.
댓글 · 감정
한마디 남겨주세요 — GitHub 로그인이 필요해요.