현업에서 자주 쓰는 백엔드 스킬들 (with JAVA)

현업에서 자주 쓰는 백엔드 스킬 — 예외 처리 제대로 하기. 컨트롤러마다 try-catch를 도배하고 있다면, API 에러 응답이 제각각일 가능성이 높다. 전역 예외 처리, 커스텀 예외 설계, 표준 에러 응답(ProblemDetail)까지 — 스프링에서 예외를 깔끔하게 다루는 법을 실제 코드로 정리한다.

---

들어가며

기능 개발에 쫓기다 보면 예외 처리는 늘 뒷전으로 밀린다. 그러나 예외 처리는 API 품질을 좌우하는 스킬이다. 잘못 던져진 500 에러 하나가 프론트엔드 개발을 멈추게 하고, 제각각인 에러 응답 형식이 클라이언트 코드를 지저분하게 만든다.

가장 흔한 안티패턴은 컨트롤러마다 try-catch를 도배하는 것이다. 같은 코드가 중복되고, 응답 형식이 메서드마다 달라지고, 어딘가에서는 처리를 깜빡한다. 이걸 한 곳으로 모으는 게 이 글의 핵심이다.

좋은 예외 처리의 목표는 두 가지다. 하나, 예외 처리를 한 곳에 모아 중복을 없앤다. 둘, 모든 에러가 일관된 형식으로 응답되게 한다. 그래야 클라이언트가 에러를 예측 가능하게 다룰 수 있다.

이 글에서는 흩어진 try-catch의 문제부터, 스프링의 전역 예외 처리(@RestControllerAdvice), 비즈니스 예외를 타입으로 설계하는 법, 표준 에러 포맷인 ProblemDetail(RFC 9457), 그리고 검증 에러 처리까지 실제 코드로 본다. 예제는 Spring Boot 3.x 기준이다.

---

1. 왜 예외 처리 전략이 필요한가

먼저 안티패턴부터 보자. 컨트롤러마다 이렇게 try-catch로 감싸는 코드다.

// 나쁜 예: 컨트롤러마다 try-catch — 중복되고, 응답 형식도 제각각이다
@GetMapping("/users/{id}")
public ResponseEntity<?> getUser(@PathVariable Long id) {
    try {
        User user = userService.findById(id);
        return ResponseEntity.ok(user);
    } catch (UserNotFoundException e) {
        return ResponseEntity.status(404).body(Map.of("error", "사용자 없음"));
    } catch (Exception e) {
        return ResponseEntity.status(500).body(Map.of("message", "서버 오류"));
    }
}

문제가 한둘이 아니다. 이 try-catch가 모든 컨트롤러 메서드에 반복되고, 어떤 곳은 error, 어떤 곳은 message 키를 쓰며 응답 형식이 제각각이다. 새 메서드에서 catch를 빠뜨리면 그대로 500이 노출된다.

해법은 예외 처리를 컨트롤러에서 걷어내 한 곳으로 모으는 것이다. 그러면 컨트롤러는 정상 흐름에만 집중하고, 예외는 그냥 던지면 된다.

---

2. 예외가 던져지면 무슨 일이 일어나는가

스프링에서 컨트롤러나 서비스가 예외를 던지면, 그 예외는 호출 스택을 타고 위로 전파된다. 아무도 잡지 않으면 스프링의 기본 처리기가 받아서 처리하는데, 이때 나오는 게 그 유명한 Whitelabel 에러 페이지나 밋밋한 기본 JSON이다.

{ "timestamp": "...", "status": 500, "error": "Internal Server Error", "path": "/api/users/42" }

이 기본 응답은 두 가지가 아쉽다. 어떤 비즈니스적 이유로 실패했는지 알 수 없고, 형식을 우리가 통제할 수 없다. 그래서 예외를 우리가 원하는 지점에서 가로채 원하는 형식으로 바꿔주는 장치가 필요하다. 그게 다음의 @RestControllerAdvice다.

---

3. 전역 예외 처리 — @RestControllerAdvice

@RestControllerAdvice는 모든 컨트롤러에서 발생한 예외를 한 곳에서 처리하게 해주는 스프링의 핵심 도구다. @ExceptionHandler로 "이 예외는 이렇게 응답하라"를 선언한다.

@Slf4j
@RestControllerAdvice   // 모든 컨트롤러의 예외를 여기서 가로챈다
public class GlobalExceptionHandler {

    // 특정 비즈니스 예외 처리
    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(UserNotFoundException e) {
        return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(new ErrorResponse("USER_NOT_FOUND", e.getMessage()));
    }

    // 예상하지 못한 모든 예외의 '최후 방어선'
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleUnexpected(Exception e) {
        log.error("처리되지 않은 예외 발생", e);   // 5xx는 반드시 로깅
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ErrorResponse("INTERNAL_ERROR", "서버 오류가 발생했습니다"));
    }
}

이제 컨트롤러는 이렇게 깔끔해진다. 예외는 잡지 않고 그냥 던지면 위의 핸들러가 알아서 처리한다.

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.findById(id);   // try-catch 없이, 예외는 그냥 전파
}

 

예외가 서비스 깊은 곳에서 던져져도, 스택을 타고 올라와 @RestControllerAdvice가 한 번에 잡는다. 처리 로직이 한 곳에 모여 중복이 사라지고 형식이 통일된다.

---

4. 커스텀 예외 설계 — 비즈니스 규칙을 타입으로

예외 종류가 늘어날 때마다 핸들러를 하나씩 추가하면 그것대로 번거롭다. 더 나은 방법은 에러를 코드로 정의하고, 공통 예외 하나로 묶는 것이다. 먼저 에러 코드를 enum으로 정의한다.

@Getter
@RequiredArgsConstructor
public enum ErrorCode {
    USER_NOT_FOUND(HttpStatus.NOT_FOUND, "사용자를 찾을 수 없습니다"),
    DUPLICATE_EMAIL(HttpStatus.CONFLICT, "이미 사용 중인 이메일입니다"),
    INVALID_INPUT(HttpStatus.BAD_REQUEST, "잘못된 요청입니다");

    private final HttpStatus status;   // 각 에러가 어떤 HTTP 상태인지
    private final String message;
}

그리고 이 코드를 담는 공통 비즈니스 예외를 만든다.

@Getter
public class BusinessException extends RuntimeException {
    private final ErrorCode errorCode;

    public BusinessException(ErrorCode errorCode) {
        super(errorCode.getMessage());
        this.errorCode = errorCode;
    }
}

이제 서비스에서는 상황에 맞는 에러 코드로 예외를 던지기만 하면 된다.

public User findById(Long id) {
    return userRepository.findById(id)
        .orElseThrow(() -> new BusinessException(ErrorCode.USER_NOT_FOUND));
}

핸들러도 단 하나면 충분하다. BusinessException 하나만 처리하면 모든 비즈니스 예외가 커버된다.

@ExceptionHandler(BusinessException.class)
public ResponseEntity<ErrorResponse> handleBusiness(BusinessException e) {
    ErrorCode code = e.getErrorCode();
    return ResponseEntity
        .status(code.getStatus())
        .body(new ErrorResponse(code.name(), code.getMessage()));
}

에러의 종류(HTTP 상태 + 메시지)가 enum 한 곳에 모여 관리되니, 새 에러를 추가할 때 enum에 한 줄만 더하면 된다. 어떤 상황에 어떤 HTTP 상태 코드를 쓸지도 여기서 일관되게 정해진다.

---

5. 일관된 에러 응답 — ProblemDetail (RFC 9457)

에러 응답 형식을 직접 만들어도 되지만, 사실 표준이 있다. RFC 9457(Problem Details for HTTP APIs)은 API 에러 응답의 공통 포맷을 정의하고, Spring 6(부트 3)부터 ProblemDetail로 기본 지원한다. 직접 만든 ErrorResponse 대신 이걸 쓰면 표준을 따르면서 코드도 준다.

@ExceptionHandler(BusinessException.class)
public ProblemDetail handleBusiness(BusinessException e) {
    ErrorCode code = e.getErrorCode();

    // status와 detail로 표준 에러 바디 생성
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(
        code.getStatus(), code.getMessage());
    problem.setTitle(code.name());
    problem.setProperty("errorCode", code.name());   // 표준 외 커스텀 필드 추가

    return problem;
}

응답은 이렇게, 표준 형식으로 나간다. Content-Type도 자동으로 application/problem+json이 된다.

{
  "type": "about:blank",
  "title": "USER_NOT_FOUND",
  "status": 404,
  "detail": "사용자를 찾을 수 없습니다",
  "instance": "/api/users/42",
  "errorCode": "USER_NOT_FOUND"
}

 

type·title·status·detail·instance가 표준 필드이고, setProperty로 errorCode 같은 커스텀 필드를 얹을 수 있다. 클라이언트는 이제 어떤 API를 호출하든 같은 구조로 에러를 파싱하면 된다. 참고로 application.properties에 spring.mvc.problemdetails.enabled=true만 켜도 스프링의 기본 예외들이 이 포맷으로 응답된다.

---

6. 검증 에러 처리 — @Valid

또 하나 자주 마주치는 게 입력 검증이다. 요청 DTO에 검증 애너테이션을 붙이고 @Valid를 걸면, 스프링이 자동으로 검증하고 실패 시 예외를 던진다.

public record SignupRequest(
    @NotBlank(message = "이름은 필수입니다")
    String name,

    @Email(message = "올바른 이메일 형식이 아닙니다")
    String email,

    @Min(value = 1, message = "나이는 1 이상이어야 합니다")
    int age
) {}

@PostMapping("/users")
public User signup(@Valid @RequestBody SignupRequest request) {
    return userService.signup(request);   // 검증 통과한 값만 여기 도달
}

검증에 실패하면 MethodArgumentNotValidException이 던져진다. 이걸 전역 핸들러에서 잡아, 어떤 필드가 왜 틀렸는지 담아 응답한다.

@ExceptionHandler(MethodArgumentNotValidException.class)
public ProblemDetail handleValidation(MethodArgumentNotValidException e) {
    ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
    problem.setTitle("VALIDATION_FAILED");

    // 필드별 에러 메시지를 모아서 담는다
    Map<String, String> errors = new HashMap<>();
    e.getBindingResult().getFieldErrors().forEach(err ->
        errors.put(err.getField(), err.getDefaultMessage()));
    problem.setProperty("errors", errors);

    return problem;
}

이제 잘못된 입력에는 "어느 필드가 어떻게 틀렸는지"가 친절하게 응답되어, 프론트엔드가 폼 에러를 바로 표시할 수 있다.

---

7. 실무 팁 정리

마지막으로, 예외 처리에서 흔히 놓치는 것들이다.

• 4xx와 5xx를 명확히 구분하라. 클라이언트 잘못(잘못된 입력, 없는 리소스)은 4xx, 서버 잘못(버그, 외부 연동 실패)은 5xx다. 이 구분이 HTTP 상태 코드를 제대로 쓰는 출발점이다.
• 5xx는 로깅하고, 4xx는 대개 하지 마라. 5xx는 우리가 고쳐야 할 문제라 스택 트레이스를 남겨야 한다. 반면 4xx(사용자의 잘못된 요청)까지 error 레벨로 로깅하면 로그가 노이즈로 가득 찬다.
• 에러 응답에 민감 정보를 노출하지 마라. 스택 트레이스, 내부 경로, SQL 등이 응답 바디에 섞여 나가면 보안 취약점이 된다. 상세 원인은 로그에만 남기고, 클라이언트에는 안전한 메시지만 준다.
• 예외를 흐름 제어로 남용하지 마라. "값이 없으면 예외"가 항상 옳은 건 아니다. 정상적으로 있을 수 있는 부재(빈 목록 등)는 예외가 아니라 정상 반환으로 다루는 게 맞다.
• @Transactional 롤백 규칙에 주의하라. 스프링은 기본적으로 RuntimeException에만 롤백한다. 커스텀 예외를 RuntimeException 기반으로 만든 이유이기도 하다(트랜잭션 전파 참고).

---

마치며

예외 처리는 "에러가 났을 때 대충 막는" 방어가 아니라, API가 실패를 일관되고 예측 가능하게 표현하는 설계다. 컨트롤러의 try-catch를 걷어내 @RestControllerAdvice로 모으고, 비즈니스 예외를 에러 코드로 타입화하고, 응답을 ProblemDetail 표준으로 통일하면, 에러 처리 코드가 극적으로 단순해지면서 품질은 올라간다.

핵심만 다시 짚으면, 예외는 던지고, 처리는 한 곳에 모으고, 응답은 표준 형식으로 통일한다. 이 세 가지만 지켜도 "컨트롤러마다 try-catch"의 지옥에서 벗어날 수 있다. 그리고 일관된 에러 응답은 백엔드만의 이득이 아니라, 그 API를 쓰는 프론트엔드와 다른 서비스 모두의 이득이다.

---

참고 출처

• Spring Framework — Error Responses (ProblemDetail, RFC 9457) — https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
• Spring Framework — Bean Validation — https://docs.spring.io/spring-framework/reference/core/validation/beanvalidation.html
• Baeldung — Error Handling for REST with Spring — https://www.baeldung.com/exception-handling-for-rest-with-spring
• RFC 9457 — Problem Details for HTTP APIs — https://www.rfc-editor.org/rfc/rfc9457