Clean Architecture com Java e Spring Boot: guia prático

A maioria dos projetos Spring Boot começa organizada — controllers, services, repositories — mas em poucos meses vira um monólito onde tudo depende de tudo. A raiz do problema não é o framework, é a falta de uma arquitetura que proteja as regras de negócio.

O que é Clean Architecture

Clean Architecture, proposta por Robert C. Martin, organiza o código em camadas concêntricas onde a dependência sempre aponta para dentro — das camadas externas (frameworks, banco de dados) para as internas (regras de negócio).

As camadas principais são:

• Entities — objetos de domínio com regras de negócio puras
• Use Cases — orquestram o fluxo de dados entre entities e interfaces externas
• Interface Adapters — controllers, presenters, gateways
• Frameworks & Drivers — Spring, JPA, HTTP, banco de dados

Estrutura de pastas recomendada

src/main/java/com/example/
├── domain/
│   ├── entity/
│   │   └── Order.java
│   ├── gateway/
│   │   └── OrderGateway.java
│   └── usecase/
│       └── CreateOrderUseCase.java
├── infra/
│   ├── persistence/
│   │   ├── OrderJpaEntity.java
│   │   ├── OrderRepository.java
│   │   └── OrderGatewayImpl.java
│   └── config/
│       └── BeanConfig.java
└── api/
    ├── controller/
    │   └── OrderController.java
    └── dto/
        └── CreateOrderRequest.java

O ponto-chave: a pasta domain não importa nada do Spring. Ela é pura Java.

Use Case na prática

public class CreateOrderUseCase {
    private final OrderGateway orderGateway;

    public CreateOrderUseCase(OrderGateway orderGateway) {
        this.orderGateway = orderGateway;
    }

    public Order execute(String customerId, List<Item> items) {
        var order = Order.create(customerId, items);
        return orderGateway.save(order);
    }
}

Repare que OrderGateway é uma interface definida no domínio. A implementação concreta (OrderGatewayImpl) fica na camada de infra e usa JPA — mas o use case não sabe disso.

Benefícios concretos

• Testes unitários rápidos — o domínio roda sem Spring Context
• Troca de banco sem dor — mude de PostgreSQL para MongoDB alterando apenas a camada de infra
• Onboarding mais rápido — devs novos entendem onde cada coisa vive
• Menos acoplamento — mudanças no controller não quebram o domínio

Quando não usar

Clean Architecture adiciona complexidade. Para CRUDs simples ou MVPs com 2-3 entidades, o padrão MVC do Spring Boot é mais do que suficiente. Use Clean Architecture quando o domínio é complexo o bastante para justificar a separação.

Na NexCript, usamos Clean Architecture em todo projeto Java que tenha mais de 5 entidades de domínio. É o investimento que mais se paga em médio prazo.