Melhores Práticas de Async
Regras para asyncio produtivo em serviços da era FastAPI - e quando permanecer síncrono.
Como Usar Esta Lista
- Aplique antes de converter um aplicativo Flask síncrono por completo.
- Meça o atraso do loop e o p99 sob carga após as alterações.
- Prefira bibliotecas async nativas em vez de pontes de executor quando o volume de chamadas for alto.
A - Quando Usar Async
- Muitas esperas de I/O concorrentes em um único processo. Centenas de conexões ociosas - o async brilha.
- Drivers async nativos disponíveis. httpx, asyncpg, clientes redis asyncio.
- Framework é async nativo. FastAPI, Starlette, servidor aiohttp.
- Pule o async para scripts de lote apenas de CPU. multiprocessing ou sequencial é mais simples.
- Não envolva o aplicativo Django inteiro em async sem um plano. Atrito entre ORM/middleware síncrono.
B - Higiene do Loop de Eventos
- Um loop de longa duração por worker. Hooks de ciclo de vida - não
asyncio.runpor requisição. - Nunca bloqueie a thread do loop. Sem
time.sleep, requisições síncronas, DB síncrono em corrotinas. - Descarregue bloqueios inevitáveis com
to_thread. Limite a concorrência com semáforo. - Defina timeouts padrão em clientes HTTP e de DB. Esperas travadas impedem verificações de integridade.
- Ative avisos de desenvolvimento para corrotinas não aguardadas. Trate como erros de CI quando viável.
C - Tarefas e Escopo
- Prefira TaskGroup para trabalho filho com escopo de requisição (3.11+). Sem tarefas órfãs após a resposta.
- Limite fan-out com semáforos. Proteja peers e descritores de arquivo.
- Recupere ou registre exceções de tarefas. Sem "dispare e esqueça" silencioso sem callback de conclusão.
- Cancele o trabalho na desconexão do cliente quando o negócio permitir. Economize recursos.
- Use
return_exceptions=Truequando o sucesso parcial for válido. APIs retornando erros por item.
D - Recursos
- Compartilhe AsyncClient/engine/pool no escopo do aplicativo. Criado no ciclo de vida, fechado no desligamento.
- Uma sessão de DB por requisição - não por linha. Transações curtas.
-
async withpara sessões, streams, locks. Liberação garantida ao cancelar. - Propague
contextvars(ID da requisição) para workers de thread. Continuidade do log. - Ajuste os pools para
max_connectionsdo DB / limites upstream. Matemática, não apenas padrões.
E - Operações
- Monitore a métrica de atraso do loop de eventos. Sinal precoce de regressão de bloqueio.
- Teste de carga para desligamento gracioso. Drenando tarefas e fechando pools.
- Documente ilhas síncronas na arquitetura. Pontes de executor conhecidas com plano de aposentadoria.
-
pytest-asynciomodo estrito em CI. Captureawaitausente em testes. - Reavalie quando as dependências lançarem async. Remova a camada de executor quando a biblioteca suportar
await.
FAQs
Async é sempre mais rápido?
Não - apenas quando esperas de I/O concorrentes dominam. Tarefas vinculadas à CPU ou baixa concorrência podem ser mais lentas devido à complexidade.
def síncrona na rota em FastAPI?
Executa em threadpool - OK para bibliotecas de bloqueio raras; async def + await nativo escala melhor.
Quanta ponte de executor é demais?
Se a maior parte do tempo da rota estiver em threads, migre o driver ou implante workers síncronos em vez disso.
websockets e SSE?
Casos de uso fortes para async - conexões de longa duração em um loop.
async para CLI?
asyncio.run uma vez no principal - OK; mantenha os internos async se usar HTTP async.
Múltiplos loops?
Raro - um loop por thread; não compartilhe clientes entre loops.
GIL e async?
Async não paraleliza CPU - descarregue computação separadamente.
Logging async?
Use manipuladores amigáveis a async ou enfileire para um listener de thread - evite emitir bloqueios no caminho crítico.
SDK de terceiros bloqueador?
Isole em thread pool, cacheie resultados ou substitua o fornecedor - documente o custo de latência.
Quando escolher threads em vez de async?
I/O bloqueador moderado, poucos endpoints, equipe não familiarizada com depuração async.
Relacionados
- Escolhendo um Modelo de Concorrência - escolha do modelo
- Depurando Código Async - ferramentas de incidentes
- Concorrência Estruturada - TaskGroup
- Melhores Práticas de Concorrência - regras de thread/processo
Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+, e uv 0.6+.