Quando dovresti usare async def rispetto a def per gli endpoint?

Question

Accepted Answer

FastAPI supporta sia `async def` che `def` regolare per le operazioni di path. La scelta è importante per le prestazioni: usa **`async def`** quando puoi usare `await` su I/O non bloccanti, e **`def`** regolare quando il tuo codice esegue operazioni bloccanti (sincrone).

## Le due forme

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

## Come FastAPI gestisce ciascuna

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

## La regola decisionale

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

La regola critica: **non mettere mai chiamate bloccanti in `async def`** — blocca l'event loop e distrugge la concorrenza. Usa una libreria async con `await`, oppure usa un semplice `def` (che FastAPI esegue in modo sicuro in un thread pool).

## Perché è importante

Scegliere correttamente tra `async def` e `def` influisce direttamente sulle prestazioni e la concorrenza della tua API, e sbagliare è un errore comune e serio.

L'intuizione chiave è che **`async def` è vantaggioso solo quando usi `await` su operazioni non bloccanti** — mettere una chiamata bloccante (come la libreria `requests` sincrona o un driver di database bloccante) dentro un `async def` blocca l'intero event loop, congelando tutte le richieste concorrenti e vanificando lo scopo dell'async.

Al contrario, FastAPI esegue intelligentemente gli endpoint `def` semplici in un thread pool, quindi il codice sincrono/bloccante è sicuro lì.

Comprendere questa regola — usa `async def` con librerie veramente async, usa `def` semplice per il codice bloccante, e non mescolare mai chiamate bloccanti in `async def` — è essenziale per scrivere endpoint FastAPI performanti e evitare l'errore sottile ma devastante di serializzare accidentalmente tutte le richieste dietro un event loop bloccato.