Jak napisać niestandardową walidację w Pydantic?

Question

Accepted Answer

Poza wbudowanymi ograniczeniami, Pydantic pozwala na napisanie **niestandardowej logiki walidacji** za pomocą field validators (walidacja jednego pola) i model validators (walidacja across wielu pól) — dla reguł, które proste ograniczenia nie mogą wyrazić. (Składnia pokazana to Pydantic v2.)

## Field validators — walidacja/transformacja pojedynczego pola

```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
```

`@field_validator` uruchamia niestandardową logikę na polu: podnieś `ValueError` aby odrzucić nieprawidłowe wejście (FastAPI zamienia go na czysty 422), lub zwróć transformowaną wartość (np. normalizacja do małych liter).

## Model validators — walidacja cross-field

```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
```

`@model_validator(mode="after")` uruchamia się po walidacji wszystkich pól, z dostępem do całego modelu — używane dla reguł obejmujących **wiele pól** (np. potwierdzenie zgodności haseł, lub że data początkowa poprzedza datę końcową).

## Wbudowana walidacja często wystarczy na początek

```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
```

Preferuj ograniczenia `Field` i wyspecjalizowane typy dla prostych reguł; użyj niestandardowych validators dla rzeczywistej logiki biznesowej.

## Dlaczego to ważne

Niestandardowa walidacja Pydantic jest ważna dla egzekwowania reguł biznesowych, które wykraczają poza proste sprawdzenia typów i ograniczenia — a ponieważ walidacja jest krytyczna dla **bezpieczeństwa i integralności danych**, możliwość wyrażenia dowolnej reguły jest cenna. **Field validators** obsługują logikę pojedynczego pola (niestandardowe sprawdzenia formatu, normalizacja/transformacja), podczas gdy **model validators** obsługują powszechną potrzebę **walidacji cross-field** (zgodność haseł, zakresy dat, warunkowe wymagania), które reguły na poziomie pola nie mogą wyrazić.

Validators integrują się bezproblemowo z FastAPI — podniesiony `ValueError` automatycznie staje się czystą odpowiedzią 422.

Zrozumienie, kiedy używać wbudowanych ograniczeń/typów (dla prostych reguł) w porównaniu z niestandardowymi validators (dla rzeczywistej logiki biznesowej), i jak różnią się field validators od model validators, pozwala na zapewnienie, że przychodzące dane w pełni spełniają wymagania Twojej aplikacji, co czyni tę wiedzę ważną dla budowania solidnych i poprawnych interfejsów API.