Spring Controller: Domine os Endpoints, Anotações e o CRUD com Clareza
Entenda, na prática, como criar controllers robustos no Spring Boot, configure endpoints GET, POST, PUT e DELETE e elimine as principais dúvidas de rotas, anotações e integração com ferramentas como Postman. Guia organizado camada por camada focado em iniciantes com lacunas a superar.
Por que isso é importante
Entender a camada Controller é essencial em projetos Spring Boot, pois ela conecta seu back-end ao mundo externo, viabilizando APIs REST. Dominar o CRUD, além de saber quando usar GET, POST, PUT ou DELETE, é base para qualquer aplicação moderna. Corrigir lacunas e compreender as principais anotações ajuda a evitar bugs e acelera sua evolução.
O que é uma Controller no Spring Boot
A Controller é responsável por definir os endpoints HTTP que seu back-end exponibiliza. Cada rota corresponde a um método, permitindo que apps web, mobile ou outros sistemas externos interajam de forma padronizada via requisições REST. No Spring Boot, as controllers utilizam anotações (@RestController, @RequestMapping e outras) para configurar rotas, definir verbos e receber dados via parâmetros ou body.
ℹ️Atenção
Trabalhar corretamente com controllers impacta diretamente na segurança, flexibilidade e testes do seu sistema.
Estrutura em Camadas: Controller, Service, Repository
A arquitetura em camadas do Spring Boot separa responsabilidades: Controller lida com rotas e requisições, Service contém regras de negócio e Repository cuida da persistência dos dados. Essa divisão facilita manutenção, testes e escalabilidade do projeto.
⚠️Alerta
Ignorar a separação de responsabilidades pode gerar códigos difíceis de manter e evoluir, além de dificultar correção de bugs.
Pré-requisitos para Seguir o Guia
✅Dica
O uso do Spring Initializr é altamente recomendado para gerar o esqueleto do projeto rapidamente.
Configurando um Projeto Spring Boot do Zero
bonus-controller.IntelliJ IDEA
IDE avançada para desenvolvimento Java.
Maven
Gerenciador de dependências e builds Java.
⚠️Atenção
Não esqueça de adicionar o Spring Web — sem ele não será possível criar endpoints REST.
Criando sua Primeira Controller: Exemplo Prático
Dentro do pacote principal do seu projeto, crie o diretório controller. Em seguida, adicione uma classe Java chamada HelloController. Anote-a com @RestController e use @RequestMapping("/hello") para definir a rota base. Implemente um método anotado com @GetMapping para retornar uma mensagem, por exemplo: Olá Mundo.
ℹ️Atenção
O nome do método é irrelevante para o endpoint em si; o que importa é o caminho definido nas anotações.
GET com PathVariable vs RequestParam: Como Escolher?
Ao criar rotas GET, você pode receber dados tanto via PathVariable (parâmetro na URL) quanto via RequestParam (parâmetro de consulta). Cada abordagem tem suas vantagens dependendo da regra de negócio e do padrão esperado pelo cliente.
GET com PathVariable
O dado faz parte do caminho da URL, útil para identificar recursos específicos.
Prós
- URLs amigáveis e semânticas
- Direto para buscar por ID ou recurso único
Contras
- Menos flexível para diversos filtros
- Pode não escalar quando há muitos parâmetros diferentes
GET com RequestParam
Parâmetros enviados após ?, ideal para buscas com múltiplos filtros.
Prós
- Aceita múltiplos parâmetros de pesquisa
- Ótimo para queries dinâmicas
Contras
- URL pode ficar longa
- Menos intuitivo para buscar por recurso único
ℹ️Dica Técnica
Para buscas simples (por ID), prefira PathVariable. Para múltiplos filtros ou buscas dinâmicas, utilize RequestParam.
Exemplo Prático: Implementando GET com PathVariable e RequestParam
UsuarioController com @RestController e @RequestMapping("/usuarios").⚠️Atenção
O Spring diferencia automaticamente os métodos conforme as anotações. Cuidado para não repetir mapeamentos que possam gerar conflito.
Como Testar Endpoints: Usando o Navegador e Postman
Para métodos GET simples, basta abrir o navegador e acessar o endereço — exemplo: http://localhost:8080/usuarios/10. Para métodos que exigem parâmetros ou outros verbos, utilize ferramentas como o Postman. Ele permite simular GET, POST, PUT, DELETE, passando headers e corpo da requisição facilmente.
⚠️Atenção
O Postman Web exige um agente local para acessar de localhost. Use sempre a versão desktop local para testes em desenvolvimento.
Criando uma Controller Completa de Produtos (CRUD)
Para consolidar, crie uma ProdutoController com anotações @RestController e @RequestMapping("/produtos"). Implemente métodos GET (listar), POST (criar), PUT (atualizar) e DELETE (remover), usando ResponseEntity para respostas estruturadas. Para PUT e DELETE, use @PathVariable e @RequestBody conforme necessário.
@GetMapping retorna lista simulando produtos.@PostMapping recebe objeto no corpo usando @RequestBody.@PutMapping(/{id}) atualiza um produto recebendo ID na rota e dados no corpo.@DeleteMapping(/{id}) remove produto pelo ID.⚠️Alerta
Sempre retorne ResponseEntity no CRUD. Ele te permite controlar status HTTP e corpo da resposta, além de padronizar retornos para o front-end.
Melhores Práticas para Controllers no Spring Boot
Limite a lógica de negócio dentro das controllers: repasse tarefas para camadas de serviço. Use nomes de rotas consistentes, prefira plural para recursos (/usuarios, /produtos), documente com exemplos e sempre trate erros retornando status corretos.
❌Erro Comum
Colocar regras de negócio ou manipulação de dados diretamente nas controllers deixa o sistema rígido e de difícil manutenção.
Integrando com Outras Camadas: Próximos Passos
Após dominar a controller, avance para a implementação de Services (negócio) e Repositories (persistência). Esse fluxo modular permite crescer seus projetos sem perder organização ou qualidade.
✅Dica
Refatore aos poucos, criando testes ao mover métodos das controllers para as services.
Reaproveitando Seu Conhecimento
Todas as práticas vistas aqui podem ser replicadas em APIs reais: para negócios online, produtos digitais, soluções internas ou integrações mobile/web. Estude, pratique e estruture sua base — isso abrirá portas para abordar tópicos mais avançados, como autenticação com Spring Security.
✅Importante
Volte ao guia sempre que precisar revisar endpoints e anotações, principalmente ao iniciar projetos RESTful em Spring Boot.