Projeto de Código (Codebase Design)
Projete módulos profundos: muito comportamento por trás de uma interface pequena, colocada em uma junta limpa, testável através dessa interface. Use esta linguagem e estes princípios sempre que o código estiver sendo projetado ou reestruturado. O objetivo é alavancagem para os chamadores, localidade para os mantenedores e testabilidade para todos.
Glossário
Use estes termos exatamente — não substitua por "componente", "serviço", "API" ou "fronteira". Uma linguagem consistente é o ponto principal.
Módulo — qualquer coisa com uma interface e uma implementação. Deliberadamente agnóstico em relação à escala: uma função, classe, pacote ou fatia que atravessa camadas. Evite: unidade, componente, serviço.
Interface — tudo o que um chamador precisa saber para usar o módulo corretamente: a assinatura de tipo, mas também invariantes, restrições de ordenação, modos de erro, configuração necessária e características de desempenho. Evite: API, assinatura (muito estreitos — referem-se apenas à superfície de tipo).
Implementação — o que está dentro de um módulo, seu corpo de código. Distinto de Adaptador: uma coisa pode ser um pequeno adaptador com uma grande implementação (um repositório Postgres) ou um grande adaptador com uma pequena implementação (um fake em memória). Use "adaptador" quando a junta for o tópico; "implementação" caso contrário.
Profundidade — alavancagem na interface: a quantidade de comportamento que um chamador (ou teste) pode exercer por unidade de interface que precisa aprender. Um módulo é profundo quando uma grande quantidade de comportamento está por trás de uma interface pequena, e raso quando a interface é quase tão complexa quanto a implementação.
Junta (Michael Feathers) — um lugar onde você pode alterar o comportamento sem editar naquele lugar; a localização onde a interface de um módulo reside. Onde colocar a junta é uma decisão de projeto em si, distinta do que fica por trás dela. Evite: fronteira (sobrecarregado com o contexto limitado do DDD).
Adaptador — uma coisa concreta que satisfaz uma interface em uma junta. Descreve o papel (qual slot ele preenche), não a substância (o que está dentro).
Alavancagem — o que os chamadores obtêm da profundidade: mais capacidade por unidade de interface que aprendem. Uma implementação retorna o investimento em N locais de chamada e M testes.
Localidade — o que os mantenedores obtêm da profundidade: mudança, bugs, conhecimento e verificação concentram-se em um lugar em vez de se espalhar pelos chamadores. Corrija uma vez, corrigido em todos os lugares.
Profundo vs Raso
Módulo profundo = interface pequena + muita implementação:
┌─────────────────────┐
│ Interface Pequena │ ← Poucos métodos, parâmetros simples
├─────────────────────┤
│ │
│ Implementação │ ← Lógica complexa oculta
│ Profunda │
│ │
└─────────────────────┘
Módulo raso = interface grande + pouca implementação (evite):
┌─────────────────────────────────┐
│ Interface Grande │ ← Muitos métodos, parâmetros complexos
├─────────────────────────────────┤
│ Implementação Fina │ ← Apenas repassa
└─────────────────────────────────┘
Ao projetar uma interface, pergunte:
- Posso reduzir o número de métodos?
- Posso simplificar os parâmetros?
- Posso ocultar mais complexidade internamente?
Princípios
- Profundidade é uma propriedade da interface, não da implementação. Um módulo profundo pode ser internamente composto de partes pequenas, simuláveis e trocáveis — elas simplesmente não fazem parte da interface. Um módulo pode ter juntas internas (privadas à sua implementação, usadas por seus próprios testes) além da junta externa em sua interface.
- O teste de exclusão. Imagine excluir o módulo. Se a complexidade desaparecer, era um repasse. Se a complexidade reaparecer em N chamadores, o módulo estava valendo a pena.
- A interface é a superfície de teste. Chamadores e testes cruzam a mesma junta. Se você quiser testar além da interface, o módulo provavelmente tem o formato errado.
- Um adaptador significa uma junta hipotética. Dois adaptadores significam uma junta real. Não introduza uma junta a menos que algo realmente varie através dela.
Projetando para testabilidade
Interfaces boas tornam o teste natural:
-
Aceite dependências, não as crie.
// Testável function processOrder(order, paymentGateway) {} // Difícil de testar function processOrder(order) { const gateway = new StripeGateway(); } -
Retorne resultados, não produza efeitos colaterais.
// Testável function calculateDiscount(cart): Discount {} // Difícil de testar function applyDiscount(cart): void { cart.total -= discount; } -
Pequena área de superfície. Menos métodos = menos testes necessários. Menos parâmetros = configuração de teste mais simples.
Relacionamentos
- Um Módulo tem exatamente uma Interface (a superfície que apresenta a chamadores e testes).
- Profundidade é uma propriedade de um Módulo, medida em relação à sua Interface.
- Uma Junta é onde a Interface de um Módulo reside.
- Um Adaptador está em uma Junta e satisfaz a Interface.
- Profundidade produz Alavancagem para chamadores e Localidade para mantenedores.
Enquadramentos rejeitados
- Profundidade como proporção de linhas de implementação para linhas de interface (Ousterhout): recompensa o preenchimento da implementação. Usamos profundidade como alavancagem.
- "Interface" como a palavra-chave
interfacedo TypeScript ou métodos públicos de uma classe: muito estreito — interface aqui inclui todo fato que um chamador precisa saber. - "Fronteira": sobrecarregado com o contexto limitado do DDD. Diga junta ou interface.
Aprofundando
- Aprofundando um cluster dadas suas dependências — veja DEEPENING.md: categorias de dependência, disciplina de junta e teste de substituir em vez de em camadas.
- Explorando interfaces alternativas — veja DESIGN-IT-TWICE.md: crie subagentes paralelos para projetar a interface de várias maneiras radicalmente diferentes, depois compare com base em profundidade, localidade e posicionamento da junta.