Quand utiliser `async def` plutôt que `def` pour les endpoints ?

Question

Accepted Answer

FastAPI supporte à la fois `async def` et `def` standard pour les opérations de chemin. Le choix est important pour la performance : utilisez **`async def`** quand vous pouvez `await` des opérations d'entrée/sortie non-bloquantes, et **`def`** standard quand votre code appelle des opérations bloquantes (synchrones).

## Les deux formes

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

## Comment FastAPI traite chacune

```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 règle de décision

```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 règle critique : **ne jamais mettre d'appels bloquants dans `async def`** — cela bloque la boucle d'événements et détruit la concurrence. Utilisez soit une bibliothèque async avec `await`, soit un `def` simple (que FastAPI exécute en toute sécurité dans un thread pool).

## Pourquoi c'est important

Choisir correctement entre `async def` et `def` affecte directement la performance et la concurrence de votre API, et faire le mauvais choix est une erreur courante et grave.

L'idée clé est que **`async def` n'est bénéfique que quand vous `await` des opérations non-bloquantes** — mettre un appel bloquant (comme la bibliothèque synchrone `requests` ou un driver de base de données bloquant) dans un `async def` bloque toute la boucle d'événements, gelant toutes les requêtes concurrentes et anéantissant l'intérêt de l'async.

Inversement, FastAPI exécute intelligemment les endpoints en `def` simple dans un thread pool, donc le code synchrone/bloquant est sûr là-bas.

Comprendre cette règle — utiliser `async def` avec des bibliothèques vraiment async, utiliser `def` simple pour le code bloquant, et ne jamais mélanger d'appels bloquants dans `async def` — est essentiel pour écrire des endpoints FastAPI performants et pour éviter l'erreur subtile mais dévastatrice de sérialiser accidentellement toutes les requêtes derrière une boucle d'événements bloquée.