Camadas da Clean Architecture

Resumo rápido

A Clean Architecture organiza o sistema em quatro círculos concêntricos: Entities (regras corporativas), Use Cases (regras da aplicação), Interface Adapters (controllers, presenters, gateways) e Frameworks & Drivers (web, DB, UI). Cada anel só pode depender do que está para dentro dele. O Spring vive no anel mais externo.

Visão geral dos quatro anéis

graph TD
    subgraph L4["4. Frameworks & Drivers (web, DB, UI, Spring)"]
        subgraph L3["3. Interface Adapters (controllers, presenters, gateways)"]
            subgraph L2["2. Use Cases (interactors, boundaries)"]
                L1["1. Entities (regras de negócio corporativas)"]
            end
        end
    end
    L4 --> L3 --> L2 --> L1

As setas representam dependências de código apontando para dentro. Ver A Regra da Dependência.

1. Entities — regras de negócio corporativas

O anel mais interno e estável. Encapsula as Enterprise Business Rules: as regras e dados que existiriam mesmo sem o software — que fariam sentido numa empresa que operasse a lápis e papel. Pode ser um objeto com métodos, um conjunto de estruturas de dados e funções, ou um agregado de Domain-Driven Design com Entidades e Value Objects.

Uma Entity não sabe nada sobre casos de uso, banco de dados ou web. Ela muda apenas quando a regra de negócio corporativa muda — nunca por razão técnica.

2. Use Cases — regras de negócio da aplicação

As Application Business Rules. Contêm os interactors que orquestram o fluxo de dados de e para as Entities e as dirigem a satisfazer os objetivos do caso de uso. Uma mudança na operação da aplicação afeta este anel; mudanças em banco ou UI não devem afetá-lo.

Aqui vivem também os input/output ports (boundaries) e os request/response models. Detalhes em Use Cases.

3. Interface Adapters — adaptadores

Um conjunto de adaptadores que convertem dados do formato conveniente aos use cases/entities para o formato conveniente a agentes externos (e vice-versa). Aqui moram:

• Controllers: recebem a entrada externa e a traduzem em chamadas ao input port.
• Presenters: recebem o response model do output port e o formatam para a view.
• Gateways (adapters de repositório): implementam as interfaces de persistência definidas no núcleo.

Nenhum código interno ao anel 2 sabe da existência do banco. É aqui que o SQL, se houver, fica restrito.

4. Frameworks & Drivers — detalhes

O anel mais externo e volátil: o framework web (Spring MVC/WebFlux), o ORM (JPA/Hibernate), o banco de dados, a UI, os clients de mensageria. É tudo detalhe, tudo plugin. Escrevemos o mínimo de código aqui — normalmente só a cola que conecta o framework ao anel seguinte.

Tabela: o que vai em cada camada

Camada	Responsabilidade	Exemplos (Java/Spring)	Depende de
1. Entities	Regras de negócio corporativas	Pedido, ItemPedido, Dinheiro (Value Object)	Nada externo
2. Use Cases	Regras de aplicação, orquestração	CriarPedidoInteractor, CriarPedidoInputPort, PedidoOutputPort, PedidoGateway (interface), request/response models	Só do anel 1
3. Interface Adapters	Conversão de formatos	PedidoController, PedidoPresenter, PedidoGatewayJpaAdapter, mappers	Anéis 1 e 2
4. Frameworks & Drivers	Detalhes técnicos	Spring Boot, PedidoJpaRepository, PedidoJpaEntity, config, DataSource	Anel 3

Onde o Spring entra

O Spring é framework — anel 4. Consequências práticas:

• Anotações @RestController, @Service, @Repository, @Component ficam fora do núcleo. Um interactor puro não deveria ter @Service; se usar, é uma concessão pragmática discutível, não uma regra.
• As @Entity/@Table JPA pertencem a uma classe de persistência separada (ex.: PedidoJpaEntity), nunca à Entity de domínio Pedido.
• A injeção de dependência do Spring é o mecanismo que pluga os adaptadores externos nas interfaces internas — realizando a inversão da A Regra da Dependência.
• Configuração (application.yml, beans, @Configuration) mora no anel externo.

Ver a montagem completa em Exemplo Clean com Spring.

Anti-padrões e erros comuns

• Domínio anotado com JPA: @Entity na classe Pedido do núcleo arrasta o Hibernate para o centro.
• Camada de use case importando ResponseEntity: o interactor sabendo de HTTP.
• Gateway retornando PedidoJpaEntity: o formato de persistência vazando para o núcleo em vez do domínio.
• Colapsar anéis por preguiça: controller chamando o repositório JPA direto, pulando o use case — vira arquitetura em camadas comum, não Clean.
• Regra de negócio no controller ou no service transacional: lógica corporativa fora das Entities.

Relações

• Princípio que rege os anéis: A Regra da Dependência e DIP.
• Anel 2 em detalhe: Use Cases e Ports.
• Montagem prática: Exemplo Clean com Spring.
• Núcleo de domínio: Entidades, Value Objects, Repositórios, Domain-Driven Design.
• Equivalência com adapters: Adapters, Arquitetura Hexagonal, Driving e Driven.
• Índice e comparação: Clean Architecture, Comparação - Hexagonal vs Clean vs Camadas, Como Tudo se Conecta.
• Home.

Perguntas de revisão

1. Qual a diferença entre regras de negócio corporativas e regras de aplicação?

Resposta

Corporativas (Entities) existiriam sem o software e mudam só por razão de negócio. De aplicação (Use Cases) descrevem como o sistema automatiza um fluxo específico; mudam quando a operação da aplicação muda.

2. Em qual anel fica um Presenter?

Resposta

No anel 3, Interface Adapters. Ele recebe o response model produzido pelo output port e o formata para a view/resposta HTTP.

3. A classe @Entity do JPA é uma Entity da Clean Architecture?

Resposta

Não. A @Entity JPA é um detalhe de persistência do anel 4/3. A Entity da Clean é o objeto de domínio puro no anel 1. Devem ser classes separadas, com um mapper entre elas.

4. Por que escrevemos pouco código no anel 4?

Resposta

Porque ele é composto de frameworks e drivers — detalhes que já vêm prontos. Só escrevemos a cola de configuração e as implementações concretas das interfaces do núcleo, mantendo o volume de política nos anéis internos.