Je, unapaswa kuwa na `async def` au `def` kwa endpoints?

Question

Accepted Answer

FastAPI inasupport `async def` na kawaida `def` kwa operesheni za njia. Chaguo linamaanisha kwa performance: tumia **`async def`** wakati unaweza `await` I/O isiyozuia, na kawaida **`def`** wakati nambari yako inaita operesheni zinazozuia (sinkroni).

## Aina mbili

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

## Jinsi FastAPI inavyohaweza kila moja

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

## Sheria ya uamuzi

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

Sheria muhimu: **kamata hakikishe kutoweza kuita zuzazuia kwenye `async def`** — inazuia event loop na kuporomza sambamba. Ama tumia maktaba async na `await`, au tumia `def` ya kawaida (ambayo FastAPI kwa aman inakabidhi kwenye thread pool).

## Kwa nini ni muhimu

Kuchagua kwa usahihi kati ya `async def` na `def` moja kwa moja kuathiri performance na sambamba ya API yako, na kukamatia vibaya ni hitilafu ya kawaida, kubwa.

Kulala muhimu ni kwamba **`async def` ni nzuri tu wakati unakuwa `await` operesheni zisizozuia** — kuwa na simu inayozuia (kama maktaba ya sinkroni `requests` au mfanyikazi wa hifadhi data inayozuia) kwa `async def` inazuia loop ya tukio nzima, kuuzuza ombi la sambamba nzima na kuangamiza kusudi la async.

Kinyume chake, FastAPI kwa akili inakabidhi `def` endpoints ya kawaida kwenye thread pool, hivyo kanuni ya sinkroni/inayozuia ni salama hapo.

Kufahamu sheria hii — tumia `async def` na maktaba za async halisi, tumia `def` ya kawaida kwa kanuni inayozuia, na kamata hairusha simu zinazozuia kwenye `async def` — ni muhimu kwa kuandika endpoints za FastAPI zenye ushindi na kuepuka hitilafu ya polepole lakini dhahiri ya kusambaza ombi nzima nyuma ya loop ya tukio iliyozuiwa.