كيف تستقبل جسم طلب JSON؟

Question

Accepted Answer

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

## النمط

```python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None      # optional field

@app.post("/items")
def create_item(item: Item):             # `item: Item` → read & validate the JSON body
    # `item` is a fully-validated Item object here
    return {"name": item.name, "total": item.price * 1.1}
```

```json
// request body the client sends:
{ "name": "Phone", "price": 999.0 }
```

تعلين `item: Item` يخبر FastAPI لقراءة جسم الطلب كـ JSON، وتحليله إلى `Item`، و**التحقق** من صحته — دالتك تستقبل كائن مكتوبة وصحيحة. المدخل السيء يُرفض تلقائياً:

```json
// POST { "name": "Phone" }  (missing price) → automatic 422:
{ "detail": [{ "loc": ["body", "price"], "msg": "field required" }] }
```

## الجسم + المسار + الاستعلام معاً

```python
@app.put("/items/{item_id}")
def update(item_id: int, item: Item, notify: bool = False):
    # item_id = path param, item = JSON body (Pydantic model), notify = query param
    # FastAPI distinguishes them by type/location automatically
```

يوجه FastAPI بذكاء المعاملات: عنصر نائب في المسار → معامل المسار، نموذج Pydantic → جسم الطلب، معامل مكتوب بشكل بسيط → معامل الاستعلام.

## معاملات جسم متعددة / تحديثات جزئية

```python
@app.patch("/items/{id}")
def patch(id: int, item: ItemUpdate):       # use a model with all-optional fields for PATCH
    update_data = item.model_dump(exclude_unset=True)   # only fields the client sent
```

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

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

التحقق أيضاً فائدة رئيسية **الأمان/المتانة** — المدخل الخاطئ يُرفض قبل الوصول إلى منطقك.

فهم كيفية تعريف نموذج الجسم، وكيفية تمييز FastAPI للجسم عن معاملات المسار/الاستعلام تلقائياً، وأنماط مثل `exclude_unset` للتحديثات الجزئية هو معرفة أساسية يومية لبناء أي نقطة نهاية للكتابة.