스프링 서비스의 에러 처리 전략

BusinessError  -> Result로 값 처리, 호출자가 반드시 처리
InfraException -> 예외로 throw, 공통 핸들러가 일괄 처리
Unknown        -> 예외로 throw, fallback 핸들러

interface ResultError {
    val code: String
    val msg: String
}

interface BusinessError : ResultError

data class CustomerNotFoundError(
    override val code: String = "CUSTOMER_NOT_FOUND",
    override val msg: String = "고객 정보를 찾을 수 없습니다.",
) : BusinessError

data class OrderNotReadyError(
    val orderStatus: String,
    override val code: String = "ORDER_NOT_READY",
    override val msg: String = "주문 가능한 상태가 아닙니다: $orderStatus",
) : BusinessError

open class InfraException(
    message: String,
    override val code: String = "INFRA_ERROR",
    open val module: String = "unknown",
    open val retryable: Boolean = false,
    open val retryAfterSeconds: Long? = null,
) : RuntimeException(message), ResultError {
    override val msg: String get() = message ?: "인프라 오류"
}

// 주문 도메인의 인프라 예외 계층
open class PaymentExecutionException(
    message: String,
    override val code: String = "PAYMENT_EXECUTION_ERROR",
    retryable: Boolean = false,
    retryAfterSeconds: Long? = null,
) : InfraException(message, module = "payment", retryable = retryable, retryAfterSeconds = retryAfterSeconds)

class PaymentGatewayException(message: String = "PG사 통신 중 오류가 발생했습니다.") :
    PaymentExecutionException(message, code = "PAYMENT_GATEWAY_ERROR", retryable = true, retryAfterSeconds = 30)

class InventoryException(message: String = "재고 시스템 오류가 발생했습니다.") :
    PaymentExecutionException(message, code = "INVENTORY_ERROR")

class PaymentLogicException(message: String = "결제 데이터 처리 중 오류가 발생했습니다.") :
    PaymentExecutionException(message, code = "PAYMENT_LOGIC_ERROR")

sealed class Result<out E : ResultError, out T> {
    data class Success<out T>(val value: T) : Result<Nothing, T>()
    data class Failure<out E : ResultError>(val error: E) : Result<E, Nothing>()
}

// 성공 값 변환 — Failure면 스킵
inline fun <E : ResultError, T, R> Result<E, T>.map(transform: (T) -> R): Result<E, R>

// 다음 Result 연산 체이닝 — Failure면 스킵
inline fun <E : ResultError, T, R> Result<E, T>.flatMap(transform: (T) -> Result<E, R>): Result<E, R>

// 실패 시 복구 시도
inline fun <E : ResultError, T> Result<E, T>.recoverWith(recover: (E) -> Result<E, T>): Result<E, T>

Success(customer) -> map -> flatMap -> Success(결과)
Failure(에러)     -> map -> flatMap -> Failure(에러)  ← 중간 연산 스킵

fun <E : ResultError, T> resultOf(block: ResultScope<E>.() -> T): Result<E, T>

class ResultScope<E : ResultError> {
    fun ensure(condition: Boolean, error: () -> E)              // 조건 실패 -> Failure
    fun <T : Any> ensureNotNull(value: T?, error: () -> E): T  // null -> Failure
}

public void placeOrder(PlaceOrderRequest request) {
    // 1. null 비교 + return
    Customer customer = customerClient.getCustomer(customerId);
    if (customer == null) return;

    // 2. boolean 상태 비교 + return
    OrderProgress progress = getProgress(orderId);
    if (!progress.isOrderable()) return;

    // 3. boolean 설정 비교 + return
    if (!orderAcceptable) return;

    // 4. 빈 컬렉션 비교 + return
    List<OrderItem> items = getItems(orderId);
    if (items.isEmpty()) return;

    // 5. 예외 전파 (try-catch 없음)
    paymentClient.requestPayment(orderId, items);
}

public OrderCompletedEvent placeOrder(PlaceOrderRequest request) {
    Customer customer = customerClient.getCustomer(customerId);
    if (customer == null) throw new CustomerNotFoundException();
    if (!customer.isActive()) throw new CustomerNotActiveException();

    OrderProgress progress = getProgress(orderId);
    if (!progress.isOrderable()) throw new OrderNotReadyException(progress.getStatus());

    if (!orderAcceptable) throw new FeatureDisabledException("신규 주문 접수");

    List<OrderItem> items = getItems(orderId);
    if (items.isEmpty()) throw new EmptyCartException();

    paymentClient.requestPayment(orderId, items);
    return new OrderCompletedEvent(customerId, orderId, items.size());
}

@Service
class OrderService(
    private val customerQueryPort: CustomerQueryPort,
    private val orderStatusQueryPort: OrderStatusQueryPort,
    private val orderItemQueryPort: OrderItemQueryPort,
    private val paymentExecutionPort: PaymentExecutionPort,
    @param:Value("\${order.auto-order-enabled:true}")
    private val orderAcceptable: Boolean = true,
) {

    fun placeOrder(request: PlaceOrderRequest): Result<BusinessError, OrderCompletedEvent> = resultOf {
        // 1. 고객 검증
        val customer = ensureNotNull(
            customerQueryPort.getCustomer(request.customerId)
        ) { CustomerNotFoundError() }
        ensure(customer.isActive) { CustomerNotFoundError() }

        // 2. 주문 상태 확인
        val progress = orderStatusQueryPort.getProgress(request.orderId)
        ensure(progress.isOrderable) { OrderNotReadyError(progress.status.name) }

        // 3. 기능 활성화 확인
        ensure(orderAcceptable) { FeatureDisabledError("신규 주문 접수") }

        // 4. 주문 상품 조회
        val items = orderItemQueryPort.getItems(request.orderId)
        ensure(items.isNotEmpty()) { EmptyCartError() }

        // 5. 결제 실행
        paymentExecutionPort.execute(request.orderId, items)
            .retry(PaymentGatewayException::class, maxRetries = 3) {
                paymentExecutionPort.execute(request.orderId, items)
            }
            .recover(InventoryException::class) { cachedResult(request.orderId) }
            .getOrThrow()

        OrderCompletedEvent(
            customerId = request.customerId,
            orderId = request.orderId,
            itemCount = items.size,
        )
    }
}

getCustomer(id).flatMap(customer ->
    getProgress(orderId).flatMap(progress ->
        getItems(orderId).flatMap(items ->
            // 깊어짐...
        )
    )
);

Customer getCustomer(...) throws CustomerNotFoundException;
// 호출자가 try-catch를 강제당함 — 실패 시그니처 명시라는 목적은 Result와 동일

Response<Customer> response = getCustomer(id);
if (response.getError() != null) { return Response.error(response.getError()); }
// error 체크를 안 해도 컴파일 됨 — response.getData()가 null일 수 있음

object PaymentExceptionClassifier {
    fun classify(e: Exception): PaymentExecutionException = when (e) {
        is PgApiException -> PaymentGatewayException("PG사 통신 오류: ${e.message}")
        is InventorySystemException -> InventoryException("재고 시스템 오류: ${e.message}")
        else -> InventoryException("결제 모듈 알 수 없는 오류: ${e.message}")
    }
}

@Component
class PaymentExecutionAdapter(
    private val paymentClient: PaymentClient,
) : PaymentExecutionPort {

    override fun execute(orderId: OrderId, items: List<OrderItem>): Result<PaymentExecutionException, Unit> {
        return try {
            paymentClient.requestPayment(orderId.value, items.map { it.productName })
            Unit.asSuccess()
        } catch (e: Exception) {
            PaymentExceptionClassifier.classify(e).asFailure()
        }
    }
}

fun <T> Result<BusinessError, T>.toResponseEntity(): ResponseEntity<Any> = when (this) {
    is Result.Success -> ResponseEntity.ok(value)
    is Result.Failure -> {
        log.warn("[BUSINESS] {}: {}", error.code, error.msg)
        ResponseEntity.status(HttpStatus.BAD_REQUEST).body(
            ErrorResponse(error = error.code, message = error.msg)
        )
    }
}

@RestControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(InfraException::class)
    fun handleInfraException(ex: InfraException): ResponseEntity<ErrorResponse> {
        logWithModule(ex.module, ex)

        val status = if (ex.retryable) HttpStatus.SERVICE_UNAVAILABLE
                     else HttpStatus.INTERNAL_SERVER_ERROR
        val headers = HttpHeaders()
        if (ex.retryable) {
            ex.retryAfterSeconds?.let { headers.set("Retry-After", it.toString()) }
        }

        return ResponseEntity.status(status).headers(headers).body(
            ErrorResponse(error = ex.code, module = ex.module, message = ex.message ?: "인프라 오류가 발생했습니다.")
        )
    }

    @ExceptionHandler(Exception::class)
    fun handleUnexpectedException(ex: Exception): ResponseEntity<ErrorResponse> {
        logWithModule("unknown", ex)
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(
            ErrorResponse(error = "UNKNOWN_ERROR", module = "unknown", message = "예상하지 못한 오류가 발생했습니다.")
        )
    }
}

@RestController
@RequestMapping("/api/orders")
class OrderController(
    private val orderService: OrderService,
    private val orderAlertPolicy: OrderAlertPolicy,
) {

    @PostMapping("/place")
    fun placeOrder(@RequestBody request: PlaceOrderRequest): ResponseEntity<Any> {
        return orderService.placeOrder(request)
            .onFailure { orderAlertPolicy.alertIfNeeded(it) }
            .toResponseEntity()
    }
}

{
  "error": "PAYMENT_GATEWAY_ERROR",
  "module": "payment",
  "message": "PG사 통신 중 오류가 발생했습니다."
}

클라이언트 -> API Gateway -> 주문 서비스 -> 결제 서비스 -> PG사

PG사 API timeout
  -> PaymentClient: PgApiException 발생
  -> PaymentExceptionClassifier: PaymentGatewayException(module="payment", retryable=true)으로 분류
  -> PaymentExecutionAdapter: Result.Failure로 변환
  -> OrderService: retry 3회 시도 -> 여전히 실패 -> getOrThrow()로 예외 전파
  -> GlobalExceptionHandler: 503 + Retry-After: 30 + module="payment" 응답
  -> 호출자: module로 원인 식별, Retry-After로 재시도 판단

@ApiErrors([
    CustomerNotFoundError::class,    // BusinessError -> 400
    OrderNotReadyError::class,       // BusinessError -> 400
    FeatureDisabledError::class,     // BusinessError -> 400
    EmptyCartError::class,           // BusinessError -> 400
    PaymentGatewayException::class,  // InfraException(retryable) -> 503
    InventoryException::class,       // InfraException -> 500
    PaymentLogicException::class,    // InfraException -> 500
])
@PostMapping("/place")
fun placeOrder(@RequestBody request: PlaceOrderRequest): ResponseEntity<Any>

private fun logWithModule(module: String, ex: Exception) {
    MDC.put("errorModule", module)
    try {
        log.error("[{}] {}", module, ex.message, ex)
    } finally {
        MDC.remove("errorModule")
    }
}

sealed interface BusinessError : ResultError

data class CustomerNotFoundError(...) : BusinessError
data class OrderNotReadyError(...) : BusinessError
data class FeatureDisabledError(...) : BusinessError
data class EmptyCartError(...) : BusinessError

@Component
class OrderAlertPolicy(
    private val alertPublisher: AlertPublisher,
) {

    fun alertIfNeeded(error: BusinessError) {
        when (error) {
            is EmptyCartError -> alertPublisher.send("[WARN] ${error.msg}")
            is OrderNotReadyError -> alertPublisher.send("[WARN] ${error.msg}")
            is CustomerNotFoundError -> { }  // 알림 불필요
            is FeatureDisabledError -> { }   // 알림 불필요
        }
        // else 없음 -> 새 에러 타입이 추가되면 컴파일 에러
    }
}