Kada turėtumėte naudoti async def vs def endpoint'ams?

Question

Accepted Answer

FastAPI palaiko tiek `async def`, tiek įprastą `def` kelio operacijoms. Pasirinkimas turi įtakos našumui: naudokite **`async def`** kai galite `await` neblokuojančią I/O operaciją, o įprastą **`def`** kai jūsų kodas iškviečia blokuojančias (sinchronines) operacijas.

## Dvi formos

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

## Kaip FastAPI tvarko kiekvieną

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

## Sprendimo taisyklė

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

Kritinė taisyklė: **niekada nedeškite blokuojančių iškvietimų `async def`** — tai blokuoja event loop'ą ir sunaikina konkurentingumą. Arba naudokite async biblioteką su `await`, arba naudokite įprastą `def` (kurį FastAPI saugiai paleidžia thread pool'e).

## Kodėl tai svarbu

Teisingas pasirinkimas tarp `async def` ir `def` tiesiogiai daro įtaką jūsų API našumui ir konkurentingumui, o klaidingas pasirinkimas yra įprasta, rimta klaida.

Pagrindinė įžvalga yra ta, kad **`async def` yra naudingas tik kai jūs `await` neblokuojančias operacijas** — blokuojančio iškvietimo (pvz., sinchroninės `requests` bibliotekos arba blokuojančio duomenų bazės tvarkiklio) dėjimas `async def` viduje blokuoja visą event loop'ą, sustabdo visus konkurentingus užklausas ir panaikina async paskirtį.

Priešingai, FastAPI protingai paleidžia įprastus `def` endpoint'us thread pool'e, todėl sinchroninis/blokuojantis kodas yra saugus ten.

Supratimas šios taisyklės — naudoti `async def` su tikrai async bibliotekoms, naudoti įprastą `def` blokuojančiam kodui, ir niekada nemixyti blokuojančių iškvietimų `async def` — yra būtinas norint rašyti našius FastAPI endpoint'us ir išvengti subtilios bet griaustos klaidos, kai netyčia serializuojate visus užklausas už blokuoto event loop'o.