كيف تعمل معاملات المسار ومعاملات الاستعلام؟

Question

Accepted Answer

يستخرج FastAPI **معاملات المسار** (جزء من مسار URL) و**معاملات الاستعلام** (بعد `?`) من وسيطات الدالة، باستخدام تلميحات النوع لتحويلها والتحقق منها تلقائياً.

## معاملات المسار — جزء من URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

معامل الدالة الذي يطابق اسمه `{placeholder}` في المسار يصبح **معامل مسار**. تلميح النوع (`int`) يحول السلسلة من URL تلقائياً ويعيد خطأ واضح 422 إذا لم تطابق.

## معاملات الاستعلام — كل شيء آخر

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

معاملات الدالة **غير** الموجودة في المسار تصبح **معاملات استعلام**. القيمة الافتراضية تجعلها اختيارية (`skip: int = 0`)؛ `str | None = None` يجعل معامل استعلام اختياري قابل للقيمة الفارغة. بدون قيمة افتراضية، تكون مطلوبة.

## مطلوب مقابل اختياري

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## دمج كليهما

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## لماذا يهم

معاملات المسار والاستعلام هي كيفية استقبال نقاط النهاية للإدخال من URL — أساسي لأي مسار API تقريباً (جلب مورد باستخدام المعرّف، التصفية، الترقيم، البحث).

نهج FastAPI أنيق وسبب رئيسي لإنتاجيته: الإعلان البسيط عن معاملات الدالة المكتوبة يمنحك الاستخراج التلقائي و**تحويل النوع** و**التحقق** (مع أخطاء 422 واضحة على الإدخال السيء) و**دلالات المطلوب مقابل الاختياري** (عبر القيم الافتراضية) — كل شيء مشتق من تلميحات نوع Python القياسية، بدون تحليل يدوي.

فهم الفرق (معاملات المسار تأتي من `{placeholders}`، كل شيء آخر هو معامل استعلام) وكيف تتحكم القيم الافتراضية في الاختيارية هو معرفة أساسية يومية لبناء نقاط نهاية FastAPI.