Kdaj bi moral uporabiti `async def` namesto `def` za endpoints?

Question

Accepted Answer

FastAPI podpira tako `async def` kot običajni `def` za operacije poti. Izbira je pomembna za zmogljivost: uporabite **`async def`** ko lahko `await` ne-blokirajočih I/O operacij, in običajni **`def`** ko vaša koda pokliče blokirajuče (sinhrone) operacije.

## Dve obliki

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

## Kako FastAPI obravnava vsako obliko

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

## Pravilo za odločitev

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

Kritično pravilo: **nikoli ne postavljajte blokirajočih klicev v `async def`** — to blokira event loop in uniči konkurenčnost. Uporabite bodisi asinkriono knjižnico z `await`, bodisi uporabite navaden `def` (ki ga FastAPI varno zažene v thread pool).

## Zakaj je to pomembno

Pravilna izbira med `async def` in `def` neposredno vpliva na zmogljivost in konkurenčnost vašega API-ja, in napačna izbira je pogosta, resna napaka.

Osrednja ugotovitev je, da je **`async def` koristen le, ko `await` ne-blokirajuče operacije** — postavka blokirajočega klica (kot je sinkriona knjižnica `requests` ali blokirajući gonilnik baze podatkov) v `async def` blokira celoten event loop, zamrzne vse konkurenčne zahtevke in prepreči namen async.

Obratno pa FastAPI pametno zažene navadne `def` endpoints v thread pool, zato je sinkriona/blokirajuča koda tam varna.

Razumevanje tega pravila — uporabite `async def` z res asinkronimi knjižnicami, uporabite navaden `def` za blokirajočo kodo in nikoli ne mešajte blokirajočih klicev v `async def` — je bistvenega pomena za pisanje produktivnih FastAPI endpoints in izogibanje subtilne a uničujoče napake nenamernega serializiranja vseh zahtevkov za blokirano event loop.