Boas Práticas de Arquitetura
Regras permanentes para serviços Python que permanecem testáveis, implantáveis e compreensíveis à medida que frameworks e equipes mudam.
Como Usar Esta Lista
- Trate itens não verificados como achados de revisão em PRs e documentos de design.
- Prefira regras aplicáveis (CI, lint, ADR) a acordos informais.
- Revise quando adicionar um novo ponto de entrada (API, worker, CLI) ou armazenamento de dados.
A - Limites
- Mantenha a lógica de domínio livre de importações de FastAPI, Django, Flask, boto3 e pandas. Regras de negócio devem compilar e testar sem frameworks de IO.
- Mapeie formas HTTP/ORM para tipos de domínio na borda. DTOs Pydantic 2 pertencem aos adaptadores, não aos construtores de entidade usados por workers.
- Defina portas com
Protocolpara dependências externas. Repositórios, relógios e notificadores recebem interfaces explícitas. - Use uma raiz de composição por item implantável.
main,lifespanoubuild_container()conectam adaptadores concretos - não globais espalhados.
B - Empacotamento e Importações
- Adote layout
srcpara serviços instaláveis. CI executauv syncoupip install -e .antes dos testes. - Banir hacks de
PYTHONPATH=.em fluxos de trabalho de desenvolvimento documentados. Se as importações precisarem disso, os metadados de empacotamento estão errados. - Quebre ciclos de importação extraindo módulos de tipos folha. Importações preguiçosas são uma ponte temporária, não arquitetura.
- Exponha uma API pública estreita via
__all__ou exportações de pacote documentadas. Módulos internos permanecem refatoráveis.
C - Configuração e Segurança
- Carregue configurações através de
pydantic-settingstipadas uma vez por processo. Semos.getenvbruto em módulos de negócios. - Armazene segredos apenas em ambiente ou gerenciador de segredos.
.env.examplelista nomes, nunca valores. - Valide padrões perigosos na inicialização. Valores de
SECRET_KEYde placeholder devem falhar rapidamente em configurações de produção. - Defina timeouts e retentativas de cliente HTTP em módulos adaptadores. Chamadas de rede ilimitadas são dívida operacional.
D - Modelagem de Dados e Domínio
- Modele dinheiro, quantidades e IDs como objetos de valor. Evite primitivas paralelas que se afastam.
- Guarde transições de entidade com métodos (
place(),cancel()). Mutação de atributo público contorna invariantes. - Mantenha pandas 2.2+ e Polars 1.x em adaptadores ETL. Funções de domínio aceitam coleções Python simples.
- Isole o carregamento/inferência de PyTorch 2.6+ atrás de portas. Importar torch no momento da importação do domínio atrasa testes e workers.
E - Portões de Qualidade
- Execute
ruff 0.9+para formatar e lintar em CI. Debates de estilo pertencem à configuração, não a threads de revisão. - Aperte tipos estáticos em arquivos alterados. Novos módulos atendem a regras mypy/pyright mais rigorosas do que os legados.
- Teste de unidade de casos de uso com adaptadores falsos. Testes de integração são um nível separado e fino.
- Documente decisões irreversíveis em ADRs. Escolhas de layout, framework e datastore precisam de um rastro de papel.
F - Operações e Evolução
- Emita logs estruturados com IDs de correlação em middleware HTTP. Depuração com
printnão escala para produção. - Separe verificações de saúde de liveness e readiness. Orquestradores precisam de sinais distintos.
- Execute migrações de banco de dados como um passo de implantação automatizado. SQL manual é um pesadelo de rollback.
- Prefira migrações strangler a reescritas "big-bang". Entregue fatias verticais com testes de caracterização.
FAQs
Quão rigorosas devem ser as regras de limite para scripts?
Scripts com algumas centenas de linhas podem coexistir lógica e IO. Promova para pacotes com limites quando um segundo ponto de entrada aparecer ou o script sobreviver a um trimestre.
Todos os serviços precisam de pastas hexagonais?
Não. Você precisa de direção de dependência clara. Nomes de pastas importam menos do que "domínio não importa FastAPI".
Quando um singleton de configurações globais é aceitável?
Quando acessado apenas a partir de raízes de composição e adaptadores. Casos de uso recebem valores ou protocolos, não from app.settings import settings.
Todo PR deve atualizar esta lista?
Use-a em revisões de design e auditorias trimestrais. PRs diários referenciam regras específicas ("importação de domínio adicionada - rejeitada") em vez de executar a lista completa novamente.
Como as melhores práticas interagem com Django?
Projetos Django ainda se beneficiam de portas para IO externo e configurações tipadas. Modelos ORM podem permanecer robustos para CRUD pesado de admin; adicione mapeamento quando as regras se multiplicarem.
Qual é o conjunto mínimo de fakes de teste?
Repositórios em memória e mailers/notificadores de log cobrem a maioria dos casos de uso. Adicione testes de contrato quando o SQL do adaptador for complexo.
Como impor limites de importação automaticamente?
Ferramentas como import-linter ou regras ruff personalizadas podem proibir domain importando adapters. Integre na CI após as convenções se estabilizarem.
Microserviços são necessários para uma boa arquitetura?
Não. Um monólito bem delimitado com módulos claros muitas vezes supera a proliferação distribuída. Divida por gatilhos de equipe ou escala, não por moda.
Com que frequência os ADRs devem ser escritos?
Para decisões caras de reverter: datastore, modelo de autenticação, barramento de eventos, framework principal. Pule ADRs para escolhas óbvias de ferramentas como ruff.
As configurações Pydantic podem servir como validação de domínio?
Configurações validam o ambiente. Domínio valida regras de negócio. A sobreposição é rara - mantenha as camadas separadas.
E os notebooks explorando a arquitetura?
Notebooks são descartáveis ou candidatos à promoção. Não deixe importações experimentais se tornarem limites de produção de fato sem empacotamento.
Como o uv se encaixa na prática de arquitetura?
Arquivos de bloqueio uv 0.6+ tornam a CI e o Docker reproduzíveis o mesmo grafo de dependência - uma base para design evoluível.
Relacionado
- Checklist de Decisões de Arquitetura de Projeto - decisões iniciais
- Arquitetura Limpa / Hexagonal - detalhe do padrão de limite
- Checklist de Auditoria de Código-Fonte - verifique se as práticas se mantêm
- Decisões de Refatoração - corrija violações
- Configuração e Configurações - mergulho profundo nas melhores práticas de configuração
Versões de 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+.