Padrões de Design em Python

Escreva código Python de fácil manutenção usando princípios fundamentais de design. Esses padrões ajudam você a construir sistemas que são fáceis de entender, testar e modificar.

Quando Usar Esta Habilidade

• Projetando novos componentes ou serviços
• Refatorando código complexo ou emaranhado
• Decidindo se deve criar uma abstração
• Escolhendo entre herança e composição
• Avaliando a complexidade e o acoplamento do código
• Planejando arquiteturas modulares

Conceitos Principais

1. KISS (Keep It Simple - Mantenha Simples)

Escolha a solução mais simples que funcione. A complexidade deve ser justificada por requisitos concretos.

2. Responsabilidade Única (SRP - Single Responsibility Principle)

Cada unidade deve ter um único motivo para mudar. Separe as responsabilidades em componentes focados.

3. Composição Sobre Herança

Construa comportamento combinando objetos, não estendendo classes.

4. Regra dos Três

Espere até ter três instâncias antes de abstrair. A duplicação é frequentemente melhor do que a abstração prematura.

Início Rápido

# Simple beats clever
# Instead of a factory/registry pattern:
FORMATTERS = {"json": JsonFormatter, "csv": CsvFormatter}

def get_formatter(name: str) -> Formatter:
    return FORMATTERS[name]()

Padrões Detalhados e Exemplos Práticos

A documentação detalhada dos padrões está em references/details.md. Leia este arquivo quando a navegação de nível superior for insuficiente.

Resumo das Melhores Práticas

1. Mantenha Simples - Escolha a solução mais simples que funcione
2. Responsabilidade Única - Cada unidade tem um motivo para mudar
3. Separe as Responsabilidades - Camadas distintas com propósitos claros
4. Componha, não herde - Combine objetos para flexibilidade
5. Regra dos Três - Espere antes de abstrair
6. Mantenha Funções Pequenas - 20-50 linhas (varia com a complexidade), um propósito
7. Injete Dependências - Injeção de construtor para testabilidade
8. Delete Antes de Abstrair - Remova código morto, depois considere padrões
9. Teste Cada Camada - Testes isolados para cada responsabilidade
10. Explícito Acima de Esperto - Código legível supera código elegante

Solução de Problemas

Uma classe está crescendo e parece ter múltiplas responsabilidades, mas dividi-la parece errado. Aplique o teste do "motivo para mudar": liste todas as mudanças que poderiam exigir a edição desta classe. Se a lista tiver itens de domínios diferentes (por exemplo, análise de HTTP E regras de negócio E formatação), divida-a. Se todas as mudanças derivarem da mesma preocupação de domínio, a classe pode ter o tamanho apropriado.

Injetar todas as dependências através do construtor está produzindo construtores com 7+ parâmetros. Isso é um sinal de muitas responsabilidades em uma única classe, não um problema com a injeção de dependência. Divida a classe em unidades menores primeiro, então cada construtor naturalmente se tornará menor.

A composição está produzindo objetos "wrapper" profundamente aninhados que são difíceis de rastrear. Mantenha a composição rasa (2-3 níveis). Se o "wrapping" for o único mecanismo, considere se uma abordagem baseada em Protocolo ou composição de funções simples seria mais limpa do que uma cadeia de objetos decoradores.

A regra dos três diz para não abstrair ainda, mas a duplicação está causando bugs quando uma cópia é atualizada, mas a outra não. Duplicação que diverge de maneiras perigosas deve ser abstraída mais cedo. A regra dos três é uma heurística, não uma lei. Se as cópias já estão divergindo incorretamente, extraia imediatamente e adicione um teste que exercite o comportamento compartilhado.

Uma camada de serviço está importando da camada de API, quebrando a direção da dependência. Esta é uma violação de camadas. A camada de serviço não deve importar de handlers. Introduza uma camada compartilhada de tipos/modelos que ambos possam importar, mantendo a seta de dependência apontando para baixo (API → Serviço → Repositório).

Habilidades Relacionadas

• python-testing-patterns — Teste cada camada isoladamente usando a estrutura de injeção de dependência estabelecida aqui
• python-project-structure — Organize módulos e layout de diretórios para que os limites das camadas sejam explícitos desde o início