Spring boot starter validation como validar request body costuma dar problema quando a API precisa responder erro claro sem vazar regra de negocio. Quando uma API começa a receber JSON incompleto, email fora de formato ou campos vazios, a dor aparece rápido: o controller aceita a requisição, o serviço quebra mais adiante e o cliente recebe uma resposta pouco útil. a solução mais limpa para essa validacao é usar Bean Validation no DTO de entrada, com @Valid no controller e tratamento padronizado da exceção. Depois de ajustar esse trecho, o proximo passo natural e seguir para Spring boot validation dto: evite falhas em produção.
Isso evita que o dado ruim atravesse a aplicação inteira. em vez de descobrir o problema só no banco, no service ou em integração, a API falha na borda, com mensagens claras por campo e contrato previsível para quem consome. Esse ponto fica mais claro quando voce conecta com API REST Spring Boot Java: Guia Completo com Exemplo Prático.
Spring boot starter validation como validar request body: secao pratica com codigo completo
Na pratica, um exemplo enxuto ajuda a sair da teoria e evitar erro comum de producao quando o projeto cresce. Esse ponto fica mais claro quando voce conecta com JWT Spring Boot Java: Guia Completo com Exemplo Prático.
public record ClienteRequest(
@NotBlank String nome,
@Email String email
) {}
@PostMapping("/clientes")
public ResponseEntity<Void> criar(@Valid @RequestBody ClienteRequest request) {
return ResponseEntity.status(201).build();
}spring boot starter validation como validar request body na prática
O fluxo certo em Spring Boot é simples: o request chega, o Jackson converte o JSON para um DTO, e o Bean Validation confere as regras antes da execução do método. para funcionar bem, a classe de entrada precisa representar o contrato da API, não o modelo do banco. essa separação evita acoplamento e deixa a validação mais estável quando o domínio evolui. Esse ponto fica mais claro quando voce conecta com JWT no Spring Security com Spring Boot: autenticação moderna passo a passo.
Na prática, o caminho mais comum para validar request body spring boot é combinar o starter de validação com anotações como @NotBlank, @Email, @Size e @NotNull. o controller recebe o DTO com @Valid e a aplicação bloqueia payload inválido antes de chegar ao service. Depois de ajustar esse trecho, o proximo passo natural e seguir para Como tratar exceções no Spring Boot com @ControllerAdvice e @ExceptionHandler.
Anotações mais usadas no Bean Validation Spring Boot
As anotações que mais aparecem em projetos REST cobrem 80% dos casos reais. @NotBlank protege campos obrigatórios de texto que não podem vir em branco; @Email ajuda a validar formatos básicos de e-mail; @Size controla tamanho mínimo e máximo de strings, listas ou coleções; @NotNull garante presença do valor, embora não impeça string vazia; @Min, @Max e @Positive cuidam de números.
Esse conjunto resolve a maior parte dos contratos de entrada de uma API. quando a regra é de negócio mais sofisticada, vale partir para validação customizada, mas só depois de esgotar as anotações padrão. em manutenção, menos código customizado significa menos surpresa para quem assumir o projeto depois.
Spring boot starter validation como validar request body: Secção prática com código completo: bean validation spring boot exemplo
O melhor jeito de entender spring boot starter validation exemplo é ver uma implementação direta, sem firula. a estrutura abaixo mostra um endpoint de cadastro simples, com DTO validado, controller enxuto e tratamento consistente de erro. o ponto principal aqui é deixar claro que a validação acontece na entrada, não no meio do fluxo.
Dependência e DTO de entrada
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-validation'
}package com.javalizando.api.user;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
public class CreateUserRequest {
@NotBlank(message = "nome é obrigatório")
@Size(min = 3, max = 80, message = "nome deve ter entre 3 e 80 caracteres")
private String name;
@NotBlank(message = "email é obrigatório")
@Email(message = "email inválido")
private String email;
@NotBlank(message = "senha é obrigatória")
@Size(min = 8, message = "senha deve ter no mínimo 8 caracteres")
private String password;
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }
public String getPassword() { return password; }
public void setPassword(String password) { this.password = password; }
}Controller validando o request body
package com.javalizando.api.user;
import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/users")
public class UserController {
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public UserResponse create(@Valid @RequestBody CreateUserRequest request) {
return new UserResponse(
1L,
request.getName(),
request.getEmail()
);
}
}package com.javalizando.api.user;
public record UserResponse(Long id, String name, String email) { }Com isso, um JSON como { "name": "", "email": "abc", "password": "123" } não chega ao service. o Spring dispara uma exceção de validação e você decide como devolver a resposta. esse ponto é importante: validar não é só barrar erro, é também devolver feedback útil.
Tratando o erro do jeito certo
Uma API madura não devolve um monte de texto solto. ela devolve erros organizados, com campo, mensagem e contexto suficiente para o front-end ou o cliente da API entender o que corrigir. o caminho mais comum é usar @ControllerAdvice com @ExceptionHandler para capturar MethodArgumentNotValidException.
package com.javalizando.api.error;
import java.util.List;
public record ValidationErrorResponse(
String message,
List errors
) { }
record FieldErrorResponse(String field, String reason) { } package com.javalizando.api.error;
import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class ApiExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ValidationErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
var errors = ex.getBindingResult().getFieldErrors().stream()
.map(error -> new FieldErrorResponse(
error.getField(),
error.getDefaultMessage()
))
.toList();
return ResponseEntity
.status(HttpStatus.BAD_REQUEST)
.body(new ValidationErrorResponse("dados inválidos", errors));
}
}Esse formato é muito melhor do que deixar o Spring devolver uma mensagem genérica ou uma exceção sem padrão. em front-end, integração com mobile ou consumo por outros serviços, a diferença é enorme.
Erros comuns em produção ao validar request body spring boot
Dois cenários aparecem com frequência em produção. o primeiro é o cliente enviar um payload incompleto porque o formulário mudou e a API ainda aceita a requisição até um ponto tardio do fluxo. o segundo é a equipe achar que a validação está funcionando porque o controller recebe o objeto, mas esquecer de tratar a exceção e acabar expondo uma resposta confusa para o consumidor.
Comparando abordagens, a pior opção é confiar só em validação manual dentro do service, com vários if espalhados. a melhor é barrar o erro na entrada com Bean Validation, manter regra de formato no DTO e deixar o service cuidar apenas da regra de negócio. isso reduz repetição, melhora legibilidade e evita que um mesmo erro seja revalidado em três camadas.
Bloco de erro comum: causa, sintoma e correção
Erro: o endpoint aceita request inválido sem disparar validação.
Causa: falta a dependência spring-boot-starter-validation ou o parâmetro do controller não está anotado com @Valid.
Sintoma: campos vazios, e-mail malformado e valores curtos seguem adiante como se fossem válidos.
Correção: adicionar o starter de validação, colocar as anotações no DTO de entrada e marcar o @RequestBody com @Valid.
Outro erro recorrente é validar diretamente a entidade JPA. em bases pequenas parece prático, mas em produção vira dívida técnica rápido. mudança de regra de persistência passa a afetar contrato HTTP, e um ajuste feito para o banco quebra a API sem necessidade. Na prática, separar DTO de request e entidade de domínio quase sempre compensa.
Quando usar e quando evitar Spring Boot Starter Validation
Use Bean Validation quando o objetivo for proteger a fronteira da API. se o endpoint recebe cadastro, atualização parcial, login ou qualquer payload com campos obrigatórios, regras de formato ou limites simples, essa é a escolha natural. ela é previsível, barata de manter e fácil de explicar para o time.
Evite transformar Bean Validation em solução para tudo. regras que dependem de banco, de outro serviço ou de estado de negócio geralmente pedem uma validação adicional na camada de serviço. exemplo clássico: “e-mail já existe” não é validação de formato, é regra de negócio. Na prática, misturar as duas coisas deixa a API menos clara e o erro menos consistente.
Em uma API REST com múltiplas rotas, isso também afeta observabilidade. se cada time inventa um formato de erro diferente, os consumidores passam a tratar exceções de maneira improvisada. padronizar a resposta de validação cedo ajuda a escalar o sistema sem aumentar o custo de suporte.
Situações reais que aparecem em produção
Em uma API de cadastro de usuários, o formulário do front pode enviar apenas nome e e-mail, deixando a senha vazia em uma etapa intermediária. sem validação de entrada, o service tenta criar o usuário e falha mais à frente com erro de banco ou regra interna. com Bean Validation, o retorno já aponta exatamente o campo ausente.
Em outro cenário comum, uma API de integrações recebe payload de parceiros externos. muitas vezes o JSON chega com espaços em branco, tamanhos fora do contrato ou formatos inconsistentes. o Bean Validation ajuda a rejeitar cedo esse tipo de carga e evita que dados contaminados virem incidentes mais difíceis de rastrear.
Spring boot starter validation como validar request body: referencias externas
Para validar detalhes de implementacao e aprofundar a configuracao, vale consultar a documentacao oficial do Spring Security, o guia de claims no JWT.io e a documentacao do Spring Boot.
FAQ
Como validar @RequestBody no Spring Boot com Bean Validation?
Adicione spring-boot-starter-validation, crie um DTO com anotações como @NotBlank e @Email, e use @Valid no parâmetro do controller que recebe o @RequestBody. sem isso, a validação não roda no ponto certo.
Por que meu @Valid não está funcionando no RequestBody?
Os motivos mais comuns são ausência da dependência de validation, uso do tipo errado no parâmetro do controller ou anotação aplicada na classe errada. se a validação estiver na entidade JPA em vez do DTO, o fluxo pode parecer funcionar, mas o contrato da API fica inconsistente.
Qual a diferença entre 400 e 422 ao validar request body no Spring Boot?
Na prática, muita equipe usa 400 para payload inválido porque o request já nasceu malformado. o 422 também aparece quando o JSON é sintaticamente válido, mas não atende às regras de negócio. o mais importante é ser consistente no projeto inteiro e documentar o padrão escolhido.
Conclusão e próximos passos
essa validacao é uma daquelas decisões que parecem pequenas, mas mudam bastante a qualidade da API. quando a validação entra na borda do sistema, o erro aparece cedo, a resposta fica mais clara e o serviço para de lidar com lixo que deveria ter sido barrado antes. para time de produto e para quem consome a API, isso reduz retrabalho. Na prática, para quem mantém o código, reduz surpresa.
Se o próximo passo for evoluir essa base, vale padronizar a resposta de erro por campo, separar melhor DTO de domínio e revisar quais regras são realmente de formato e quais pertencem à camada de negócio. em projetos maiores, essa distinção evita acoplamento e melhora bastante a manutenção.
Leitura complementar: Spring boot validation dto: evite falhas em produção, API REST Spring Boot Java: Guia Completo com Exemplo Prático, Como tratar exceções no Spring Boot com @ControllerAdvice e @ExceptionHandler e Spring boot validation dto: evite falhas em produção. os proximos passos sao validar esse fluxo no seu projeto, ajustar o caso de uso real e cobrir a implementacao com testes.