🎯 서버 개발 시 예외 처리는 어떻게 해야 할까? CustomException이란?

— InvalidCoordinateException, NotFoundException, CustomException 무엇이 다를까?

개발을 하다 보면 필연적으로 예외 처리를 하게 된다.

최근 공간 정보 기반 POI 프로젝트를 진행하면서 다양한 예외를 처리해야 했는데,

이 과정에서 "도메인별 예외"와 "공통 예외 처리 방식"의 차이를 깊게 이해하게 되었다.

이번 포스팅에서는 개별 예외 클래스(InvalidCoordinateException, NotFoundException)와 통합 예외 처리 방식(CustomException 패턴)의 차이를 비교하고, 어떤 상황에서 어떤 스타일이 적합한지 정리해보았다.

 

---

💥 문제 상황: 좌표가 잘못 들어왔을 때

예를 들어 사용자가 잘못된 위도를 입력한 경우:

{
  "latitude": 123.456, // ❌ 실제 위도 범위 초과
  "longitude": 126.9769
}

이럴 때 다음 두 가지 방식으로 예외 처리를 할 수 있다.

 

---

1️⃣ 개별 Exception: 의미를 명확히 전달

코드 예시

class InvalidCoordinateException(message: String) : RuntimeException(message)

throw InvalidCoordinateException("위도는 -90 ~ 90 사이여야 합니다.")

 

Handler

@ExceptionHandler(InvalidCoordinateException::class)
fun handleInvalidCoordinate(e: InvalidCoordinateException): ResponseEntity<ErrorResponse> {
    return ResponseEntity
        .badRequest()
        .body(ErrorResponse("C001", e.message ?: "잘못된 좌표입니다."))
}

 

장점

• 예외 이름만 봐도 어떤 문제인지 직관적
• 작은 규모의 프로젝트에서는 오히려 명확함.

단점

• 예외 클래스 수가 많아지면 중복과 관리의 어려움이 생김.
• 공통 응답 포맷 맞추기 어려움.

 

---

2️⃣ 통합 예외 처리: CustomException + ErrorCode

ErrorCode Enum

enum class ErrorCode(
    val code: String,
    val message: String,
    val status: HttpStatus
) {
    INVALID_COORDINATE("C001", "위도/경도가 잘못되었습니다.", HttpStatus.BAD_REQUEST),
    POI_NOT_FOUND("P001", "POI를 찾을 수 없습니다.", HttpStatus.NOT_FOUND)
}

 

예외 클래스

class CustomException(val errorCode: ErrorCode) : RuntimeException(errorCode.message)

 

사용 예

throw CustomException(ErrorCode.INVALID_COORDINATE)​

 

GlobalExceptionHandler

@ExceptionHandler(CustomException::class)
fun handleCustomException(e: CustomException): ResponseEntity<ErrorResponse> {
    val error = e.errorCode
    return ResponseEntity
        .status(error.status)
        .body(ErrorResponse(error.code, error.message))
}

 

장점

• 응답 포맷을 통일할 수 있어 프론트와 협업에 유리
• API 문서화 및 정합성 유지가 쉬움.
• 비즈니스 예외 추가도 Enum만 늘리면 끝!

단점

• 초기 세팅이 약간 귀찮음.
• 익숙하지 않으면 오히려 불편하다고 느껴질 수 있음.

 

---

 

상황	추천 방식
프로젝트가 작고 예외가 몇 개 없음	개별 Exception (직관적)
예외가 많아지고 응답 통일 필요	CustomException + ErrorCode 패턴
여러 팀/플랫폼과 협업	반드시 통합 방식 추천

 

---

예외 처리는 단순히 오류 메시지를 던지는 기능이 아니라, 서비스의 신뢰도와 사용자 경험을 좌우하는 중요한 부분이다.

• 예외의 의도를 분명히 하고
• 응답 포맷을 통일하며
• 유지보수가 쉬운 방향으로 선택하자!