Spring Boot Controller: CRUD com PathVariable e RequestParam
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
Por que isso é importante
Spring Boot Controller (@RestController) expõe endpoints HTTP e devolve ResponseEntity — não é o lugar da regra de negócio. Use PathVariable para recurso na URL e RequestParam para filtros/query; valide com DTO + @Valid e delegue ao Service. Status corretos (200/201/204/400/404/409) são contrato da API.
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 do guia de Controller
Dica
O uso do Spring Initializr é altamente recomendado para gerar o esqueleto do projeto rapidamente.
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.
Primeira @RestController na prática
Dentro do pacote principal do seu projeto, crie o diretório <code>controller</code> . Em seguida, adicione uma classe Java chamada <code>HelloController</code> . 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.
PathVariable vs RequestParam: quando usar
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 .
Cheat sheet de status HTTP
Status HTTP é contrato. Não devolva 200 com body de erro.
GET na prática: path e query juntos
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.
Testar no navegador e no Postman
Para métodos GET simples, basta abrir o navegador e acessar o endereço — exemplo: <code>http://localhost:8080/usuarios/10</code> . 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.
CRUD completo de produtos na Controller
Para consolidar, crie uma <code>ProdutoController</code> 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 <code>ResponseEntity</code> no CRUD. Ele te permite controlar status HTTP e corpo da resposta, além de padronizar retornos para o front-end.
Controller fina: o que NÃO colocar nela
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 ( <code>/usuarios</code> , <code>/produtos</code> ), documente com exemplos e sempre trate erros retornando status corretos.
Fora da Controller
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.
DTO + @Valid: validação fora da bagunça
Controller magra: recebe DTO de request, anota @Valid, delega ao Service. Entity de JPA não deve ser o body público. Bean Validation (@NotNull, @Size, @Email…) fica no DTO; regra de negócio (estoque, duplicidade) fica no Service.
Service e Repository: 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.
Reaproveitar o padrão em outros recursos
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.
Checklist de Implementação
Checklist de Implementação
Fontes
Revisão em agosto de 2026. Use a versão default do Spring Initializr no dia do setup — este tutorial ensina o padrão Controller–Service–Repository, não um pin eterno de release.
<a href="https://spring.io/projects/spring-boot">Spring Boot</a>. <a href="https://docs.spring.io/spring-boot/documentation.html">Spring Boot documentation</a>. <a href="https://start.spring.io/">start.spring.io</a>.
Perguntas frequentes
O que um Spring Boot Controller faz?
Expõe endpoints HTTP, mapeia requests e devolve responses. É a porta de entrada da API — não o lugar da regra de negócio pesada.
Como criar um CRUD com @RestController?
Mapeie GET/POST/PUT/DELETE, receba DTO com @RequestBody, delegue ao Service e retorne status HTTP claros. Teste no Postman depois.
Controller deve acessar o banco diretamente?
Prefira camadas Controller → Service → Repository. Controller magro facilita teste e troca de persistência.
Qual a diferença entre @PathVariable e @RequestParam?
@PathVariable entra na URL como parte do path (/users/{id}); @RequestParam vai na query (?page=1). Use path para identidade e query para filtros.