예외 처리와 응답 표준화

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    // 업무 규칙 위반: 클라이언트가 상황을 고치면 해결됩니다
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusiness(BusinessException e) {
        log.warn("business error: code={}, message={}", e.getCode(), e.getMessage());
        return ResponseEntity
                .status(e.getStatus())
                .body(ErrorResponse.of(e.getCode(), e.getMessage()));
    }

    // 검증 실패: 어떤 필드가 왜 틀렸는지 돌려줍니다
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException e) {
        List<FieldError> errors = e.getBindingResult().getFieldErrors().stream()
                .map(error -> new FieldError(error.getField(), error.getDefaultMessage()))
                .toList();
        return ResponseEntity
                .badRequest()
                .body(ErrorResponse.of("INVALID_REQUEST", "요청 값이 올바르지 않습니다", errors));
    }

    // 최후의 안전망: 예상하지 못한 예외
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleUnexpected(Exception e) {
        log.error("unexpected error", e);
        return ResponseEntity
                .internalServerError()
                .body(ErrorResponse.of("INTERNAL_ERROR", "요청을 처리하지 못했습니다"));
    }
}

마지막 핸들러가 메시지를 고정 문구로 내보내는 점을 보세요. 예외 메시지를 그대로 전달하면 내부 구조가 노출됩니다.

// 자체 형식 예시
{
  "code": "ORDER_NOT_FOUND",
  "message": "주문을 찾을 수 없습니다",
  "traceId": "b3f1c2a4",
  "errors": []
}

// ProblemDetail 형식 예시
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "주문을 찾을 수 없습니다",
  "instance": "/api/orders/1024"
}

무엇을 고르든 code나 type처럼 기계가 분기할 수 있는 값을 반드시 포함합니다. message만 있으면 클라이언트가 문구를 비교하는 코드를 짜게 됩니다.