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
- Passo 1: Ter conhecimentos básicos de Spring Framework.
- Passo 2: Ter o Java e Maven instalados na máquina.
- Passo 3: Ter uma IDE como IntelliJ (ou Eclipse) instalada.
- Passo 4: Ter visto um curso introdutório de Spring Boot
(sugestão: playlist gratuita).
Dica
O uso do Spring Initializr é altamente recomendado para gerar o esqueleto do projeto
rapidamente.
Projeto Spring Boot do zero
- 1: Acesse o Spring Initializr e configure
Project para Maven, linguagem Java e versão adequada. - 2: Defina um nome de artefato descritivo — por exemplo,
bonus-controller. - 3: Selecione as dependências Spring Web (para
RESTful) e Spring DevTools (para fast reload). - 4: Baixe o projeto, descompacte e abra na sua IDE favorita.
Spring Initializr
Gera rapidamente um projeto base Spring Boot.
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 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.
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.
- 200 OK: GET/PUT/PATCH com sucesso e body.
- 201 Created: POST que criou recurso (+ Location quando fizer sentido).
- 204 No Content: DELETE/sucesso sem body.
- 400 Bad Request: validação/@Valid falhou, query obrigatória ausente.
- 404 Not Found: id inexistente (PathVariable sem registro).
- 409 Conflict: regra de unicidade/estado (opcional, mas claro).
GET na prática: path e query juntos
- 1: Crie um
UsuarioControllercom @RestController e @RequestMapping("/usuarios") . - 2: Adicione um método GET para buscar por ID usando @GetMapping( /{id} ) e @PathVariable .
- 3: Adicione outro método GET para busca por nome usando @GetMapping("/buscar") e @RequestParam .
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: 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.
CRUD completo de produtos na Controller
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.
- 1: GET:
@GetMappingretorna lista simulando
produtos. - 2: POST:
@PostMappingrecebe objeto no corpo
usando@RequestBody. - 3: PUT:
@PutMapping( /{id} )atualiza um produto
recebendo ID na rota e dados no corpo. - 4: DELETE:
@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.
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 ( /usuarios , /produtos ), documente com exemplos e sempre trate
erros retornando status corretos.
Fora da Controller
- Regras de negócio e cálculos de domínio → Service.
- Acesso a banco / queries → Repository.
- Validação de payload → DTO + @Valid (não ifs soltos no método).
- Mapeamento Entity↔DTO espalhado sem padrão → camada/mapper dedicado.
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.
- Request DTO ≠ Entity ≠ Response DTO (pode começar simples, mas separe cedo).
- @Valid no @RequestBody; trate MethodArgumentNotValidException → 400 estruturado.
- Nada de if (nome == null) espalhado na Controller.
- Service retorna Optional/entity; Controller mapeia para 404 quando vazio.
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
- Projeto criado no Spring Initializr com dependências Spring Web e DevTools
- Controller criada e configurada com @RestController e @RequestMapping
- Endpoints testados via navegador e Postman
- CRUD funcionando com ResponseEntity e boas práticas REST
- Próximos passos definidos: explorar Service e Repository
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.
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.
Continue explorando
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.
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.