Πώς μοντελοποιείτε ένθετα και πολύπλοκα σώματα αιτημάτων;

Question

Accepted Answer

Τα μοντέλα Pydantic μπορούν να **ενσωματωθούν** — ένα πεδίο μοντέλου μπορεί να είναι ένα άλλο μοντέλο, μια λίστα μοντέλων ή πολύπλοκοι τύποι — επιτρέποντας στο FastAPI να επαληθεύει το βαθιά δομημένο JSON (αντικείμενα μέσα σε αντικείμενα, πίνακες αντικειμένων) αυτόματα.

## Ένθετα μοντέλα

```python
from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    zip: str

class User(BaseModel):
    name: str
    address: Address                    # a NESTED model
    tags: list[str] = []                # a list of strings
    addresses: list[Address] = []       # a list of NESTED models

@app.post("/users")
def create(user: User):                  # validates the WHOLE nested structure
    return user
```

```json
// FastAPI validates this entire structure, including the nested address:
{ "name": "Ann",
  "address": { "street": "1 Main", "city": "NY", "zip": "10001" },
  "tags": ["vip"] }
```

Ένα πεδίο μοντέλου που πληκτρολογείται ως άλλο μοντέλο (ή `list[Model]`) επαληθεύεται αναδρομικά — τα ένθετα αντικείμενα και οι πίνακες αντικειμένων ελέγχονται όλα αυτόματα ενάντια στα σχήματά τους.

## Πολύπλοκοι και ειδικοί τύποι

```python
from pydantic import BaseModel, HttpUrl, EmailStr
from datetime import datetime
from enum import Enum

class Status(str, Enum):                 # enums constrain to allowed values
    active = "active"
    inactive = "inactive"

class Item(BaseModel):
    url: HttpUrl                          # validates URL format
    email: EmailStr                       # validates email format
    created: datetime                     # parses ISO 8601 strings → datetime
    status: Status                        # must be one of the enum values
    metadata: dict[str, int]              # typed dict
    coordinates: tuple[float, float]      # typed tuple
```

Το Pydantic χειρίζεται πλούσιους τύπους: enums (περιορισμός σε επιτρεπόμενες τιμές), `datetime` (ανάλυση συμβολοσειρών ISO), `HttpUrl`/`EmailStr` (επαλήθευση μορφής) και πληκτρολογημένα dicts/tuples — όλα επαληθεύονται αυτόματα.

## Γενικές / επαναχρησιμοποιήσιμες περιτυλίξεις

```python
from typing import Generic, TypeVar
T = TypeVar("T")
class Paginated(BaseModel, Generic[T]):   # a reusable generic response wrapper
    items: list[T]
    total: int
# Paginated[User] → { items: [User...], total: N }
```

## Γιατί έχει σημασία

Τα API του πραγματικού κόσμου σπάνια ασχολούνται με επίπεδα δεδομένα — χειρίζονται πολύπλοκες, ένθετες δομές (έναν χρήστη με διεύθυνση και μια λίστα παραγγελιών, μια παραγγελία με στοιχεία γραμμής, αντικείμενα διαμόρφωσης), και η ικανότητα του Pydantic να **ενσωματώνει μοντέλα** κάνει την επαλήθευση βαθιά δομημένων σωμάτων αιτημάτων χωρίς προσπάθεια.

Η κατανόηση ότι ένα πεδίο μοντέλου μπορεί να είναι ένα άλλο μοντέλο, μια λίστα μοντέλων ή ένας πλούσιος τύπος — και ότι το FastAPI **επαληθεύει ολόκληρη την ένθετη δομή αναδρομικά και αυτόματα** — είναι σημαντική για τη δημιουργία API που δέχονται ρεαλιστικές, πολύπλοκες εισόδους με ασφάλεια.

Η υποστήριξη πλούσιων τύπων (enums για περιορισμένες τιμές, ανάλυση `datetime`, επαλήθευση μορφής `HttpUrl`/`EmailStr`, πληκτρολογημένες συλλογές) εξασφαλίζει περαιτέρω ότι τα πολύπλοκα δεδομένα είναι σωστά χωρίς χειροκίνητους ελέγχους.

Η γνώση του τρόπου μοντελοποίησης ένθετων και πολύπλοκων σωμάτων (και επαναχρησιμοποιήσιμες γενικές περιτυλίξεις για πράγματα όπως η σελιδοποίηση) είναι πρακτική γνώση για τη δημιουργία API που χειρίζονται τα δομημένα δεδομένα που απαιτούν οι πραγματικές εφαρμογές, με πλήρη επαλήθευση που παρέχεται αυτόματα — ένα βασικό σημείο δύναμης του σχεδιασμού του FastAPI που βασίζεται στο Pydantic.