ما هي نماذج Pydantic في FastAPI؟

Question

Accepted Answer

**نماذج Pydantic** هي فئات (ترث من `BaseModel`) تحدّد **البنية والأنواع وقواعد التحقق** للبيانات. يستخدمها FastAPI في كل مكان — لأجسام الطلبات وأشكال الاستجابات والإعدادات — مما يجعلها قلب التصميم الموجّه بالأنواع.

## تعريف نموذج

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

كل حقل يصرّح بنوع وقيود/قيم افتراضية اختيارية. يتحقق Pydantic من البيانات مقابل هذا التعريف ويحول الأنواع حيث يكون ذلك معقولاً.

## التحقق التلقائي والمعالجة

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

عند استخدامه كنوع معامل، يحلل FastAPI جسم طلب JSON إلى النموذج، **ويتحقق** من كل حقل ويعيد خطأ 422 منظماً يسرد بالضبط ما هو خاطئ — كل ذلك تلقائياً.

## ما يوفره Pydantic

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

## مصدر واحد للحقيقة

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

## لماذا يهم

نماذج Pydantic هي حجر الزاوية في FastAPI — وهي كيفية تحديد والتحقق من البيانات التي يقبلها وترجعها واجهة برمجتك، وتتدفق من خلالها تقريباً كل ميزة في FastAPI.

فهمها ضروري لأنها توفر **التحقق التلقائي** (حرج للأمان والاستتباب — عدم الثقة أبداً في الإدخال الخام)، والمعالجة/الإكراه، والتسلسل، ودعم المحرر، كل ذلك من فئة تصريحية واحدة.

تعمل كـ **مصدر واحد للحقيقة**: نموذج واحد يدفع التحقق من الطلب وشكل الاستجابة والتوثيق المُنشأ تلقائياً.

هذا النهج الموجّه بالأنواع والذي يتحقق بشكل افتراضي — الحصول على التحقق القوي من الإدخال والرسائل خطأ واضحة بشكل أساسي مجاناً — هو سبب رئيسي لكون FastAPI منتجاً وآمناً جداً، مما يجعل نماذج Pydantic معرفة أساسية يجب إتقانها.