คุณจะสร้างโมเดลสำหรับ request body ที่ซ้อนกันและซับซ้อนอย่างไร?

Question

Accepted Answer

Pydantic model สามารถ **ซ้อน (nest)** ได้ — field ของโมเดลหนึ่งสามารถเป็นอีกโมเดลหนึ่ง, เป็น list ของโมเดล หรือเป็น type ที่ซับซ้อนได้ — ทำให้ FastAPI สามารถ validate JSON ที่มีโครงสร้างลึก (object ภายใน object, array ของ object) ได้โดยอัตโนมัติ

## โมเดลที่ซ้อนกัน

```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"] }
```

Field ของโมเดลที่กำหนด type เป็นอีกโมเดลหนึ่ง (หรือ `list[Model]`) จะถูก validate แบบ recursive — ทั้ง nested object และ array ของ object จะถูกตรวจสอบกับ schema ของมันโดยอัตโนมัติ

## Type ที่ซับซ้อนและพิเศษ

```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 จัดการ type ที่หลากหลายได้: enum (จำกัดให้เป็นค่าที่อนุญาต), `datetime` (parse string แบบ ISO), `HttpUrl`/`EmailStr` (validate รูปแบบ) และ typed dict/tuple — ทั้งหมดถูก validate โดยอัตโนมัติ

## Wrapper แบบ generic / นำกลับมาใช้ใหม่ได้

```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 ในโลกจริงแทบไม่เคยจัดการกับข้อมูลแบบแบน — มันต้องจัดการกับโครงสร้างที่ซับซ้อนและซ้อนกัน (ผู้ใช้ที่มี address และ list ของ order, order ที่มี line item, object สำหรับ configuration) และความสามารถของ Pydantic ในการ **ซ้อนโมเดล** ทำให้การ validate request body ที่มีโครงสร้างลึกเหล่านี้ง่ายอย่างไม่น่าเชื่อ

การเข้าใจว่า field ของโมเดลสามารถเป็นอีกโมเดลหนึ่ง, เป็น list ของโมเดล หรือเป็น type ที่ซับซ้อน — และว่า FastAPI **validate ทั้งโครงสร้างที่ซ้อนกันแบบ recursive** โดยอัตโนมัติ — เป็นสิ่งสำคัญสำหรับการสร้าง API ที่รับ input ที่สมจริงและซับซ้อนได้อย่างปลอดภัย

การรองรับ type ที่หลากหลาย (enum สำหรับค่าที่จำกัด, การ parse `datetime`, การ validate รูปแบบ `HttpUrl`/`EmailStr`, typed collection) ยิ่งช่วยให้มั่นใจว่าข้อมูลที่ซับซ้อนถูกต้องโดยไม่ต้องตรวจสอบเอง

การรู้วิธีสร้างโมเดลสำหรับ body ที่ซ้อนกันและซับซ้อน (และ generic wrapper ที่นำกลับมาใช้ใหม่ได้สำหรับสิ่งต่าง ๆ เช่น pagination) เป็นความรู้เชิงปฏิบัติสำหรับการสร้าง API ที่จัดการข้อมูลที่มีโครงสร้างซึ่งแอปพลิเคชันจริงต้องการ พร้อมการ validate เต็มรูปแบบที่มีให้โดยอัตโนมัติ — จุดแข็งสำคัญของการออกแบบที่อิงกับ Pydantic ของ FastAPI