Java İle Bean Validation Kullanarak Form Doğrulama İşlemi Nasıl Yapılır?

Gereksinimler ve Proje Kurulumu

Bean Validation kullanabilmek için projenizde ilgili kütüphanelerin tanımlı olması gerekir. 2026 yılı standartlarında, Jakarta Validation API ve bunun bir uygulaması olan Hibernate Validator kullanılması önerilir. Eğer bir Spring Boot projesi üzerinde çalışıyorsanız, aşağıdaki bağımlılığı pom.xml dosyanıza eklemeniz yeterlidir.

    org.springframework.boot
    spring-boot-starter-validation

Bu bağımlılık, hem doğrulama API'sini hem de Hibernate Validator motorunu projenize dahil eder. Ayrıca, Java 17 veya daha güncel bir sürüm kullanmanız, performans ve güvenlik güncellemelerinden yararlanmanız açısından tavsiye edilir.

Model Sınıflarında Doğrulama Kurallarını Tanımlama

Doğrulama işleminin ilk adımı, veriyi taşıyan nesnelerin üzerine kısıtlamaları eklemektir. Örneğin, bir kullanıcı kayıt formu için UserDTO sınıfını ele alalım. Burada @NotNull, @Size ve @Email gibi standart anotasyonları kullanacağız.

import jakarta.validation.constraints.*;

public class UserDTO {

    @NotBlank(message = "Kullanıcı adı boş bırakılamaz")
    @Size(min = 3, max = 20, message = "Kullanıcı adı 3 ile 20 karakter arasında olmalıdır")
    private String username;

    @Email(message = "Geçerli bir e-posta adresi giriniz")
    @NotBlank(message = "E-posta alanı zorunludur")
    private String email;

    @Min(value = 18, message = "18 yaşından küçükler kayıt olamaz")
    private int age;

    // Getter ve Setter metotları...
}

Burada kullanılan @NotBlank, boş veya sadece boşluk içeren karakterleri engellerken, @Email anotasyonu basit bir regex ile e-posta formatını kontrol eder. Bu yaklaşımla, veritabanına hatalı veri gitmeden önce uygulamanın giriş katmanında engelleme yapmış olursunuz.

Controller Katmanında Doğrulamayı Tetikleme

Model üzerindeki kuralları tanımladıktan sonra, bu kuralların bir HTTP isteği geldiğinde çalışmasını sağlamamız gerekir. Spring Boot projelerinde @Valid anotasyonu bu işi üstlenir. Aşağıdaki örnekte, bir kayıt endpoint'inin nasıl korunacağı gösterilmiştir.

import org.springframework.web.bind.annotation.*;
import jakarta.validation.Valid;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping("/register")
    public ResponseEntity registerUser(@Valid @RequestBody UserDTO userDTO) {
        // Eğer doğrulama başarısız olursa, bu kısma hiç girilmez.
        return ResponseEntity.ok("Kullanıcı başarıyla kaydedildi.");
    }
}

@Valid anotasyonu, gelen JSON verisini UserDTO nesnesine dönüştürdüğü anda doğrulama kurallarını işletir. Eğer kurallardan biri ihlal edilirse, sistem otomatik olarak MethodArgumentNotValidException fırlatır.

Hata Yönetimi ve Global Exception Handler

Doğrulama hatalarını kullanıcıya anlamlı bir şekilde döndürmek, iyi bir kullanıcı deneyimi (UX) için şarttır. Bunun için @ControllerAdvice kullanarak tüm uygulamadaki hataları tek bir merkezden yönetebilirsiniz.

import org.springframework.web.bind.annotation.*;
import org.springframework.http.*;
import java.util.*;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map errors = new HashMap();
        ex.getBindingResult().getFieldErrors().forEach(error -> 
            errors.put(error.getField(), error.getDefaultMessage()));
        return new ResponseEntity(errors, HttpStatus.BAD_REQUEST);
    }
}

Bu yapı sayesinde, formda hata olduğunda kullanıcıya 400 Bad Request kodu ile birlikte hangi alanın neden hatalı olduğuna dair net bir JSON mesajı döner.

Bean Validation Yöntemlerinin Karşılaştırması

Aşağıdaki tablo, form doğrulama yöntemleri arasındaki farkları özetlemektedir:

Güvenlik ve Kritik Uyarılar

Dikkat: Bean Validation, uygulamanın giriş katmanında bir "doğrulama" (validation) mekanizmasıdır, ancak bir "güvenlik" (security) katmanı değildir. Veritabanı seviyesinde de mutlaka benzer kısıtlamaları (constraints) tanımlayın. Ayrıca, kullanıcıdan gelen verileri asla doğrudan SQL sorgularına eklemeyin; her zaman Prepared Statement veya ORM (Hibernate/JPA) kullanarak SQL Injection saldırılarına karşı önlem alın.

Sıkça Sorulan Sorular

Bean Validation ile özel hata mesajlarını nasıl özelleştirebilirim?

Anotasyonların içerisinde message parametresini kullanarak veya ValidationMessages.properties dosyası oluşturarak merkezi bir şekilde hata mesajlarını değiştirebilirsiniz.

@Valid ve @Validated arasındaki fark nedir?

@Valid standart Jakarta anotasyonudur. @Validated ise Spring'e özgü bir anotasyondur ve grup bazlı (grouping) doğrulamaları destekler.

Doğrulama kurallarını çalışma anında dinamik olarak değiştirebilir miyim?

Doğrudan anotasyonlar statiktir. Ancak, ConstraintValidator arayüzünü kullanarak kendi özel doğrulama mantığınızı (custom validator) yazabilir ve dinamik kurallar oluşturabilirsiniz.

Boş değerleri nasıl kontrol edebilirim?

@NotNull null değerleri, @NotEmpty boş koleksiyon veya dizeleri, @NotBlank ise boşluk haricinde karakter içermeyen metinleri kontrol eder.

Bean Validation performans kaybına neden olur mu?

Modern JVM'lerde Bean Validation kullanımı oldukça optimize edilmiştir. Küçük ve orta ölçekli projelerde performans etkisi ihmal edilebilir düzeydedir.

Özel Doğrulama Kuralları (Custom Constraint) Oluşturma

Standart Bean Validation anotasyonları (@NotNull, @Size, @Email vb.) çoğu senaryo için yeterli olsa da, bazen iş mantığına özel kurallar tanımlamanız gerekebilir. Örneğin, bir kullanıcı adı alanının sadece belirli bir formatta veya veritabanında daha önce kullanılmamış olması gibi özel bir kısıtlamaya ihtiyacınız olabilir.

Kendi anotasyonunuzu oluşturmak için iki temel bileşene ihtiyacınız vardır: Bir anotasyon arayüzü ve bu kuralı işleyecek bir ConstraintValidator sınıfı.

Adım Adım Özel Doğrulama Yazımı

Öncelikle, anotasyonumuzu tanımlayalım. Bu örnekte, belirli bir kelimeyi içermeyen alanları kontrol eden @NoForbiddenWord anotasyonunu tasarlayacağız.

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = ForbiddenWordValidator.class)
public @interface NoForbiddenWord {
    String message() default "Bu kelime yasaklıdır!";
    Class[] groups() default {};
    Class


Sonuç

Java ile Bean Validation kullanarak form doğrulama işlemi, uygulamanızın kalitesini ve güvenliğini artıran en temel pratiklerden biridir. Bu rehberde, model sınıflarınızı nasıl dekore edeceğinizi, @Valid ile doğrulamayı nasıl tetikleyeceğinizi ve hataları nasıl yöneteceğinizi adım adım inceledik. Bir sonraki adım olarak, karmaşık iş kurallarınız için @Constraint anotasyonu ile kendi özel doğrulama kurallarınızı yazmayı deneyebilirsiniz. Temiz kod yazma yolculuğunuzda bu standartları uygulamak, uzun vadede projenizi yönetilebilir kılacaktır.