Mejores Prácticas de Async

Reglas para un asyncio productivo en servicios de la era FastAPI, y cuándo mantenerse síncrono.

Cómo Usar Esta Lista

• Aplica antes de convertir una aplicación Flask síncrona por completo.
• Mide el lag del bucle y el p99 bajo carga después de los cambios.
• Prefiere librerías async nativas sobre puentes de executor cuando el volumen de llamadas es alto.

A - Cuándo Usar Async

• Muchas esperas de I/O concurrentes en un proceso. Cientos de conexiones inactivas: async brilla.
• Controladores async nativos disponibles. httpx, asyncpg, clientes redis asyncio.
• El framework es nativo async. FastAPI, Starlette, servidor aiohttp.
• Evita async para scripts de procesamiento por lotes solo de CPU. multiprocessing o secuencial es más simple.
• No envuelvas toda la aplicación Django en async sin un plan. Fricción con ORM/middleware síncrono.

B - Higiene del Bucle de Eventos

• Un bucle de larga duración por worker. Hooks de ciclo de vida, no asyncio.run por petición.
• Nunca bloquees el hilo del bucle. No uses time.sleep, peticiones síncronas, ni bases de datos síncronas en corrutinas.
• Descarga el bloqueo inevitable con to_thread. Limita la concurrencia con semáforo.
• Establece tiempos de espera predeterminados en clientes HTTP y de base de datos. Las esperas colgadas detienen las comprobaciones de estado.
• Habilita advertencias de desarrollo para corrutinas no esperadas. Trátalas como errores de CI cuando sea factible.

C - Tareas y Ámbito

• Prefiere TaskGroup para trabajo hijo en el ámbito de la petición (3.11+). Sin tareas huérfanas después de la respuesta.
• Limita el fan-out con semáforos. Protege pares y descriptores de archivo.
• Recupera o registra las excepciones de las tareas. Sin "disparar y olvidar" silenciosamente sin una callback done.
• Cancela el trabajo al desconectar el cliente cuando el negocio lo permita. Ahorra recursos.
• Usa return_exceptions=True cuando el éxito parcial sea válido. APIs que devuelven errores por ítem.

D - Recursos

• Comparte AsyncClient/engine/pool en el ámbito de la aplicación. Creado en el ciclo de vida, cerrado al apagar.
• Una sesión de base de datos por petición, no por fila. Transacciones cortas.
• async with para sesiones, streams, locks. Liberación garantizada al cancelar.
• Propaga contextvars (ID de petición) a los workers de hilos. Continuidad del registro.
• Ajusta los pools al max_connections de la base de datos / límites del upstream. Matemáticas, no solo valores predeterminados.

E - Operaciones

• Monitoriza la métrica de lag del bucle de eventos. Señal temprana de regresión de bloqueo.
• Prueba de carga de apagado ordenado. Drenando tareas y cerrando pools.
• Documenta las islas síncronas en la arquitectura. Puentes de executor conocidos con plan de jubilación.
• pytest-asyncio modo estricto en CI. Detecta await faltantes en pruebas.
• Reevalúa cuándo las dependencias envían async. Elimina la capa de executor cuando la librería soporte await.

Preguntas Frecuentes

Relacionado

• Elección de un Modelo de Concurrencia - elección del modelo
• Depuración de Código Async - herramientas de incidentes
• Concurrencia Estructurada - TaskGroup
• Mejores Prácticas de Concurrencia - reglas de hilos/procesos

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