¿Cómo funciona el middleware en FastAPI?

Question

Accepted Answer

**Middleware** en FastAPI es código que se ejecuta para **cada request y response** — envuelve tus endpoints para manejar preocupaciones transversales como logging, timing, CORS y agregar headers. FastAPI utiliza el sistema de middleware de Starlette (está basado en ASGI).

## Escribiendo middleware personalizado

```python
import time

@app.middleware("http")
async def add_timing(request: Request, call_next):
    start = time.time()
    response = await call_next(request)        # call the endpoint (and any inner middleware)
    response.headers["X-Process-Time"] = str(time.time() - start)   # modify the response
    return response
```

El patrón: el código antes de `await call_next(request)` se ejecuta en el camino **hacia adentro** (antes del endpoint), `call_next` invoca el endpoint, y el código después se ejecuta en el camino **hacia afuera** (modificando la response). Esto envuelve cada request — aquí, agregando un header de timing a todas las responses.

## El flujo de request/response

```text
Request  → MW1 → MW2 → endpoint
Response ← MW1 ← MW2 ← endpoint
Middleware wraps the endpoint; runs in order on the way in, reverse on the way out.
```

## Middleware incorporado / común

```python
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], ...)  # CORS
app.add_middleware(GZipMiddleware, minimum_size=1000)                               # compression
```

El middleware se agrega comúnmente a través de `add_middleware` — CORS (permitir requests de origen cruzado), GZip (comprimir responses) y verificaciones de host de confianza son built-ins típicos.

## Usos comunes de middleware

```text
✓ Logging / request timing / metrics
✓ CORS (cross-origin request handling)
✓ Adding security or custom headers
✓ Response compression (GZip)
✓ Request ID / correlation ID injection
```

## Middleware vs dependencies

```text
Middleware   → runs for ALL requests; works at the raw request/response level (headers,
               timing, the whole response). Best for truly global concerns.
Dependencies → per-endpoint (or grouped) logic with access to parsed params, DI, and
               typed values. Best for auth, validation, shared parameters.
→ Use middleware for global cross-cutting concerns; dependencies for endpoint logic.
```

## Por qué es importante

Middleware es el mecanismo correcto para **preocupaciones globales y transversales** en FastAPI — lógica que debe aplicarse a cada request y response, como logging, timing de requests, CORS, compresión y headers personalizados.

Comprenderlo es importante para estructurar las aplicaciones correctamente: el middleware envuelve todos los endpoints (se ejecuta antes y después, con la capacidad de modificar tanto la request como la response), lo que lo hace ideal para el comportamiento de toda la aplicación que sería tedioso y propenso a errores repetir en cada endpoint.

Conocer la distinción entre **middleware** (global, nivel raw de request/response) y **dependencies** (por-endpoint, con acceso a valores analizados/tipados y DI — mejor para autenticación y validación) es clave para elegir la herramienta correcta.

Las necesidades comunes como CORS y compresión se manejan mediante middleware incorporado, mientras que el middleware personalizado cubre logging e instrumentación — haciendo que este sea un conocimiento práctico, frecuentemente utilizado para construir APIs bien estructuradas y observables.