كيف تقوم بنمذجة أجسام الطلبات المتداخلة والمعقدة؟

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` (التحقق من الصيغة)، والقواميس المكتوبة/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 }
```

## لماذا يهم هذا

نادرًا ما تتعامل واجهات برمجة التطبيقات في العالم الحقيقي مع بيانات مسطحة — فهي تتعامل مع هياكل معقدة ومتداخلة (مستخدم بعنوان وقائمة طلبات، طلب يحتوي على عناصر سطر، كائنات التكوين)، وقدرة Pydantic على **تداخل النماذج** تجعل التحقق من صحة أجسام الطلبات المنظمة بعمق سهلاً.

فهم أن حقل نموذج يمكن أن يكون نموذجًا آخر، أو قائمة من النماذج، أو نوعًا غنيًا — وأن FastAPI **يتحقق من صحة البنية المتداخلة بأكملها بشكل متكرر وتلقائي** — أمر مهم لبناء واجهات برمجة تطبيقات تقبل مدخلات واقعية ومعقدة بأمان.

دعم الأنواع الغنية (enums للقيم المحدودة، تحليل `datetime`، التحقق من صيغة `HttpUrl`/`EmailStr`، المجموعات المكتوبة) يضمن بشكل إضافي أن البيانات المعقدة صحيحة دون فحوصات يدوية.

معرفة كيفية نمذجة الأجسام المتداخلة والمعقدة (والأغلفة العامة القابلة لإعادة الاستخدام للأشياء مثل الترقيم) هي معرفة عملية لبناء واجهات برمجة تطبيقات تتعامل مع البيانات المنظمة التي تتطلبها التطبيقات الحقيقية، مع التحقق الكامل المقدم تلقائيًا — وهي نقطة قوة رئيسية في تصميم FastAPI القائم على Pydantic.