Estrutura Ideal de um Projeto Spring Boot: Padrões e Melhores Práticas

Introdução — Quando iniciamos um projeto usando o Spring Initializr, ganhamos uma aplicação pronta para rodar em poucos segundos. Porém, à medida que a aplicação cresce, a falta de uma arquitetura bem definida pode transformar o seu código em um grande monólito difícil de dar manutenção. Como organizar seus pacotes de verdade?

1. Por Que a Estrutura Importa?

Organização de código não é apenas um luxo estético. Uma estrutura clara ajuda novos desenvolvedores a se encontrarem no projeto (reduzindo o tempo de onboarding), evita dependências cíclicas entre classes e define limites e responsabilidades claras para cada parte do sistema.

No ecossistema Spring Boot, existem duas formas clássicas de se organizar os arquivos, além de abordagens mais modernas como a Clean Architecture e Arquitetura Hexagonal. Vamos focar nas duas formas de mapeamento de pacotes mais comuns.

2. A Clássica: Separação por Camadas (Package by Layer)

A abordagem mais ensinada em tutoriais e amplamente utilizada é separar os arquivos por responsabilidade técnica.

Neste modelo, todos os controladores ficam no mesmo lugar, todos os serviços em outro, e assim por diante:

com.empresa.app
├── config        # Configurações do Spring (Security, Swagger, Web)
├── controller    # REST Controllers (@RestController)
├── service       # Regras de Negócio (@Service)
├── repository    # Interfaces Spring Data (@Repository)
├── model         # Entidades do banco de dados (@Entity)
├── dto           # Objetos de Transferência de Dados
└── exception     # Tratamento global de erros (@ControllerAdvice)

✅ Vantagens:

Simplicidade absoluta, fácil de entender para desenvolvedores juniores.
Mapeamento claro e direto das camadas do MVC (Model, View, Controller).

❌ Desvantagens:

Baixa coesão técnica: Se você for alterar a lógica da entidade Usuario, precisará navegar por quase todas as pastas para alterar o UsuarioController, UsuarioService e UsuarioRepository.
Fica caótico em aplicações de grande porte. A pasta service pode facilmente chegar a 50 ou mais arquivos dificultando a navegação.

3. A Moderna: Separação por Feature / Domínio (Package by Feature)

À medida que abraçamos princípios de Domain-Driven Design (DDD) e Microsserviços, a separação por funcionalidade se torna a queridinha dos engenheiros de software seniores.

Nessa abordagem, os pacotes encapsulam funcionalidades ou domínios de negócio específicos.

com.empresa.app
├── core
│   ├── config
│   └── exception
├── user
│   ├── UserController.java
│   ├── UserService.java
│   ├── UserRepository.java
│   ├── User.java
│   └── UserDTO.java
└── product
    ├── ProductController.java
    ├── ProductService.java
    ├── ProductRepository.java
    └── Product.java

✅ Vantagens:

Alta Coesão: Tudo relacionado a "Usuários" vive no mesmo pacote.
Micro-Arquitetura Pronta: Se você precisar transformar o domínio product em um microsserviço independente amanhã, o esforço é ínfimo, pois as fronteiras já estão isoladas.
Visibilidade de Pacote (Package-Private): No Java, se os arquivos estão na mesma pasta, você pode omitir o modificador public nas suas entidades e repositórios. Isso obriga outros domínios da aplicação a interagirem com o user unicamente pela interface exposta do UserService, promovendo um excelente encapsulamento.

4. O Coração do Projeto: Classes Essenciais

Independentemente de usar por camada ou por feature, um bom projeto Spring Boot não deve misturar conceitos. Sempre conte com estas boas práticas:

Global Exception Handler

Evite lotar seus Controllers com blocos try-catch. Foque no Caminho Feliz (Happy Path) e delegue a captura de erros para uma classe centralizada (@ControllerAdvice).

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(EntityNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(EntityNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                             .body(new ErrorResponse(ex.getMessage()));
    }
}

O Uso Inteligente de DTOs

Nunca vaze suas entidades do banco (@Entity) diretamente em sua API REST. Entidades representam a estrutura estrita do banco de dados (tabelas e chaves); DTOs (Data Transfer Objects) representam o contrato da sua API. Usar bibliotecas como MapStruct ou ModelMapper facilita muito a tradução de um para o outro em poucas linhas.

5. Inversão de Controle e Injeção de Dependências

Para que a estrutura brilhe, o princípio da Injeção de Dependência do framework deve ser seguido. Prefira depender de interfaces para a comunicação entre módulos.

Além disso, sempre opte pela injeção através do método construtor (Constructor Injection), abandonando o uso da clássica, mas arriscada, anotação @Autowired diretamente nos campos (Field Injection).

@Service
public class UserService {
    // Injeção via construtor (Fortemente recomendado)
    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

🔥 Dica rápida: Se você usa a biblioteca Lombok, a anotação @RequiredArgsConstructor compila esse código do construtor automaticamente para você, mantendo a classe super limpa!

6. Conclusão

Não existe certo ou errado absoluto na arquitetura de software, mas sim o trade-off adequado. Um projeto pequeno ou um MVP rápido funciona maravilhosamente com Package-by-Layer. Contudo, times grandes que desenvolvem aplicações de longa vida preferem Package-by-Feature por promover coesão e preparo para evoluir para microsserviços.

A estrutura ideal é, no fim das contas, a que reduz a carga cognitiva da sua equipe no dia a dia. Padronize com seu time, centralize as documentações de arquitetura do projeto na raiz e extraia todo o potencial de produtividade que o ecossistema Spring entrega!