Framework de Arquitetura Limpa
Uma abordagem disciplinada para estruturar software de modo que as regras de negócio permaneçam independentes de frameworks, bancos de dados e mecanismos de entrega. Aplique estes princípios ao projetar arquitetura de sistema, revisar limites de módulos ou aconselhar sobre gerenciamento de dependências.
Princípio Central
As dependências do código-fonte devem apontar para dentro — em direção às políticas de mais alto nível. Nada em um círculo interno pode saber sobre qualquer coisa de um círculo externo. Esta única regra produz sistemas que são testáveis e independentes de frameworks, UI, banco de dados e qualquer agência externa. As regras de negócio são o que importa; bancos de dados, frameworks web e mecanismos de entrega são detalhes — quando os detalhes dependem das políticas, você pode adiar decisões, trocar implementações e testar a lógica de negócio de forma isolada.
Pontuação
Meta: 10/10. Atribua um ponto para cada uma das sete linhas do Diagnóstico Rápido que a arquitetura satisfizer (0-7) e, em seguida, mapeie para uma faixa de 0 a 10: 6-7 satisfeitos = 9-10 (a Regra de Dependência é mantida, a lógica de negócio é independente de framework e banco de dados); 4-5 = 6-8 (o núcleo é testável, mas alguns detalhes vazam para dentro); 2-3 = 3-5 (o framework ou a persistência ditam a estrutura); 0-1 = 0-2 (sem limites — as regras de negócio vivem em controladores e modelos ORM). Relate a pontuação, as linhas do diagnóstico que falharam e a inversão específica necessária para corrigir cada uma.
1. Regra de Dependência e Círculos Concêntricos
Conceito central: Organize a arquitetura como círculos concêntricos — Entidades (regras de negócio corporativas) no centro, depois Casos de Uso (regras de negócio da aplicação), depois Adaptadores de Interface, com Frameworks e Drivers na camada mais externa. As dependências do código-fonte sempre apontam para dentro.
Por que funciona: Quando as políticas de alto nível não dependem de detalhes de baixo nível, você pode trocar o banco de dados, o framework web ou o estilo de API sem tocar na lógica de negócio — o sistema se torna resiliente às partes mais voláteis da pilha.
Insights principais:
- Círculos internos não podem mencionar nomes de círculos externos — sem classes, funções, variáveis ou formatos de dados de fora
- Os dados que cruzam um limite devem estar na forma mais conveniente para o círculo interno, nunca ditada pelo externo
- A Inversão de Dependência (interfaces definidas internamente, implementadas externamente) é o mecanismo que impõe a regra
- O número de círculos não é fixo — quatro é típico; a regra permanece a mesma
- Frameworks são detalhes, não arquitetura — eles pertencem ao círculo mais externo
Aplicações de código:
| Contexto | Padrão | Exemplo |
|---|---|---|
| Direção da camada | Círculos internos definem interfaces; externos implementam | Interface UserRepository nos Casos de Uso; PostgresUserRepository nos Adaptadores |
| Cruzamento de dados | DTOs cruzam limites, não entidades ORM | Caso de Uso retorna DTO UserResponse, não um modelo ActiveRecord |
| Direção da dependência | Setas de importação sempre apontam para dentro | Controller importa Caso de Uso; Caso de Uso nunca importa Controller |
Veja references/dependency-rule.md quando uma importação do círculo interno apontar para fora e você precisar da explicação detalhada dos quatro círculos, das regras de cruzamento de dados e do procedimento de inversão de dependência em quatro etapas para corrigi-la.
2. Entidades e Casos de Uso
Conceito central: Entidades encapsulam regras de negócio de toda a empresa — regras que existiriam mesmo sem software. Casos de Uso contêm regras específicas da aplicação que orquestram o fluxo de dados de e para as Entidades.
Por que funciona: Separar o que o negócio faz (Entidades) de como a aplicação orquestra (Casos de Uso) permite reutilizar Entidades entre aplicações e alterar o comportamento da aplicação sem modificar as regras centrais de negócio.
Insights principais:
- Entidades não são linhas de banco de dados — são objetos ou funções puras que encapsulam regras de negócio críticas
- Casos de Uso aceitam Modelos de Requisição e retornam Modelos de Resposta — nunca objetos de framework
- Cada Caso de Uso é uma única operação da aplicação (
CriarPedido,AprovarDespesa) - O padrão Interactor: uma classe de Caso de Uso implementa uma interface de limite de entrada e chama uma interface de limite de saída
- Mudanças em um Caso de Uso nunca devem afetar uma Entidade; alterações em Entidades podem se propagar para Casos de Uso
Aplicações de código:
| Contexto | Padrão | Exemplo |
|---|---|---|
| Design de Entidade | Regras de negócio críticas, zero dependências de framework | Pedido.calcularTotal() aplica regras de imposto; não sabe nada sobre HTTP |
| Requisição/Resposta | Estruturas de dados simples cruzam o limite | CriarPedidoRequest { itens, clienteId } — sem modelos ORM |
| Responsabilidade única | Um Caso de Uso por operação | ColocarPedido, CancelarPedido, ReembolsarPedido como classes separadas |
| Interactor | Implementa Porta de Entrada, chama Porta de Saída | ColocarPedidoInteractor implements ColocarPedidoInput |
Veja references/entities-use-cases.md ao projetar um Interactor ou decidir o que pertence a uma Entidade versus um Caso de Uso — tratamento completo de Regras de Negócio Corporativas vs. de Aplicação com exemplos de modelos de requisição/resposta.
3. Adaptadores de Interface e Frameworks
Conceito central: Adaptadores de Interface convertem dados entre a forma conveniente para Casos de Uso/Entidades e a forma exigida por agências externas. Frameworks e Drivers são a camada mais externa — código de cola para o mundo exterior.
Por que funciona: Quando o framework web, ORM ou fila de mensagens está confinado aos círculos externos, substituir qualquer um deles é uma mudança localizada. O banco de dados é um detalhe; a web é um detalhe; detalhes devem ser plugins para suas regras de negócio, não o esqueleto da aplicação.
Insights principais:
- Controladores traduzem HTTP em entrada de Caso de Uso; Apresentadores traduzem saída de Caso de Uso em modelos de visão
- Gateways implementam interfaces de repositório definidas pelos Casos de Uso — o círculo interno define o contrato, o externo o cumpre
- Regras de negócio nunca sabem se os dados vivem em SQL, NoSQL ou arquivos planos, ou que a entrega é HTTP
- Trate frameworks com desconfiança — eles querem que você se acople a eles; mantenha-os à distância
Aplicações de código:
| Contexto | Padrão | Exemplo |
|---|---|---|
| Controlador | Mecanismo de entrega → entrada de Caso de Uso | PedidoController.criar(req) constrói CriarPedidoRequest, chama Interactor |
| Apresentador | Saída de Caso de Uso → modelo de visão | PedidoApresentador.apresentar(resposta) formata para JSON/HTML |
| Gateway | Interface de repositório implementada por DB | SqlPedidoRepository implements PedidoRepository |
| Limite do framework | Framework chama para dentro, nunca o contrário | Manipulador de rota do Express chama Controller; Controller nunca importa Express |
Veja references/adapters-frameworks.md ao conectar controladores, apresentadores ou gateways, ou ao argumentar que o banco de dados/web é um detalhe — cobre arquitetura de plugins e como confinar um framework às bordas.
4. Princípios de Componentes
Conceito central: Componentes são as unidades de implantação. Três princípios de coesão governam o que vai dentro de um componente; três princípios de acoplamento governam as relações entre componentes.
Por que funciona: Componentes mal compostos criam efeitos cascata onde uma mudança força a reimplantação de código não relacionado; os princípios mantêm as mudanças localizadas e os lançamentos independentes.
Insights principais:
- REP (Equivalência de Reúso/Lançamento): classes em um componente devem ser versionáveis e lançáveis como uma unidade
- CCP (Fechamento Comum): classes que mudam pela mesma razão ao mesmo tempo pertencem juntas — SRP para componentes
- CRP (Reúso Comum): não force os usuários a depender de classes que não usam
- ADP (Dependências Acíclicas): o grafo de componentes não deve ter ciclos — quebre-os com DIP ou um novo componente
- SDP (Dependências Estáveis): dependa na direção da estabilidade
- SAP (Abstrações Estáveis): componentes estáveis devem ser abstratos; instáveis, concretos
Aplicações de código:
| Contexto | Padrão | Exemplo |
|---|---|---|
| Agrupamento de componentes | Agrupe classes que mudam juntas (CCP) | Todos os Casos de Uso relacionados a pedidos em um componente |
| Quebra de ciclos | Aplique DIP para inverter uma aresta de dependência | Extraia uma interface para um novo componente para quebrar o ciclo |
| Métricas de estabilidade | Instabilidade I = Ce / (Ca + Ce) | Muitas dependências de entrada, nenhuma de saída → I próximo de 0 (estável) |
Veja references/component-principles.md ao agrupar classes em componentes implantáveis ou quebrar um ciclo de dependência — cada um de REP, CCP, CRP, ADP, SDP, SAP trabalhados com a métrica de instabilidade.
5. Princípios SOLID
Conceito central: Cinco princípios em nível de classe e módulo — Responsabilidade Única, Aberto-Fechado, Substituição de Liskov, Segregação de Interface, Inversão de Dependência — os blocos de construção de nível médio que tornam a Regra de Dependência possível.
Por que funciona: Cada princípio aborda uma maneira específica pela qual as dependências dão errado, prevenindo a rigidez, fragilidade e imobilidade que transformam bases de código em pesadelos legados.
Insights principais:
- SRP: um módulo tem uma razão para mudar — ele serve a um ator (não "faz uma coisa")
- OCP: estenda o comportamento adicionando novo código, não modificando o existente — padrões de estratégia e plugin
- LSP: subtipos devem ser utilizáveis através da interface base sem que o cliente saiba — violado por exceções inesperadas ou métodos ignorados
- ISP: clientes não devem depender de métodos que não usam — interfaces gordas criam acoplamento desnecessário
- DIP: módulos de alto nível e módulos de baixo nível dependem de abstrações definidas pelo módulo de alto nível
Aplicações de código:
| Contexto | Padrão | Exemplo |
|---|---|---|
| Violação de SRP | Classe serve a múltiplos atores | Funcionario lida com pagamento (CFO), relatórios (COO), persistência (CTO) |
| OCP via estratégia | Novo comportamento através de novas classes | Adicione EntregaExpressa implementando EstrategiaEntrega; Pedido inalterado |
| Violação de LSP | Subtipo altera comportamento esperado | Quadrado extends Retangulo quebra o contrato de setLargura()/setAltura() |
| Aplicação de ISP | Divida interfaces gordas em interfaces de papel | Impressora, Scanner, Fax em vez de um DispositivoMultiFuncao |
| Conexão com DIP | Alto nível define interface; baixo nível implementa | ServicoPedido depende de GatewayPagamento, não de ClienteStripe |
Veja references/solid-principles.md ao aplicar SRP/OCP/LSP/ISP/DIP a uma classe específica ou diagnosticar uma violação — cada princípio trabalhado com exemplos de código e o cheiro que ele previne.
6. Limites e Anatomia de Limites
Conceito central: Um limite é uma linha entre coisas que importam e coisas que são detalhes, implementado através de polimorfismo: dependências cruzam apontando para dentro, enquanto o fluxo de controle pode cruzar em qualquer direção.
Por que funciona: Cada limite compra a opção de adiar uma decisão ou trocar uma implementação; o posicionamento estratégico de limites determina se um sistema é uma alegria ou uma dor de manter ao longo dos anos.
Insights principais:
- Limites completos usam interfaces recíprocas em ambos os lados; limites parciais usam uma estratégia ou fachada mais simples
- Padrão Objeto Humilde: divida o código do limite em uma parte difícil de testar (próxima ao limite) e uma parte fácil de testar (a lógica)
- Serviços não são automaticamente limites arquiteturais — um microsserviço com um modelo de dados compartilhado gordo é um monólito com chamadas de rede
- Testes são o componente mais isolado: eles dependem para dentro, nada depende deles
- Limites prematuros são caros, mas limites ausentes também — desenhe-os em pontos de provável volatilidade
Aplicações de código:
| Contexto | Padrão | Exemplo |
|---|---|---|
| Limite completo vs. parcial | Portas recíprocas, ou uma única estratégia | Caso de Uso define ColocarPedidoInput/ColocarPedidoOutput; casos mais simples usam uma EstrategiaEntrega |
| Objeto Humilde | Separe a lógica testável da infraestrutura | LogicaApresentador (testável) produz ModeloVisao; Visao (humilde) renderiza |
| Main como plugin | Raiz de composição monta o sistema | main() conecta todas as implementações concretas e inicia a aplicação |
Veja references/boundaries.md ao decidir onde desenhar um limite, escolher entre completo vs. parcial ou aplicar o padrão Objeto Humilde — também cobre serviços como limites, limites de teste e Main como o plugin definitivo.
Erros Comuns
| Erro | Por que Falha | Correção |
|---|---|---|
| ORM vazando para a lógica de negócio | Entidades acopladas ao esquema; mudanças no BD reescrevem regras de negócio | Separe entidades de domínio de modelos de persistência; mapeie na camada de adaptador |
| Regras de negócio em controladores | Não testável sem HTTP; duplicado entre endpoints | Mova a lógica para Interactors de Caso de Uso; controladores apenas traduzem e delegam |
| Arquitetura orientada a framework | Framework dita a estrutura; trocá-lo significa reescrever | Trate o framework como um plugin; estruture o código por capacidade de negócio |
| Dependências circulares entre componentes | Mudanças se propagam imprevisivelmente; sem lançamentos independentes | Aplique DIP ou extraia um componente de abstração compartilhada |
| Um Caso de Uso gigante por funcionalidade | Orquestradores inchados de milhares de linhas | Divida em Casos de Uso focados de operação única |
| Pular limites "porque é simples" | Acoplamento se acumula silenciosamente até que o custo seja enorme | Desenhe limites proativamente em pontos de provável volatilidade |
| Microsserviços como arquitetura boa automática | Um monólito distribuído é pior que um monólito limpo | Aplique a Regra de Dependência dentro e entre serviços; serviços são limites de implantação, não arquiteturais |
Diagnóstico Rápido
| Pergunta | Se Não | Ação |
|---|---|---|
| Você pode testar regras de negócio sem BD, servidor web ou framework? | Regras acopladas à infraestrutura | Extraia entidades e casos de uso por trás de interfaces; simule camadas externas |
| Todas as dependências de código-fonte apontam para dentro? | Dependências invertidas observadas | Aplique DIP: defina interface no círculo interno, implemente no externo |
| Nenhum modelo de framework/BD aparece em Entidades ou Casos de Uso? | Detalhes vazaram para dentro | Substitua por tipos definidos internamente; mapeie no adaptador |
| Os Casos de Uso são focados em uma única operação cada? | Casos de Uso fazem muitas coisas | Divida em classes separadas de operação única |
| Os controladores traduzem HTTP para entrada de Caso de Uso (não contêm lógica)? | Controladores contêm lógica de negócio | Mova a lógica para Interactors de Caso de Uso |
| O grafo de componentes não tem ciclos? | Ciclos no grafo de dependência | Extraia uma abstração compartilhada ou aplique DIP para quebrar o ciclo |
| A alteração de um detalhe (BD, framework web) não força mudanças nas regras de negócio? | Detalhes vazam através dos limites | Confirme que todos os detalhes estão atrás de interfaces definidas pelo interior |