Middleware y Manejo de Errores
Añade CORS, IDs de solicitud y manejadores de excepciones consistentes.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["https://app.example"], allow_methods=["*"], allow_headers=["*"])
@app.middleware("http")
async def add_request_id(request: Request, call_next):
response = await call_next(request)
response.headers["X-Request-Id"] = request.headers.get("X-Request-Id", "generated")
return responseCuándo usar esto:
- Los clientes del navegador necesitan CORS
- Errores JSON uniformes
- Metadatos de solicitud transversales
Ejemplo Funcional
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
app = FastAPI()
class AppError(Exception):
def __init__(self, code: str, status: int = 400):
self.code = code
self.status = status
@app.exception_handler(AppError)
async def app_error_handler(_: Request, exc: AppError):
return JSONResponse(status_code=exc.status, content={"error": exc.code})
@app.get("/boom")
def boom():
raise AppError("invalid_state", 422)Lo que esto demuestra:
- Middleware CORS
- Middleware HTTP para encabezados
- Manejadores de excepciones registrados
Análisis Profundo
Cómo Funciona
- El middleware envuelve las solicitudes de afuera hacia adentro según el orden de
add_middleware. - Los manejadores de excepciones convierten los errores del dominio en JSON estables.
- Registra detalles del lado del servidor; devuelve mensajes seguros a los clientes.
Errores Comunes
- Validación de límites omitida: Llegan datos inválidos a las capas de persistencia. Solución: Valida con Pydantic o formularios del framework en el borde.
- Fugas de trazas de pila: Los clientes ven errores internos. Solución: Mapea excepciones a respuestas HTTP estables.
- Bloqueo de bucles de eventos asíncronos: Los trabajadores se bloquean bajo carga concurrente. Solución: Usa drivers asíncronos o wrappers de threadpool.
- Secretos en control de versiones: Las credenciales se filtran a través del historial de git. Solución: Carga secretos desde el entorno o una bóveda en tiempo de ejecución.
- Falta de observabilidad: Los incidentes son difíciles de depurar. Solución: Añade logs estructurados, métricas e IDs de solicitud.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Framework alternativo en este cookbook | Estándar del equipo o monolito existente | API nueva con diferentes restricciones |
| BaaS gestionado | MVP solo CRUD | Autenticación personalizada, flujos de trabajo o necesidades de cumplimiento |
| gRPC | RPC interno de alto rendimiento | Clientes HTTP públicos y acceso al navegador |
Preguntas Frecuentes
¿Cuándo debería adoptar el middleware de FastAPI?
Úsalo cuando los patrones y las compensaciones de esta página coincidan con tu API o el límite de datos.
¿Cuál es el principal error de producción con el middleware de FastAPI?
Omitir la validación, los tiempos de espera o los contratos de error explícitos en el borde HTTP.
¿Cómo pruebo el middleware de FastAPI?
Usa el cliente de prueba del framework, anula las dependencias y verifica el estado más la forma del JSON.
¿El middleware de FastAPI funciona con Python 3.14?
Sí, los ejemplos se dirigen a Python 3.14 con versiones de framework fijadas del pie de página de la pila.
¿Cómo se relaciona el middleware de FastAPI con Pydantic 2?
Valida y serializa en los límites; mantén los servicios funcionando con objetos de dominio tipados.
¿Síncrono o asíncrono?
Prefiere rutas asíncronas cuando el I/O domina; mantén el trabajo de CPU pequeño o descárgalo a workers.
¿Dónde debe vivir la lógica de negocio?
Controladores delgados; los servicios poseen las reglas; los repositorios poseen las consultas.
¿Cómo documento las APIs?
Publica documentación OpenAPI o de esquema que coincida con los modelos de respuesta en el código.
¿Cómo manejo el versionado?
Versionado explícito de URL o encabezado con ventanas de deprecación; evita roturas silenciosas.
¿Qué debo leer a continuación?
Sigue los enlaces Relacionados para obtener la siguiente capa de profundidad en esta sección.
¿Cómo me mantengo seguro?
Autentica a los llamadores, autoriza por recurso, limita la tasa y nunca registres secretos.
¿Primer paso para el rendimiento?
Mide la latencia de la base de datos y de los sistemas externos antes de cambiar de framework.
Relacionado
- Conceptos Básicos de FastAPI - Rutas y modelos principales
- Inyección de Dependencias - Proveedores por solicitud
- Pruebas de FastAPI - Patrones de cliente de prueba
- Despliegue de FastAPI - Servidores de producción
Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.