Exception Handling Fundamentals

Exception handling neden gerekli?

Bir controller method’u çalışırken üç farklı hata türüyle karşılaşabiliriz. Kullanıcı yanlış veri gönderebilir, iş kuralı izin vermeyebilir ya da sistem beklenmeyen teknik bir problem yaşayabilir. Bunların hepsini aynı şekilde ele alırsak API tüketicisi için karanlık bir kutu oluşur.

@PostMapping("/transfers")
public ResponseEntity<?> transfer(@Valid @RequestBody TransferRequest request) {
    try {
        transferService.transfer(request);
        return ResponseEntity.status(HttpStatus.CREATED).build();
    } catch (InsufficientBalanceException ex) {
        return ResponseEntity.status(HttpStatus.CONFLICT)
            .body(Map.of("message", "Insufficient balance"));
    } catch (AccountNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(Map.of("message", "Account not found"));
    }
}

Bu kod çalışır ama büyüdükçe problem çıkarır. Her controller aynı try/catch bloklarını tekrarlar, hata response formatı controller’dan controller’a değişebilir ve teknik detayların dışarı sızma riski artar. Daha temiz olan yaklaşım, controller’ı sade tutup hata dönüşümünü merkezi hale getirmektir.

Spring MVC exception akışı nasıl işler?

Controller method’u exception fırlattığında Spring MVC request’i hemen kaybetmez. DispatcherServlet, oluşan exception’ı çözebilecek bir handler arar. Bu noktada devreye exception resolver zinciri girer.

Bu mekanizmanın önemli tarafı şudur: Hata oluştu diye response mutlaka 500 olmak zorunda değildir. Sen doğru exception tipini doğru handler ile eşlersen, iş kuralı hatalarını anlamlı status code ve body ile döndürebilirsin.

@RestControllerAdvice ve @ExceptionHandler

@RestControllerAdvice, REST controller’lar için global bir hata yakalama katmanı sağlar. Burada yazdığımız @ExceptionHandler method’ları, uygulamanın farklı controller’larından gelen exception’ları tek merkezde karşılar.

Bu yaklaşım controller’ları sadeleştirir. Controller sadece request’i alır, service’i çağırır ve başarılı response’u döner. İş kuralı ihlalinde service exception fırlatır; global handler bunu API cevabına çevirir.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(AccountNotFoundException.class)
    public ResponseEntity<ApiErrorResponse> handleAccountNotFound(
            AccountNotFoundException ex,
            HttpServletRequest request
    ) {
        ApiErrorResponse response = ApiErrorResponse.of(
            "ACCOUNT_NOT_FOUND",
            ex.getMessage(),
            request.getRequestURI()
        );

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
    }
}

Burada dikkat edilmesi gereken şey, handler method’unun sadece response üretmesidir. Business karar burada verilmez. “Hesap gerçekten var mı?” kararı service katmanındadır. Handler sadece “bu exception API’de nasıl temsil edilecek?” sorusuna cevap verir.

Business exception ile technical exception ayrımı

Business exception, beklenen ve domain tarafından anlamı olan hatadır. Kullanıcı hatalı bir işlem yapmış olabilir veya iş kuralı bu işleme izin vermiyor olabilir. Technical exception ise çoğu zaman beklenmeyen ve kullanıcıya detaylı açıklanmaması gereken sistem hatasıdır.

MiniBank için örnek hata kodları

Validation hatalarını özel ele almak

Bir önceki modülde request DTO ve validation ekledik. Şimdi bu validation hatalarının dışarı nasıl döneceğini standart hale getireceğiz. Çünkü validation hatasında sadece “Bad Request” demek çoğu zaman yetmez; hangi alanın neden hatalı olduğunu da söylemek gerekir.

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "path": "/api/v1/accounts",
  "fieldErrors": [
    {
      "field": "iban",
      "message": "IBAN boş olamaz"
    },
    {
      "field": "balance",
      "message": "Bakiye negatif olamaz"
    }
  ]
}

Bu format frontend ve mobil ekip için çok değerlidir. Çünkü kullanıcıya alan bazlı mesaj gösterebilirler. API tüketicisi sadece 400 status code’a bakmak zorunda kalmaz; response body üzerinden hangi input’u düzeltmesi gerektiğini bilir.

Standard error response modeli

Error contract tasarlarken temel amaç tutarlılıktır. Aynı uygulamada bazı hataların message, bazılarının error, bazılarının detail alanıyla dönmesi API tüketicisini yorar. MiniBank’ta tek bir standart response modeli kullanacağız.

public record ApiErrorResponse(
    String code,
    String message,
    String path,
    Instant timestamp,
    List<FieldErrorResponse> fieldErrors
) {
    public static ApiErrorResponse of(String code, String message, String path) {
        return new ApiErrorResponse(
            code,
            message,
            path,
            Instant.now(),
            List.of()
        );
    }

    public static ApiErrorResponse validation(
            String message,
            String path,
            List<FieldErrorResponse> fieldErrors
    ) {
        return new ApiErrorResponse(
            "VALIDATION_ERROR",
            message,
            path,
            Instant.now(),
            fieldErrors
        );
    }
}