Spring MVC’de İstisna Yönetimi: @ControllerAdvice, @ExceptionHandler ve HandlerExceptionResolver

Spring MVC’de İstisna Yönetimi: @ControllerAdvice, @ExceptionHandler ve HandlerExceptionResolver

Giriş

Modern web uygulamaları, kullanıcılarla etkileşim kurarken ve karmaşık iş mantığını yürütürken çeşitli hata ve istisna durumlarıyla karşılaşabilir. Bu durumlar, beklenmedik veri girişlerinden, ağ sorunlarına, veritabanı bağlantı hatalarına veya iş kurallarının ihlallerine kadar geniş bir yelpazeyi kapsar. Bir uygulamanın sağlamlığı ve kullanıcı deneyimi, bu istisnaların ne kadar etkili bir şekilde yönetildiğine bağlıdır. Spring MVC, bu tür senaryoları ele almak için güçlü ve esnek mekanizmalar sunar. Doğru istisna yönetimi stratejileri uygulamak, uygulamanızın daha güvenilir, bakımı daha kolay ve kullanıcı dostu olmasını sağlar.

Bu makalede, Spring MVC ekosisteminde istisna yönetiminin temel taşları olan @ExceptionHandler anotasyonu, @ControllerAdvice anotasyonu ve HandlerExceptionResolver arayüzünü derinlemesine inceleyeceğiz. Her bir yaklaşımın ne zaman kullanılacağını, avantajlarını ve dezavantajlarını örnek kodlarla açıklayacak, böylece geliştiricilerin uygulamalarında en uygun stratejiyi seçmelerine yardımcı olacağız. Amacımız, Spring MVC’deki istisna yönetiminin farklı katmanlarını ve bu katmanların nasıl bir araya gelerek kapsamlı bir hata işleme çözümü sunduğunu net bir şekilde ortaya koymaktır.

Temel İstisna Yönetimi Kavramları

İstisna yönetimine dalmadan önce, Java’daki temel istisna kavramlarını ve web uygulamalarında istisna yönetiminin neden bu kadar kritik olduğunu anlamak önemlidir.

Java’da İstisnalar ve Hatalar

Java’da istisnalar (exceptions) ve hatalar (errors), programın normal akışını bozan olayları temsil eder. Throwable sınıfı, tüm istisna ve hata sınıflarının süper sınıfıdır.
* Hatalar (Errors): Genellikle uygulamanın kontrolü dışındaki ciddi sorunları (örn: OutOfMemoryError, StackOverflowError) temsil eder. Bu tür durumlarda, uygulamayı kurtarmak genellikle mümkün değildir ve JVM’in kapanması gerekebilir. Geliştiricilerin doğrudan yakalayıp işlemeye çalıştığı durumlar değildir.
* İstisnalar (Exceptions): Uygulamanın çalışması sırasında meydana gelen ancak genellikle yakalanıp işlenebilecek sorunları temsil eder. İstisnalar iki ana kategoriye ayrılır:
* Kontrol Edilen İstisnalar (Checked Exceptions): Exception sınıfından türeyen ancak RuntimeException sınıfından türemeyen istisnalardır. Derleme zamanında kontrol edilirler ve metot imzalarında throws anahtar kelimesiyle belirtilmeli veya try-catch bloğu ile yakalanmalıdır. Örnek: IOException, SQLException.
* Kontrol Edilmeyen İstisnalar (Unchecked Exceptions) veya Çalışma Zamanı İstisnaları (Runtime Exceptions): RuntimeException sınıfından türeyen istisnalardır. Derleme zamanında kontrol edilmezler ve metot imzasında belirtilmesi zorunlu değildir. Genellikle programcı hatalarını (örn: NullPointerException, ArrayIndexOutOfBoundsException, IllegalArgumentException) veya kurtarılamayacak mantıksal hataları gösterirler. Spring MVC genellikle bu tür istisnalarla daha sık karşılaşır.

Web Uygulamalarında İstisna Yönetiminin Önemi

Web uygulamalarında istisna yönetimi sadece teknik bir gereklilik değil, aynı zamanda kullanıcı deneyimi, güvenlik ve uygulama bakımı açısından da hayati öneme sahiptir.
* Kullanıcı Deneyimi: Beklenmedik bir hata durumunda, kullanıcıya anlamsız bir yığın izi (stack trace) göstermek yerine, anlaşılır ve yardımcı bir hata mesajı sunmak, uygulamanın profesyonel algısını artırır. Hatta bazen kullanıcıyı hatanın nasıl düzeltileceği konusunda yönlendirmek mümkündür.
* Güvenlik: Yığın izleri veya ayrıntılı hata mesajları, saldırganlara uygulamanızın iç yapısı, kullanılan kütüphaneler veya veritabanı şeması hakkında hassas bilgiler sağlayabilir. Doğru istisna yönetimi, bu tür bilgilerin açığa çıkmasını engeller.
* Bakım Kolaylığı: Merkezi bir istisna yönetim mekanizması, hataların tek bir yerden ele alınmasını, loglanmasını ve izlenmesini sağlar. Bu, sorun giderme ve hata ayıklama süreçlerini önemli ölçüde hızlandırır.
* API Tutarlılığı: RESTful API’lar geliştirirken, hata yanıtlarının tutarlı bir formatta (örn: JSON) ve anlamlı HTTP durum kodlarıyla (örn: 400 Bad Request, 404 Not Found, 500 Internal Server Error) dönmesi, API’yi kullanan istemcilerin (frontend uygulamaları, mobil uygulamalar) hataları kolayca işlemesini sağlar.

Spring MVC’de İstisna Yönetimine Genel Bakış

Spring MVC, istisna yönetimi için çeşitli seviyelerde ve esnekliklerde mekanizmalar sunar. Bu mekanizmalar, basit, controller’a özgü hata işleminden, tüm uygulama genelinde geçerli olacak karmaşık ve merkezi çözümlere kadar değişir. Spring’in bu konudaki felsefesi, geliştiricilere ihtiyaçlarına en uygun aracı sağlamaktır.
* Controller Seviyesi: @ExceptionHandler anotasyonu ile belirli bir controller içindeki metotlar tarafından fırlatılan istisnaları yakalamak.
* Global Seviye: @ControllerAdvice anotasyonu ile @ExceptionHandler‘ı birleştirerek tüm uygulama genelindeki controller’lar için merkezi bir istisna yönetim katmanı oluşturmak.
* Düşük Seviye/Programatik: HandlerExceptionResolver arayüzünü implemente ederek Spring’in istisna çözümleme mekanizmasına tam kontrolle müdahale etmek. Bu, Spring’in kendi iç istisna çözücülerinin (örn: DefaultHandlerExceptionResolver, SimpleMappingExceptionResolver) temelidir.

Bu yaklaşımların her birini detaylı olarak inceleyelim.

@ExceptionHandler Anotasyonu

@ExceptionHandler anotasyonu, Spring MVC’de istisna yönetiminin en temel ve doğrudan yoludur. Belirli bir controller içinde fırlatılan istisnaları yakalamak ve işlemek için kullanılır.

Controller Seviyesinde İstisna Yönetimi

Bir Controller sınıfı içinde bir metodu @ExceptionHandler ile işaretlediğinizde, bu metot sadece o controller içindeki diğer metotlar tarafından fırlatılan belirtilen istisna türlerini yakalar. Bu, belirli bir controller’ın kendi özel hata işleme mantığına sahip olması gerektiğinde kullanışlıdır.

Nasıl Çalışır:
1. Bir client bir HTTP isteği gönderir.
2. Spring MVC, isteği ilgili controller metoduna yönlendirir.
3. Controller metodu çalışırken bir istisna fırlatır.
4. Spring, aynı controller içinde bu istisna türünü veya onun bir süper sınıfını yakalamak için @ExceptionHandler ile işaretlenmiş bir metot olup olmadığını kontrol eder.
5. Eğer uygun bir metot bulunursa, Spring bu metodu çağırır ve istisnayı ona iletir.
6. @ExceptionHandler metodu, istisnayı işler ve uygun bir yanıt (örn: hata mesajı, HTTP durum kodu) döndürür.

Avantajları:
* Basitlik: Belirli bir controller’a özgü istisnaları yönetmek için kolay ve anlaşılır bir yol sunar.
* Özgünlük: Her controller, kendi özel istisna işleme mantığına sahip olabilir.

Dezavantajları:
* Tekrar: Eğer birden fazla controller aynı istisna türünü aynı şekilde ele alması gerekiyorsa, @ExceptionHandler kodunu her controller’a kopyalamak zorunda kalırsınız. Bu, kod tekrarına (DRY – Don’t Repeat Yourself prensibinin ihlali) yol açar ve bakımı zorlaştırır.
* Genelleştirilemez: Uygulama genelindeki istisnaları tek bir noktadan yönetmek için uygun değildir.

Birden Fazla İstisna Türünü Yakalama

Bir @ExceptionHandler metodu, tek bir istisna türünü veya bir istisna dizisini yakalayabilir. Bu, value veya exception özniteliği kullanılarak belirtilir.

@ExceptionHandler({ MyCustomException.class, AnotherCustomException.class })
public ResponseEntity handleMultipleExceptions(Exception ex) {
    // İstisnayı işle ve yanıt döndür
    return new ResponseEntity<>("Birden fazla istisna türü yakalandı: " + ex.getMessage(), HttpStatus.BAD_REQUEST);
}

Örnek Kod

Aşağıdaki örnek, bir ProductController içinde ProductNotFoundException istisnasını nasıl yakalayacağınızı gösterir:

package com.example.demo.controller;

import com.example.demo.exception.ProductNotFoundException;
import com.example.demo.model.Product;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;
import java.util.Optional;

@RestController
@RequestMapping("/products")
public class ProductController {

    private List products = new ArrayList<>();

    public ProductController() {
        products.add(new Product(1L, "Laptop", 1200.0));
        products.add(new Product(2L, "Mouse", 25.0));
    }

    @GetMapping("/{id}")
    public ResponseEntity getProductById(@PathVariable Long id) {
        Optional product = products.stream()
                .filter(p -> p.getId().equals(id))
                .findFirst();

        if (product.isPresent()) {
            return ResponseEntity.ok(product.get());
        } else {
            throw new ProductNotFoundException("ID " + id + " ile ürün bulunamadı.");
        }
    }

    // Bu controller'a özgü ProductNotFoundException'ı yakalayan metot
    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity handleProductNotFoundException(ProductNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }

    // Genel bir istisnayı yakalayan metot (daha spesifik olanlar önce yakalanır)
    @ExceptionHandler(Exception.class)
    public ResponseEntity handleGenericException(Exception ex) {
        return new ResponseEntity<>("Bir hata oluştu: " + ex.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

// Product.java
package com.example.demo.model;

public class Product {
    private Long id;
    private String name;
    private double price;

    public Product(Long id, String name, double price) {
        this.id = id;
        this.name = name;
        this.price = price;
    }

    // Getters and setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public double getPrice() { return price; }
    public void setPrice(double price) { this.price = price; }
}

// ProductNotFoundException.java
package com.example.demo.exception;

public class ProductNotFoundException extends RuntimeException {
    public ProductNotFoundException(String message) {
        super(message);
    }
}

Yukarıdaki örnekte, /products/3 adresine yapılan bir istek, ProductNotFoundException fırlatacak ve bu istisna handleProductNotFoundException metodu tarafından yakalanarak 404 NOT FOUND durum koduyla bir yanıt dönecektir.

@ControllerAdvice Anotasyonu

@ExceptionHandler anotasyonunun controller seviyesindeki sınırlamalarını aşmak ve uygulama genelinde merkezi bir istisna yönetim mekanizması oluşturmak için Spring, @ControllerAdvice anotasyonunu sunar.

Global İstisna Yönetimi Çözümü

@ControllerAdvice anotasyonu, Spring’in bileşen taraması sırasında keşfedilen ve tüm uygulamadaki controller’lar için ortak özellikler (istisna yönetimi, veri bağlama, model öznitelikleri) tanımlayan bir sınıfı işaretlemek için kullanılır. Özellikle istisna yönetimi bağlamında, @ControllerAdvice ile işaretlenmiş bir sınıf içinde tanımlanan @ExceptionHandler metotları, tüm uygulama genelindeki controller’lar tarafından fırlatılan istisnaları yakalayabilir.

Nasıl Çalışır:
1. Bir @ControllerAdvice sınıfı oluşturulur.
2. Bu sınıfın içine, bir controller’daki gibi @ExceptionHandler ile işaretlenmiş metotlar tanımlanır.
3. Uygulamanın herhangi bir yerindeki bir controller metodu bir istisna fırlattığında, Spring önce o controller içindeki @ExceptionHandler‘ları arar.
4. Eğer controller içinde uygun bir işleyici bulunamazsa, Spring @ControllerAdvice ile işaretlenmiş sınıflardaki @ExceptionHandler metotlarını arar.
5. Uygun bir metot bulunursa, istisna o metot tarafından işlenir.

Avantajları:
* Merkezi Yönetim (DRY): Tüm uygulama genelindeki istisnaları tek bir yerden yönetmenizi sağlar, kod tekrarını önler.
* Temiz Kod: Controller’ların iş mantığı ve istisna işleme mantığı ayrı tutularak daha temiz ve okunaklı bir kod yapısı elde edilir.
* Tutarlılık: Tüm hata yanıtlarının aynı formatta ve HTTP durum kodlarıyla dönmesini sağlayarak API tutarlılığını artırır.
* Esneklik: Belirli istisna türleri için özel yanıtlar veya loglama mekanizmaları tanımlamak kolaydır.

@ExceptionHandler ile Birlikte Kullanımı

@ControllerAdvice tek başına istisna yönetimi yapmaz; @ExceptionHandler anotasyonlu metotları barındırmak için bir konteyner görevi görür. Bu, bir GlobalExceptionHandler sınıfı oluşturup içine çeşitli @ExceptionHandler metotları ekleyerek yapılır.

package com.example.demo.exception;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.context.request.WebRequest;

import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity handleProductNotFoundException(ProductNotFoundException ex, WebRequest request) {
        ErrorDetails errorDetails = new ErrorDetails(LocalDateTime.now(), ex.getMessage(), request.getDescription(false));
        return new ResponseEntity<>(errorDetails, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity handleIllegalArgumentException(IllegalArgumentException ex, WebRequest request) {
        ErrorDetails errorDetails = new ErrorDetails(LocalDateTime.now(), ex.getMessage(), request.getDescription(false));
        return new ResponseEntity<>(errorDetails, HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity