Pydantic'te özel doğrulama (custom validation) nasıl yazarsınız?

Question

Accepted Answer

Yerleşik kısıtlamaların ötesinde, Pydantic **özel doğrulama mantığı** yazmanıza olanak tanır — alan doğrulayıcıları (tek bir alanı doğrula) ve model doğrulayıcıları (birden fazla alan arasında doğrula) ile basit kısıtlamaların ifade edemediği kurallar için. (Gösterilen söz dizimi Pydantic v2 içindir.)

## Alan doğrulayıcıları — tek bir alanı doğrula/dönüştür

```python
from pydantic import BaseModel, field_validator

class User(BaseModel):
    username: str
    password: str

@field_validator("username")
    @classmethod
    def username_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("username must be alphanumeric")   # → a 422 error
        return v.lower()                                         # can also TRANSFORM the value
```

Bir `@field_validator` bir alanda özel mantık çalıştırır: geçersiz girdiyi reddetmek için `ValueError` yükseltin (FastAPI bunu açık bir 422'ye dönüştürür) veya dönüştürülmüş bir değer döndürün (örneğin küçük harfe normalleştirme).

## Model doğrulayıcıları — alanlar arası doğrulama

```python
from pydantic import model_validator

class SignupForm(BaseModel):
    password: str
    confirm_password: str

@model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.confirm_password:    # compare MULTIPLE fields
            raise ValueError("passwords do not match")
        return self
```

Bir `@model_validator(mode="after")` tüm alanlar doğrulandıktan sonra çalışır ve tüm modele erişime sahiptir — **birden fazla alan** içeren kurallar için kullanılır (örneğin parolaların eşleştiğini onaylama veya başlangıç tarihinin bitiş tarihinden önce olduğunu onaylama).

## Yerleşik doğrulama genellikle ilk başta yeterlidir

```python
class Product(BaseModel):
    price: float = Field(gt=0)          # use Field constraints for simple rules
    sku: str = Field(pattern=r"^[A-Z]{3}-\d+$")
    email: EmailStr                      # specialized types for formats
# reach for custom validators only when constraints/types can't express the rule
```

Basit kurallar için `Field` kısıtlamalarını ve uzmanlaştırılmış türleri tercih edin; gerçek iş mantığı için özel doğrulayıcılar kullanın.

## Neden önemli

Özel Pydantic doğrulaması, basit tür kontrolleri ve kısıtlamalarının ötesine giden iş kurallarını uygulamak için önemlidir — ve doğrulama **güvenlik ve veri bütünlüğü** için kritik olduğundan, herhangi bir kuralı ifade edebilmek değerlidir. **Alan doğrulayıcıları** tek alan mantığını (özel format kontrolleri, normalleştirme/dönüştürme) gerçekleştirirken, **model doğrulayıcıları** alan düzeyindeki kuralların ifade edemediği **alanlar arası doğrulama** (parolalar eşleşiyor, tarih aralıkları, koşullu gereksinimler) için ortak gereksinimi gerçekleştirirler.

Doğrulayıcılar FastAPI ile sorunsuz bir şekilde entegre olur — yükseltilen bir `ValueError` otomatik olarak açık bir 422 yanıtı haline gelir.

Yerleşik kısıtlamaları/türleri (basit kurallar için) ne zaman kullanacağınızı, özel doğrulayıcıları (gerçek iş mantığı için) ne zaman kullanacağınızı ve alan doğrulayıcıları ile model doğrulayıcılarının nasıl farklı olduğunu anlamak, gelen verilerin uygulamanızın gereksinimlerini tamamen karşılamasını sağlamanıza ve güçlü, doğru API'ler oluşturmak için bu önemli bilgiye sahip olmanıza olanak tanır.