Czym są modele Pydantic w FastAPI?

Question

Accepted Answer

**Modele Pydantic** to klasy (podklasy `BaseModel`), które definiują **strukturę, typy i reguły walidacji** dla danych. FastAPI używa ich wszędzie — w request bodies, response shapes i ustawieniach — czyniąc je sercem projektu opartego na typach.

## Definiowanie modelu

```python
from pydantic import BaseModel, EmailStr, Field

class User(BaseModel):
    name: str
    email: EmailStr                          # validates email format
    age: int = Field(ge=0, le=120)            # constraint: 0 <= age <= 120
    is_active: bool = True                    # default value
    tags: list[str] = []                      # typed list with a default
```

Każde pole deklaruje typ i opcjonalne ograniczenia/wartości domyślne. Pydantic waliduje dane względem tej definicji i konwertuje typy tam, gdzie ma to sens.

## Automatyczna walidacja i parsing

```python
@app.post("/users")
def create_user(user: User):                  # FastAPI builds & validates a User from the body
    return user                               # already validated here
# valid JSON → a typed User object; invalid → automatic 422 with field-level errors
```

Gdy jest używany jako typ parametru, FastAPI parsuje JSON request body do modelu, **waliduje** każde pole i zwraca strukturyzowany błąd 422 wymieniający dokładnie co jest nie tak — wszystko automatyczne.

## Co Pydantic ci daje

```text
✓ Validation — type checks + constraints (lengths, ranges, formats), clear errors
✓ Parsing/coercion — "5" → 5, ISO string → datetime, etc.
✓ Serialization — model.model_dump() / model_dump_json() → dict/JSON
✓ Editor support — full autocomplete & type checking on model attributes
✓ Self-documenting — the model defines the schema used in the auto-generated docs
```

## Jedno źródło prawdy

```text
One Pydantic model drives: request validation, the response schema, the OpenAPI docs,
and typed access in your code → define the data shape ONCE.
```

## Dlaczego to ważne

Modele Pydantic są kamieniem węgielnym FastAPI — to jak definiujesz i walidujesz dane, które twoje API akceptuje i zwraca, i prawie każda funkcja FastAPI przechodzi przez nie.

Zrozumienie ich jest niezbędne, ponieważ zapewniają automatyczną **walidację** (krytyczną dla bezpieczeństwa i odporności — nigdy nie ufając surowym danym wejściowym), parsing/coercion, serializację i obsługę edytorów, wszystko z jednej deklaracyjnej klasy.

Służą jako **jedno źródło prawdy**: jeden model napędza walidację żądania, shape odpowiedzi i automatycznie wygenerowaną dokumentację.

Te podejście oparte na typach, walidujące domyślnie — otrzymywanie solidnej walidacji danych wejściowych i jasnych komunikatów o błędach praktycznie za darmo — to główny powód, dla którego FastAPI jest tak wydajny i bezpieczny, czyniąc modele Pydantic fundamentalną, niezbędną wiedzą.