متى يجب استخدام async def مقابل def للنقاط النهائية (endpoints)؟

Question

Accepted Answer

يدعم FastAPI كلاً من `async def` و`def` العادي للعمليات على المسارات. الاختيار يهم من حيث الأداء: استخدم **`async def`** عندما تتمكن من `await` عمليات إدخال/إخراج غير محجوبة، و**`def`** العادي عندما يستدعي الكود عمليات محجوبة (متزامنة).

## الشكلان

```python
@app.get("/async")
async def async_endpoint():
    data = await fetch_from_api()        # await non-blocking I/O — efficient
    return data

@app.get("/sync")
def sync_endpoint():
    data = blocking_db_call()             # ordinary blocking code
    return data
```

## كيفية تعامل FastAPI مع كل منهما

```text
async def → runs on the main event loop. Efficient ONLY if you await non-blocking calls.
            ⚠️ A BLOCKING call inside async def blocks the WHOLE event loop → kills concurrency!
def       → FastAPI runs it in a THREAD POOL, so blocking code doesn't block the event loop.
            Safe for synchronous/blocking libraries.
```

## قاعدة القرار

```python
# ✅ async def — when you can await async libraries (httpx, async DB drivers)
async def get_user():
    async with httpx.AsyncClient() as c:
        return await c.get(url)

# ✅ plain def — when using SYNCHRONOUS/blocking libraries (requests, sync ORM)
def get_user():
    return requests.get(url).json()       # blocking → FastAPI runs it in a thread

# ❌ THE DANGEROUS MISTAKE — blocking call inside async def
async def bad():
    return requests.get(url).json()       # blocks the event loop! Use `def` or an async client
```

القاعدة الحرجة: **لا تضع أبداً استدعاءات محجوبة في `async def`** — فهذا يحجب حلقة الأحداث ويدمر التزامن. إما أن تستخدم مكتبة غير متزامنة مع `await`، أو تستخدم `def` عادي (الذي يقوم FastAPI بتشغيله بأمان في مجموعة خيوط).

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

الاختيار الصحيح بين `async def` و`def` يؤثر مباشرة على أداء واجهتك البرمجية والتزامن، والخطأ فيه هو غلطة شائعة وخطيرة جداً.

الرؤية الأساسية هي أن **`async def` مفيد فقط عندما تقوم بـ `await` عمليات غير محجوبة** — وضع استدعاء محجوب (مثل مكتبة `requests` المتزامنة أو محرك قاعدة بيانات محجوب) داخل `async def` يحجب حلقة الأحداث بأكملها، مما يجمد جميع الطلبات المتزامنة ويهدم الغرض من العمليات غير المتزامنة.

على العكس من ذلك، يقوم FastAPI بذكاء بتشغيل نقاط نهائية `def` عادية في مجموعة خيوط، لذلك الكود المتزامن/المحجوب آمن هناك.

فهم هذه القاعدة — استخدم `async def` مع مكتبات غير متزامنة حقيقية، استخدم `def` عادي للكود المحجوب، ولا تمزج أبداً استدعاءات محجوبة في `async def` — أمر أساسي لكتابة نقاط نهائية FastAPI ذات أداء عالية وتجنب الغلطة الدقيقة لكن المدمرة المتمثلة في تسلسل الطلبات عن غير قصد خلف حلقة أحداث محجوبة.