Skip to content

3. O modelo da action

Uma action precisa das informações enviadas pelo navegador: os parâmetros da URL ([?name=martin&age=42]), os campos de formulário, o corpo JSON da requisição e, às vezes, um cabeçalho HTTP da requisição. O curso original chama o conjunto dessas informações de modelo da action. Este capítulo mostra como o [Spring MVC] fornece essas informações à action, as converte para o tipo correto e as valida. Esse processo é chamado de binding de dados ([data binding]).

Nota sobre a terminologia: no [Spring MVC], a palavra “modelo” ([Model]) designa principalmente os dados que uma action passa à sua view (Capítulo 4, “A view e seu modelo”). O modelo de uma action, no sentido usado neste capítulo, é aquilo que ela recebe.

Os exemplos 07 a 12 são, como os do capítulo anterior, módulos [Maven] da pasta [examples]. Você pode executar um deles abrindo um terminal nessa pasta e digitando [../mvnw spring-boot:run] ([..\mvnw spring-boot:run] no [Windows]); [Ctrl-C] interrompe o servidor. Cada exemplo tem um arquivo chamado [application.properties] com esta aparência:

1
2
3
4
# a porta de escuta do servidor (8080 por padrão)
server.port=5000
# as respostas de erro do Spring Boot não contêm a pilha de chamadas
spring.web.error.include-stacktrace=never
  • linha 2: a porta de escuta do servidor;
  • linha 4: quando uma requisição falha, [Spring Boot] responde com um documento JSON de erro (veremos vários deles neste capítulo). Esta propriedade impede que a pilha de chamadas da exceção ([stack trace]), que é longa e nunca deve ser exibida a um usuário, seja incluída. Isso é necessário porque a dependência [spring-boot-devtools] (as ferramentas de desenvolvimento, declarada no [pom.xml] pai) altera várias configurações padrão durante o desenvolvimento: em particular, ela adiciona a mensagem da exceção (propriedade [spring.web.error.include-message]) e a pilha de chamadas ([spring.web.error.include-stacktrace]) a esse JSON. Mantemos a mensagem, pois ela é útil para entender o que aconteceu; em produção, sem as ferramentas de desenvolvimento, ela também desaparece.

3.1. Exemplo 07: Os parâmetros da URL

O arquivo [controllers/ParametersController.java]:

package example07.controllers;

import java.util.Map;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/parameters")
public class ParametersController {

    // /parameters/action01?name=martin: o parâmetro de URL [name] -> o parâmetro de ação [name]
    // required = false: o parâmetro pode estar ausente, e então é null
    @GetMapping("/action01")
    public String action01(@RequestParam(required = false) String name) {
        return "name = [%s], of type %s".formatted(name, name == null ? "null" : name.getClass().getSimpleName());
    }

    // /parameters/action02?age=42: o valor é CONVERTIDO para o tipo do parâmetro;
    // sem required = false, o parâmetro é obrigatório
    @GetMapping("/action02")
    public String action02(@RequestParam int age) {
        return "age = [%d], of type int".formatted(age);
    }

    // /parameters/action03?age=42: Integer (e não int) aceita o valor null
    @GetMapping("/action03")
    public String action03(@RequestParam(required = false) Integer age) {
        return "age = [%s]".formatted(age);
    }

    // /parameters/action04?page=2: um valor padrão se o parâmetro estiver ausente
    @GetMapping("/action04")
    public String action04(@RequestParam(defaultValue = "1") int page) {
        return "page = [%d]".formatted(page);
    }

    // /parameters/action05?q=spring: o nome do parâmetro de URL, quando ele difere
    @GetMapping("/action05")
    public String action05(@RequestParam(name = "q", required = false) String search) {
        return "search = [%s]".formatted(search);
    }

    // /parameters/action06?name=martin&age=42: todos os parâmetros de uma vez
    @GetMapping("/action06")
    public Map<String, String> action06(@RequestParam Map<String, String> parameters) {
        return parameters;
    }
}

Vamos comentar este código:

  • Linhas 16–17: A anotação [@RequestParam] associa um parâmetro da action a um parâmetro da URL (a parte que segue o [?], conhecida como query string ou [query string]). Salvo indicação em contrário, o parâmetro da URL tem o mesmo nome que o parâmetro em [Java]: [name]. Esse nome só é conhecido em tempo de execução porque o projeto pai do [Spring Boot] instrui o compilador a preservá-lo no código compilado (opção [-parameters]). Uma anotação pode aceitar argumentos nomeados, chamados de atributos: [required = false] indica que o parâmetro pode ser omitido; nesse caso, equivale a [null]. Linha 18: O método [formatted] substitui cada ocorrência de [%s] na string pelo argumento seguinte; [name.getClass().getSimpleName()] é o nome curto do tipo do valor;
  • Linhas 23–24: O parâmetro é declarado com o tipo [int]: [Spring MVC] converte a string recebida (["42"]) em um número. Sem o atributo [required = false], [@RequestParam] torna o parâmetro obrigatório: este é o valor padrão de [required]. Um parâmetro ausente, ou cuja conversão falhe, causa um erro 400, e a action não é executada;
  • linhas 29–30: um [int] não pode ser igual a [null]. Para um número opcional, o parâmetro é declarado com o tipo [Integer], a classe [Java], que “encapsula” um [int] ([wrapper]): Um objeto [Integer] pode ter o valor [null], o que permite distinguir entre “nenhuma idade” e “idade 0”;
  • linhas 35–36: o atributo [defaultValue] fornece o valor a ser usado quando o parâmetro está ausente (ele também torna o parâmetro opcional). É uma string, convertida da mesma forma que o seria o valor recebido;
  • linhas 41–42: O atributo [name] especifica o nome do parâmetro da URL quando ele difere do nome do parâmetro [Java]: o parâmetro [search] da action recebe o parâmetro [q] da URL;
  • Linhas 47–48: Um parâmetro do tipo [Map<String, String>] anotado com [@RequestParam] recebe todos os parâmetros da URL, sem conversão: um dicionário (nome do parâmetro, valor). A action o devolve como está, e o [Spring MVC] o serializa em JSON.

Os resultados:

curl -i "http://localhost:5000/parameters/action01?name=martin"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 31

name = [martin], of type String
curl -i "http://localhost:5000/parameters/action01"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 27

name = [null], of type null

O servidor [Tomcat] não exibe o texto [OK] após o código 200 na primeira linha: esse texto é opcional no HTTP/1.1; apenas o código importa. As aspas em torno da URL são obrigatórias quando ela contém o caractere [&], que tem um significado especial para o console; nós as incluímos em todos os casos. Um parâmetro do tipo [int]:

curl -i "http://localhost:5000/parameters/action02?age=42"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 23

age = [42], of type int
curl -i "http://localhost:5000/parameters/action02?age=abc"
1
2
3
4
HTTP/1.1 400
Content-Type: application/json

{"timestamp":"2026-09-25T16:46:05.177Z","status":400,"error":"Bad Request","message":"Method parameter 'age': Failed to convert value of type 'java.lang.String' to required type 'int'; For input string: \"abc\"","path":"/parameters/action02"}
curl -i "http://localhost:5000/parameters/action02"
1
2
3
4
HTTP/1.1 400
Content-Type: application/json

{"timestamp":"2026-09-25T16:46:05.205Z","status":400,"error":"Bad Request","message":"Required parameter 'age' is not present.","path":"/parameters/action02"}

Esta é uma diferença significativa em relação ao [ASP.NET Core MVC], em que uma conversão impossível não impedia a execução da action. Com [@RequestParam], o [Spring MVC] lança uma exceção antes de chamar a action: [MethodArgumentTypeMismatchException] para uma conversão impossível, [MissingServletRequestParameterException] para um parâmetro obrigatório ausente (o console do servidor exibe os nomes dessas exceções). Um componente do [Spring MVC] as converte em uma resposta de erro 400 ([Bad Request], requisição inválida), e o [Spring Boot] gera o corpo dessa resposta: é a resposta de erro JSON já encontrada no capítulo anterior. Seus campos:

  • [timestamp]: a data e a hora do erro (em Tempo Universal Coordenado);
  • [status], [error]: o código HTTP e sua descrição;
  • [message]: a mensagem da exceção, incluída aqui porque as ferramentas de desenvolvimento a solicitaram;
  • [path]: o caminho da requisição.

Um navegador que solicita uma página com o código HTML recebe, em vez disso, uma página de erro mínima, a “Whitelabel Error Page”. Veremos no Exemplo 12 como tratar você mesmo essas exceções. Com o tipo [Integer]:

curl -i "http://localhost:5000/parameters/action03?age=42"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10

age = [42]
curl -i "http://localhost:5000/parameters/action03"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 12

age = [null]
curl -i "http://localhost:5000/parameters/action03?age=abc"
1
2
3
4
HTTP/1.1 400
Content-Type: application/json

{"timestamp":"2026-09-25T16:46:05.250Z","status":400,"error":"Bad Request","message":"Method parameter 'age': Failed to convert value of type 'java.lang.String' to required type 'java.lang.Integer'; For input string: \"abc\"","path":"/parameters/action03"}

Um parâmetro ausente é tratado como [null]; um parâmetro inválido sempre resulta em um erro 400. O valor padrão:

curl -i "http://localhost:5000/parameters/action04"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10

page = [1]
curl -i "http://localhost:5000/parameters/action04?page=2"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10

page = [2]
curl -i "http://localhost:5000/parameters/action04?page="
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 10

page = [1]

Um parâmetro presente, mas vazio ([?page=]), é tratado como se estivesse ausente: ele assume o valor padrão. As duas últimas actions:

curl -i "http://localhost:5000/parameters/action05?q=spring"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 17

search = [spring]
curl -i "http://localhost:5000/parameters/action06?name=martin&age=42"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 28

{"name":"martin","age":"42"}

Aqui, age é uma string (["42"]): sem um tipo declarado, não há conversão. Por fim, os nomes dos parâmetros diferenciam maiúsculas de minúsculas:

curl -i "http://localhost:5000/parameters/action01?NAME=martin"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 27

name = [null], of type null

O parâmetro [NAME] não é o mesmo que o parâmetro [name], que, portanto, está ausente. Esta é outra diferença em relação ao [ASP.NET Core MVC], que ignora a diferença entre maiúsculas e minúsculas. Observe que:

  • [@RequestParam] vincula um parâmetro da action a um parâmetro de mesmo nome na URL, inclusive quanto às letras maiúsculas (atributo [name] se os nomes forem diferentes);
  • o parâmetro é obrigatório por padrão; [required = false] o torna opcional, e [defaultValue] fornece um valor de reserva;
  • seu valor é convertido para o tipo declarado, e uma conversão impossível resulta em um erro 400 sem executar a action. Um tipo objeto ([Integer], e não [int]) permite receber [null].

Caracteres acentuados e espaços são codificados em uma URL ([%C3%A9] para [é], etc.): [Spring MVC] os decodifica antes do binding. O navegador exibe a URL codificada e o JSON recebido:

Image

3.2. Exemplo 08: Um modelo de action descrito por uma classe

Quando uma action tem vários parâmetros, eles são descritos por uma classe. Cada campo da classe tem restrições de validação, na forma de anotações. Elas são definidas pelo [Bean Validation], o padrão de validação do [Java] (pacote [jakarta.validation]), cuja implementação mais utilizada é o [Hibernate Validator]. Elas não fazem parte do [Spring MVC]: é preciso adicionar o starter de validação ao [pom.xml] do exemplo:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>course.springmvc</groupId>
    <artifactId>examples</artifactId>
    <version>1.0</version>
  </parent>
  <artifactId>example08</artifactId>

  <dependencies>
    <!-- validação (Bean Validation, Hibernate Validator) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
  </dependencies>
</project>
  • linhas 6–10: o projeto pai, [pom.xml], na pasta [examples];
  • Linhas 13–19: O starter [spring-boot-starter-validation] inclui o [Hibernate Validator] e o configura. Lembre-se de que um starter é uma dependência que agrupa outras dependências, junto com suas versões e sua configuração automática. Os exemplos 09 a 12 compartilham a mesma dependência.

O arquivo [models/PersonModel.java]:

package example08.models;

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;

// o modelo da ação: uma classe em que cada campo carrega suas restrições
public class PersonModel {

    @NotBlank(message = "the name is required")
    @Size(min = 2, max = 20, message = "the name must have 2 to 20 characters")
    private String name;

    @NotNull(message = "the age is required")
    @Min(value = 0, message = "the age must be between 0 and 150")
    @Max(value = 150, message = "the age must be between 0 and 150")
    private Integer age;

    @NotNull(message = "the title is required")
    @Pattern(regexp = "Mr|Mme|Melle", message = "unknown title")
    private String title;

    // opcional: sem @NotNull
    @Email(message = "invalid email address")
    private String email;

    // os acessores (getters e setters): o binding de modelo preenche
    // cada campo por meio de seu setter; a serialização JSON o lê por meio de seu getter
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }

    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

Vamos comentar este código:

  • linhas 3–9: as anotações de validação, todas no pacote [jakarta.validation.constraints];
  • linhas 14–16: o nome é obrigatório e não pode ser vazio ([@NotBlank] rejeita [null], uma string vazia e uma string formada por espaços) e deve ter entre 2 e 20 caracteres ([@Size]). Cada anotação aceita uma mensagem de erro personalizada (atributo [message]);
  • linhas 18–21: A idade é convertida em um inteiro, que é obrigatório ([@NotNull]), e deve estar entre 0 e 150 ([@Min], [@Max]). Ela é declarada como [Integer] em vez de [int], para que “nenhuma idade” ([null]) seja detectada por [@NotNull] em vez de ser definida como 0;
  • linhas 23–25: o título deve corresponder à expressão regular [Mr|Mme|Melle] ([@Pattern]): deve ser um destes três valores;
  • linhas 28–29: o endereço de e-mail é opcional (sem [@NotNull]); se presente, deve ser válido ([@Email]). Todas as restrições, exceto [@NotNull] e [@NotBlank] , aceitam o valor [null]: é isso que torna um campo opcional;
  • linhas 33–43: os acessores. Por convenção, o valor do campo [name] é lido pelo método [getName] ([getter]) e escrito pelo método [setName] ([setter]). Uma classe que tem um construtor sem parâmetros (neste caso, o fornecido implicitamente pelo [Java]) e acessores que seguem essa convenção é chamada de JavaBean. Essa é a forma esperada pelo data binding: o [Spring MVC] cria o objeto usando seu construtor sem parâmetros e, em seguida, para cada parâmetro da requisição, chama o setter de mesmo nome: [setName("martin")] para [?name=martin], após converter o valor para o tipo do setter. O conversor JSON, por sua vez, lê os campos por meio de seus getters.

O arquivo [controllers/PersonsController.java]:

package example08.controllers;

import java.util.LinkedHashMap;
import java.util.Map;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import example08.models.PersonModel;
import jakarta.validation.Valid;

@RestController
@RequestMapping("/persons")
public class PersonsController {

    // /persons/action01?name=martin&age=42&title=Mr
    // @Valid: o modelo é validado ANTES de a ação ser executada; se for
    // inválido, a requisição é rejeitada AUTOMATICAMENTE (erro 400)
    @GetMapping("/action01")
    public Map<String, Object> action01(@Valid PersonModel person) {
        Map<String, Object> response = new LinkedHashMap<>();
        response.put("person", person);
        response.put("ageType", person.getAge().getClass().getSimpleName());
        return response;
    }
}
  • Linha 21: A action recebe um [PersonModel]. O parâmetro não tem a anotação [@RequestParam]: para um parâmetro cujo tipo não é um tipo "simples" (string, número, data etc.), o [Spring MVC] subentende a anotação [@ModelAttribute], que poderia ter sido escrita. O parâmetro é então um objeto de comando ([command object]), criado e preenchido pelo data binding como acabamos de descrever. Os parâmetros da query que não correspondem a nenhum setter são ignorados;
  • linha 21: a anotação [@Valid] (de [jakarta.validation]) solicita que o objeto seja validado depois de preenchido, verificando as restrições de seus campos. Se o data binding ou a validação falhar, o [Spring MVC] lança a exceção [MethodArgumentNotValidException]: a action não é executada, e a resposta é um erro 400. Isso equivale ao atributo [[ApiController]] do [ASP.NET Core MVC];
  • linhas 22–25: a action devolve a pessoa recebida e o tipo de sua idade. [LinkedHashMap] é um dicionário que preserva a ordem de inserção de suas chaves: o JSON as exibirá nessa ordem.

O arquivo [application.properties] do exemplo tem duas linhas adicionais:

1
2
3
4
5
6
# a porta de escuta do servidor (8080 por padrão)
server.port=5000
# as respostas de erro do Spring Boot não contêm a pilha de chamadas
spring.web.error.include-stacktrace=never
# as respostas de erro detalham os erros de validação
spring.web.error.include-binding-errors=always
  • Linha 6: Quando a resposta de erro resulta de uma verificação de validação, ela contém a lista de erros (campo [errors]). As ferramentas de desenvolvimento já habilitam isso; esta linha o mantém habilitado em produção. Sem ela, e sem as ferramentas de desenvolvimento, a resposta de erro se reduz a [{"timestamp":"...","status":400,"error":"Bad Request","path":"/persons/action01"}]: o cliente fica sabendo que sua requisição está incorreta, mas não o motivo.

Uma requisição válida, com um parâmetro [pirate] que não corresponde a nenhum campo:

curl -i "http://localhost:5000/persons/action01?name=martin&age=42&title=Mr&pirate=1"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 83

{"person":{"age":42,"email":null,"name":"martin","title":"Mr"},"ageType":"Integer"}

A idade é de fato um número (um [Integer]), e o parâmetro [pirate] foi ignorado. As propriedades da pessoa são ordenadas alfabeticamente: essa é a configuração padrão do [Jackson] 3, a biblioteca JSON usada pelo [Spring MVC]. Uma query inválida (o JSON de resposta foi formatado para facilitar a leitura: uma propriedade por linha):

curl -i "http://localhost:5000/persons/action01?name=m&age=abc&title=Dr&email=xx"
HTTP/1.1 400
Content-Type: application/json

{
  "timestamp": "2026-09-25T16:46:41.520Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed for object='personModel'. Error count: 4",
  "errors": [
    {
      "arguments": [{"arguments":null,"code":"age","codes":["personModel.age","age"],"defaultMessage":"age"}],
      "bindingFailure": true,
      "code": "typeMismatch",
      "codes": ["typeMismatch.personModel.age","typeMismatch.age","typeMismatch.java.lang.Integer","typeMismatch"],
      "defaultMessage": "Failed to convert property value of type 'java.lang.String' to required type 'java.lang.Integer' for property 'age'; For input string: \"abc\"",
      "field": "age",
      "objectName": "personModel",
      "rejectedValue": "abc"
    },
    {
      "objectName": "personModel",
      "field": "email",
      "rejectedValue": "xx",
      "codes": ["Email.personModel.email","Email.email","Email.java.lang.String","Email"],
      "arguments": [{"arguments":null,"code":"email","codes":["personModel.email","email"],"defaultMessage":"email"},[],{"arguments":null,"codes":[".*"],"defaultMessage":".*"}],
      "bindingFailure": false,
      "code": "Email",
      "defaultMessage": "invalid email address"
    },
    {
      "objectName": "personModel",
      "field": "title",
      "rejectedValue": "Dr",
      "codes": ["Pattern.personModel.title","Pattern.title","Pattern.java.lang.String","Pattern"],
      "arguments": [{"arguments":null,"code":"title","codes":["personModel.title","title"],"defaultMessage":"title"},[],{"arguments":null,"codes":["Mr|Mme|Melle"],"defaultMessage":"Mr|Mme|Melle"}],
      "bindingFailure": false,
      "code": "Pattern",
      "defaultMessage": "unknown title"
    },
    {
      "objectName": "personModel",
      "field": "name",
      "rejectedValue": "m",
      "codes": ["Size.personModel.name","Size.name","Size.java.lang.String","Size"],
      "arguments": [{"arguments":null,"code":"name","codes":["personModel.name","name"],"defaultMessage":"name"},20,2],
      "bindingFailure": false,
      "code": "Size",
      "defaultMessage": "the name must have 2 to 20 characters"
    }
  ],
  "path": "/persons/action01"
}

A action não foi executada. O campo [errors] lista os erros, um por campo rejeitado. Para cada um:

  • [field], [rejectedValue]: o campo e o valor rejeitado;
  • [defaultMessage]: a mensagem de erro; é a mais útil;
  • [code]: o nome da restrição violada ([Size], [Email]...) ou [typeMismatch] para um erro de conversão; [bindingFailure] é igual a [true] para um erro de conversão (o erro ocorreu durante a vinculação, antes da validação);
  • [codes], [arguments]: chaves e valores usados para procurar a mensagem em um arquivo de mensagens. É assim que a mensagem de erro em inglês para o erro de conversão (chave [typeMismatch...]) será substituída por uma mensagem personalizada, como mostrado no Exemplo 19.

A ordem dos erros não é garantida: ela pode mudar de uma execução para outra. O mesmo vale sem nenhum parâmetro:

curl -i http://localhost:5000/persons/action01
HTTP/1.1 400
Content-Type: application/json

{
  "timestamp": "2026-09-25T16:46:41.574Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed for object='personModel'. Error count: 3",
  "errors": [
    {
      "objectName": "personModel",
      "field": "age",
      "rejectedValue": null,
      "codes": ["NotNull.personModel.age","NotNull.age","NotNull.java.lang.Integer","NotNull"],
      "arguments": [{"arguments":null,"code":"age","codes":["personModel.age","age"],"defaultMessage":"age"}],
      "bindingFailure": false,
      "code": "NotNull",
      "defaultMessage": "the age is required"
    },
    {
      "objectName": "personModel",
      "field": "title",
      "rejectedValue": null,
      "codes": ["NotNull.personModel.title","NotNull.title","NotNull.java.lang.String","NotNull"],
      "arguments": [{"arguments":null,"code":"title","codes":["personModel.title","title"],"defaultMessage":"title"}],
      "bindingFailure": false,
      "code": "NotNull",
      "defaultMessage": "the title is required"
    },
    {
      "objectName": "personModel",
      "field": "name",
      "rejectedValue": null,
      "codes": ["NotBlank.personModel.name","NotBlank.name","NotBlank.java.lang.String","NotBlank"],
      "arguments": [{"arguments":null,"code":"name","codes":["personModel.name","name"],"defaultMessage":"name"}],
      "bindingFailure": false,
      "code": "NotBlank",
      "defaultMessage": "the name is required"
    }
  ],
  "path": "/persons/action01"
}

Apenas uma mensagem por campo: As restrições [@Size] e [@Pattern] aceitam o valor [null]; somente [@NotBlank] e [@NotNull] o rejeitam. Assim como [@RequestParam], o data binding diferencia maiúsculas de minúsculas: com [?NAME=martin&age=42&title=Mr], você obtém o erro “o nome é obrigatório”, porque [NAME] não corresponde a nenhum setter.

3.2.1. Por que uma classe JavaBean e não um record?

A partir do [Java] 16, um record de uma única linha descreve uma classe de dados não modificável: [record Point(int x, int y) {}] declara os campos [x] e [y], um construtor que recebe todos eles e os métodos de leitura [x()] e [y()]. Um record não tem setters. [Spring MVC] sabe preencher um record: ele chama o construtor com os parâmetros da query (isso se chama binding por construtor). Vamos substituir, só para ver, a classe [PersonModel] pelo record equivalente (a action então lê a idade usando [person.age()]):

public record PersonModel(
    @NotBlank(message = "the name is required")
    @Size(min = 2, max = 20, message = "the name must have 2 to 20 characters")
    String name,
    @NotNull(message = "the age is required")
    @Min(value = 0, message = "the age must be between 0 and 150")
    @Max(value = 150, message = "the age must be between 0 and 150")
    Integer age,
    @NotNull(message = "the title is required")
    @Pattern(regexp = "Mr|Mme|Melle", message = "unknown title")
    String title,
    @Email(message = "invalid email address")
    String email) {
}

Uma query válida retorna o mesmo resultado, exceto pela ordem das propriedades do JSON: as propriedades de um record são escritas na ordem de seus componentes ([{"name":"martin","age":42,"title":"Mr","email":null}]). Mas a query inválida anterior agora retorna apenas um erro:

curl -i "http://localhost:5000/persons/action01?name=m&age=abc&title=Dr&email=xx"
HTTP/1.1 400
Content-Type: application/json

{
  "timestamp": "2026-09-25T16:47:45.491Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed for object='personModel'. Error count: 1",
  "errors": [
    {
      "arguments": [{"arguments":null,"code":"age","codes":["personModel.age","age"],"defaultMessage":"age"}],
      "bindingFailure": true,
      "code": "typeMismatch",
      "codes": ["typeMismatch.personModel.age","typeMismatch.age","typeMismatch.java.lang.Integer","typeMismatch"],
      "defaultMessage": "Failed to convert value of type 'java.lang.String' to required type 'java.lang.Integer'; For input string: \"abc\"",
      "field": "age",
      "objectName": "personModel",
      "rejectedValue": "abc"
    }
  ],
  "path": "/persons/action01"
}

A conversão da idade falhou; portanto, o construtor do record não pôde ser chamado, porque um de seus parâmetros ficou sem valor; sem objeto, não há validação: os erros no nome, no título e no endereço de e-mail não são relatados. Com um JavaBean, por outro lado, cada setter é chamado de forma independente: um campo convertido incorretamente fica em branco e recebe um erro de conversão, enquanto os demais são preenchidos, e a validação prossegue (exemplo 09). Para um formulário HTML, em que o objetivo é relatar todos os erros de uma só vez, isso é essencial: todos os formulários deste curso são, portanto, formulários JavaBean. Um record continua sendo válido para um modelo cujos campos não podem ter erros de conversão: é o caso do Exemplo 10.

Essa rejeição automática é adequada para um servidor JSON, consultado por um cliente [JavaScript] que exibe os erros à sua maneira. Para uma aplicação HTML, um erro JSON não faz sentido: o objetivo é reexibir o formulário com seus erros. O exemplo a seguir mostra como manter o controle.

3.3. Exemplo 09: Validação realizada pela action

A classe [PersonModel] do Exemplo 09 é idêntica à do Exemplo 08; apenas o controller muda. O arquivo [controllers/PersonsController.java]:

package example09.controllers;

import java.util.stream.Collectors;

import org.springframework.http.MediaType;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import example09.models.PersonModel;
import jakarta.validation.Valid;

@RestController
@RequestMapping("/persons")
public class PersonsController {

    // um parâmetro BindingResult, logo após o modelo: a ação é SEMPRE
    // executada, e é ela que decide o que fazer com um modelo inválido
    @GetMapping(value = "/action01", produces = MediaType.TEXT_HTML_VALUE)
    public String action01(@Valid PersonModel person, BindingResult result) {
        // result: o resultado do binding E da validação do modelo
        if (!result.hasErrors()) {
            return "<p>Welcome %s %s (%d years old)</p>".formatted(person.getTitle(), person.getName(), person.getAge());
        }
        // os erros, campo por campo
        String items = result.getFieldErrors().stream()
                .map(error -> "<li>%s: %s</li>".formatted(error.getField(), error.getDefaultMessage()))
                .collect(Collectors.joining());
        return "<p>The form contains errors:</p><ul>" + items + "</ul>";
    }
}

Vamos analisar este código:

  • Linha 20: O atributo [produces] de [@GetMapping] define o tipo da resposta: [MediaType.TEXT_HTML_VALUE] é a constante ["text/html"]. A string devolvida pela action é, portanto, enviada como uma página HTML;
  • linha 21: a action tem um segundo parâmetro, do tipo [BindingResult], colocado imediatamente após o modelo validado. Sua presença muda tudo: em caso de erro de binding ou de validação, o [Spring MVC] deixa de lançar uma exceção; ele armazena os erros neste [BindingResult] e executa a action, que decide o que fazer com eles. [BindingResult] desempenha o mesmo papel que [ModelState] no [ASP.NET Core MVC];
  • linhas 23–25: [hasErrors()] indica se há erros. Se não houver nenhum, uma página de boas-vindas ([%d] é substituído por um inteiro);
  • linhas 27–29: caso contrário, a lista de erros. [getFieldErrors()] devolve a lista de erros associados a um campo ([FieldError]), junto com o nome do campo ([getField()]) e a mensagem ([getDefaultMessage()]). O processamento usa a API de [Java] streams ([Stream]): [stream()] gera os itens da lista um a um, [map] transforma cada um (neste caso, um erro em uma linha: HTML [<li>]), [collect(Collectors.joining())] concatena tudo em uma string. O argumento de [map] é uma lambda: uma função anônima, escrita como [parameter -> expression];
  • linha 30: uma página que lista os erros. Em ambos os casos, a resposta tem código de status 200.

Uma requisição válida em um navegador:

Image

Uma requisição inválida:

Image

Um erro de conversão aparece em [BindingResult] como um erro de validação, mas não impede que os demais campos sejam validados:

curl -i "http://localhost:5000/persons/action01?name=m&age=abc&title=Mr"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 247

<p>The form contains errors:</p><ul><li>age: Failed to convert property value of type 'java.lang.String' to required type 'java.lang.Integer' for property 'age'; For input string: "abc"</li><li>name: the name must have 2 to 20 characters</li></ul>

Esta é a técnica que todos os formulários do estudo de caso usarão (veja o Exemplo 19): A action recebe o formulário (um JavaBean anotado com [@Valid]) seguido de um [BindingResult], e reexibe o formulário se houver erros.

3.4. Exemplo 10: Parâmetros múltiplos

Um mesmo parâmetro pode aparecer várias vezes em uma requisição: é o caso das caixas de seleção de um formulário ou de uma lista de seleção múltipla ([?color=red&color=green]).

O arquivo [controllers/ArraysController.java]:

package example10.controllers;

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

import org.springframework.validation.BindingResult;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import example10.models.ChoiceModel;
import jakarta.validation.Valid;

@RestController
@RequestMapping("/arrays")
public class ArraysController {

    // /arrays/action01?color=red&color=green: um parâmetro simples
    @GetMapping("/action01")
    public Map<String, String> action01(@RequestParam(required = false) String color) {
        Map<String, String> response = new LinkedHashMap<>();
        response.put("color", color);
        return response;
    }

    // /arrays/action02?color=red&color=green: uma lista
    @GetMapping("/action02")
    public Map<String, Object> action02(@RequestParam(required = false) List<String> color) {
        List<String> colors = color == null ? List.of() : color;
        Map<String, Object> response = new LinkedHashMap<>();
        response.put("color", colors);
        response.put("count", colors.size());
        return response;
    }

    // /arrays/action03?color=red: uma lista, validada por ChoiceModel
    @GetMapping("/action03")
    public Map<String, Object> action03(@Valid ChoiceModel choice, BindingResult result) {
        Map<String, Object> response = new LinkedHashMap<>();
        response.put("colors", choice.color());
        response.put("valid", !result.hasErrors());
        response.put("errors", result.getAllErrors().stream().map(ObjectError::getDefaultMessage).toList());
        return response;
    }
}

A action [action01] (linhas 22–27) mostra o que um único parâmetro recebe:

curl -i "http://localhost:5000/arrays/action01?color=red"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 15

{"color":"red"}
curl -i "http://localhost:5000/arrays/action01?color=red&color=green"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 21

{"color":"red,green"}

Um parâmetro do tipo [String] que recebe vários valores os concatena, separados por vírgulas: ["red,green"]. Isso é uma armadilha: você acha que está recebendo uma única cor, mas na verdade recebe uma lista de cores disfarçada. Um parâmetro do tipo lista ([action02], linhas 30–37) recebe todos eles, cada um em um elemento separado da lista. [List<String>] é uma lista de strings; [List.of()] (linha 32) é uma lista vazia, que substitui [null] quando o parâmetro está ausente:

curl -i "http://localhost:5000/arrays/action02?color=red"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 27

{"color":["red"],"count":1}
curl -i "http://localhost:5000/arrays/action02?color=red&color=green"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 35

{"color":["red","green"],"count":2}
curl -i "http://localhost:5000/arrays/action02"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 22

{"color":[],"count":0}

Inversamente, um único valor contendo vírgulas é dividido:

curl -i "http://localhost:5000/arrays/action02?color=red,green"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 35

{"color":["red","green"],"count":2}

Converter uma string em uma lista, assim como converter uma lista em uma string, usa a vírgula como separador. Também poderíamos ter declarado um array ([String[] color]). Resta apenas validar a lista. O arquivo [models/ChoiceModel.java]:

package example10.models;

import java.util.List;

import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;

// uma lista, e uma restrição em CADA elemento da lista:
// a anotação @Pattern é colocada DENTRO do tipo genérico List<...>
public record ChoiceModel(

        @Size(min = 1, message = "choose at least one color")
        List<@Pattern(regexp = "red|green|blue", message = "unknown color: ${validatedValue}") String> color) {

    // o construtor "compacto" de um record: uma lista ausente se torna uma lista vazia
    public ChoiceModel {
        color = color == null ? List.of() : color;
    }
}

Vamos comentar este código:

  • linha 10: [ChoiceModel] é um record de um único campo (veja os exemplos 03 e 08), [color]. O binding por construtor não representa problema aqui: uma lista de strings não pode resultar em um erro de conversão;
  • linha 12: [@Size(min = 1)], quando aplicada a uma lista, refere-se ao número de elementos da lista: deve haver pelo menos um;
  • linha 13: a anotação [@Pattern] é colocada dentro do tipo genérico, antes de [String]: ela não se aplica à lista, mas a cada um de seus elementos. Cada cor deve ser [red], [green], or [blue]. Na mensagem, [${validatedValue}] é substituído pelo valor rejeitado;
  • linhas 16–18: o construtor compacto de um record: um bloco executado no início do construtor, antes de os campos serem atribuídos, que pode modificar seus parâmetros. Aqui, uma lista ausente ([null]) se torna uma lista vazia.

A action [action03] do controller [ArraysController] recebe um [ChoiceModel] validado, seguido de um [BindingResult], e devolve seu conteúdo junto com o status da validação. [choice.color()] lê o campo do record. [result.getAllErrors()] devolve todos os erros, e [ObjectError::getDefaultMessage] é uma referência de método: uma notação abreviada para a lambda [error -> error.getDefaultMessage()]. [toList()] coleta o stream em uma lista.

curl -i "http://localhost:5000/arrays/action03?color=red&color=green"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 51

{"colors":["red","green"],"valid":true,"errors":[]}
curl -i "http://localhost:5000/arrays/action03?color=red&color=black"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 74

{"colors":["red","black"],"valid":false,"errors":["unknown color: black"]}
curl -i "http://localhost:5000/arrays/action03"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 66

{"colors":[],"valid":false,"errors":["choose at least one color"]}

[ASP.NET Core MVC] exigia um método de validação escrito em [C#] para verificar cada item da lista; com o [Bean Validation], basta uma anotação no tipo genérico.

3.5. Exemplo 11: Os parâmetros de uma requisição POST

Um formulário HTML enviado pelo método POST coloca seus campos no corpo da requisição, e não na URL. O arquivo [controllers/PostController.java]:

package example11.controllers;

import java.util.LinkedHashMap;
import java.util.Map;

import org.springframework.util.MultiValueMap;
import org.springframework.validation.BindingResult;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import example11.models.PersonModel;
import jakarta.validation.Valid;
import tools.jackson.databind.JsonNode;

@RestController
@RequestMapping("/post")
public class PostController {

    // os campos de um formulário HTML (corpo application/x-www-form-urlencoded)
    @PostMapping("/action01")
    public Map<String, Object> action01(@RequestHeader("Content-Type") String type,
            @RequestParam MultiValueMap<String, String> fields) {
        Map<String, Object> response = new LinkedHashMap<>();
        response.put("receivedType", type);
        response.put("fields", fields);
        return response;
    }

    // um corpo JSON: @RequestBody o desserializa
    @PostMapping("/action02")
    public Map<String, Object> action02(@RequestHeader("Content-Type") String type, @RequestBody JsonNode body) {
        Map<String, Object> response = new LinkedHashMap<>();
        response.put("receivedType", type);
        response.put("body", body);
        return response;
    }

    // um único campo do formulário: @RequestParam, como para um parâmetro de URL
    @PostMapping("/action03")
    public String action03(@RequestParam(required = false) String name) {
        return "name = [%s]".formatted(name);
    }

    // os campos do formulário, vinculados e validados pela classe PersonModel
    @PostMapping("/action04")
    public Map<String, Object> action04(@Valid PersonModel person, BindingResult result) {
        Map<String, Object> response = new LinkedHashMap<>();
        response.put("person", person);
        response.put("valid", !result.hasErrors());
        response.put("errors", result.getAllErrors().stream().map(ObjectError::getDefaultMessage).sorted().toList());
        return response;
    }
}

Vamos comentar este código:

  • linha 25: [@PostMapping] associa a action às requisições POST, assim como [@GetMapping] o faz com as requisições GET;
  • linha 26: [@RequestHeader("Content-Type")] fornece o valor de um cabeçalho da requisição: neste caso, o tipo de seu corpo;
  • linha 27: um parâmetro do tipo [MultiValueMap<String, String>], anotado com [@RequestParam], recebe todos os parâmetros da requisição. Um [MultiValueMap] é um dicionário em que cada chave está associada a uma lista de valores: ele conserva todos os valores de um parâmetro repetido, ao passo que o [Map<String, String>] do Exemplo 07 conservaria apenas um;
  • Linha 36: [@RequestBody] instrui o sistema a ler o corpo da requisição e a desserializá-lo, ou seja, convertê-lo em um objeto [Java]. O corpo deve ser um documento JSON (que é o que um cliente [JavaScript] envia), lido pela biblioteca [Jackson]. [JsonNode] representa qualquer documento JSON; poderíamos ter declarado uma classe ou um record. Linha 18: No [Jackson] 3, usado pelo [Spring Boot] 4, as classes estão no pacote [tools.jackson.databind] (e não mais em [com.fasterxml.jackson.databind] como no [Jackson] 2);
  • linhas 44–45: [@RequestParam] lê um campo de formulário exatamente como um parâmetro da URL;
  • linhas 50–51: o formulário inteiro, vinculado e validado pela classe [PersonModel] (uma cópia, no pacote [example11.models], da classe do Exemplo 08) (um objeto de comando, como no Exemplo 09);
  • linha 55: [sorted()] ordena as mensagens para que a ordem dos erros permaneça consistente de uma execução para outra.

A opção [-d] do [curl] envia uma requisição POST com um corpo no formato de um formulário HTML ([application/x-www-form-urlencoded]):

curl -i -d "name=martin&age=42" http://localhost:5000/post/action01
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 94

{"receivedType":"application/x-www-form-urlencoded","fields":{"name":["martin"],"age":["42"]}}

Cada campo está associado a uma lista de valores, que neste caso contém apenas um valor. O mesmo conteúdo em formato JSON:

curl -i -H "Content-Type: application/json" -d '{"name":"martin","age":42}' http://localhost:5000/post/action02
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 69

{"receivedType":"application/json","body":{"name":"martin","age":42}}

(A opção [-H] do [curl] adiciona um cabeçalho à requisição; no [Windows], no prompt de comando, você digitaria [-d "{\"name\":\"martin\",\"age\":42}"]). No primeiro caso, a idade é uma string (um formulário HTML transporta apenas texto) e, no segundo, é um número. O [Spring MVC] seleciona o conversor que lê o corpo com base no cabeçalho [Content-Type] da requisição. Uma action [@RequestBody] que espera JSON rejeita, portanto, um corpo de tipo diferente, retornando um erro 415 ([Unsupported Media Type], tipo de conteúdo não suportado):

curl -i -d "name=martin&age=42" http://localhost:5000/post/action02
1
2
3
4
5
HTTP/1.1 415
Accept: application/json, application/*+json
Content-Type: application/json

{"timestamp":"2026-09-25T16:48:45.851Z","status":415,"error":"Unsupported Media Type","message":"Content-Type 'application/x-www-form-urlencoded;charset=UTF-8' is not supported.","path":"/post/action02"}

O cabeçalho de resposta [Accept] lista os tipos aceitos. Um corpo JSON inválido, por outro lado, resulta em um erro 400:

curl -i -H "Content-Type: application/json" -d '{"name":"martin",' http://localhost:5000/post/action02
1
2
3
4
HTTP/1.1 400
Content-Type: application/json

{"timestamp":"2026-09-25T16:48:45.879Z","status":400,"error":"Bad Request","message":"JSON parse error: Unexpected end-of-input within/between Object entries","path":"/post/action02"}

As outras duas actions:

curl -i -d "name=martin&age=42" http://localhost:5000/post/action03
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 15

name = [martin]
curl -i -d "name=martin&age=42&title=Mme" http://localhost:5000/post/action04
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 89

{"person":{"age":42,"email":null,"name":"martin","title":"Mme"},"valid":true,"errors":[]}
curl -i -d "name=martin&age=200" http://localhost:5000/post/action04
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 149

{"person":{"age":200,"email":null,"name":"martin","title":null},"valid":false,"errors":["the age must be between 0 and 150","the title is required"]}

[@RequestParam] e os objetos de comando não distinguem a URL do corpo: eles tratam os parâmetros da URL e os campos do formulário como um todo único. Um parâmetro presente nos dois locais recebe, portanto, dois valores:

curl -i "http://localhost:5000/post/action03?name=durand" -d "name=martin"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 22

name = [durand,martin]

Uma action POST responde com o código de status 200, assim como uma action GET. Em uma aplicação HTML, uma action POST responde com uma página (o formulário reexibido) ou com um redirecionamento (veja o Exemplo 20).

3.6. Exemplo 12: Data binding e validação personalizados

O data binding e a validação podem ser estendidos. O estudo de caso os utiliza de forma moderada, mas compreendê-los ajuda a esclarecer o funcionamento do [Spring MVC].

12-custom-binding/
├── src/main/java/example12/
│   ├── controllers/
│   │   └── ExamplesController.java
│   ├── binding/
│   │   ├── DateFrConverter.java
│   │   ├── Language.java
│   │   ├── LanguageResolver.java
│   │   ├── NoSpace.java
│   │   ├── NoSpaceValidator.java
│   │   └── WebConfig.java
│   └── Example12Application.java
├── src/main/resources/
│   └── application.properties
└── pom.xml

3.6.1. Um conversor: DateFrConverter

Para converter a string ["42"] em [int], o [Spring MVC] usa um conversor ([Converter]). Ele fornece conversores para todos os tipos comuns; você pode escrever os seus. O arquivo [binding/DateFrConverter.java]:

package example12.binding;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.format.ResolverStyle;

import org.springframework.core.convert.converter.Converter;

// um conversor: transforma uma data francesa "23/09/2026" em um LocalDate.
// Ele será usado para QUALQUER parâmetro do tipo LocalDate (veja WebConfig)
public class DateFrConverter implements Converter<String, LocalDate> {

    // uuuu: o ano; STRICT: "31/02/2026" é rejeitada (e não convertida para 28 de fevereiro)
    private static final DateTimeFormatter FORMAT =
            DateTimeFormatter.ofPattern("dd/MM/uuuu").withResolverStyle(ResolverStyle.STRICT);

    @Override
    public LocalDate convert(String text) {
        try {
            return LocalDate.parse(text, FORMAT);
        } catch (DateTimeParseException e) {
            // falha: uma exceção, que o Spring transforma em um erro de conversão
            throw new IllegalArgumentException("[" + text + "] is not a valid dd/mm/yyyy date");
        }
    }
}
  • linha 12: um conversor implementa a interface genérica [Converter<S, T>], em que [S] é o tipo de origem e [T] é o tipo de destino: aqui, de [String] para [LocalDate] (uma data sem horário);
  • linhas 15–16: o formato da data, [dd/mm/yyyy]. No modo [STRICT], uma data que não existe (31/02/2026) é rejeitada; esse modo exige escrever o ano como [uuuu] em vez de [yyyy];
  • linhas 19–21: O único método da interface, [convert], devolve a data resultante;
  • linhas 22–25: Se a conversão falhar, o conversor lança uma exceção. [Spring MVC] produz um erro de conversão, assim como com [?age=abc]: erro 400 para um [@RequestParam], erro [typeMismatch] no [BindingResult] para um campo de um objeto de comando. Nossa exceção é mantida como a causa do erro de conversão: recuperaremos sua mensagem no controller.

3.6.2. Um argument resolver: a anotação @Language e o LanguageResolver

Um parâmetro de action pode vir de uma fonte diferente da URL ou do formulário. Para cada parâmetro de uma action, o [Spring MVC] consulta uma lista de objetos chamados [argument resolvers] (“resolvedores de argumentos”): o primeiro que declarar poder tratar o parâmetro fornece seu valor. É assim que [@RequestParam], [@RequestHeader], [@RequestBody] e assim por diante funcionam. Você pode adicionar os seus. Primeiro, é preciso uma forma de identificar os parâmetros em questão: uma anotação “personalizada”. O arquivo [binding/Language.java]:

package example12.binding;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

// uma anotação "caseira": @Language String language. Ela não faz nada por
// si só: marca um parâmetro, que o LanguageResolver saberá preencher.
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Language {
}
  • linha 12: [@interface] declara uma anotação. Esta anotação não tem atributos;
  • linha 10: [@Target] especifica onde a anotação pode ser colocada: neste caso, somente em um parâmetro de método;
  • linha 11: [@Retention(RetentionPolicy.RUNTIME)]: a anotação é preservada no código compilado e pode ser lida em tempo de execução. Isso é essencial para que o [Spring MVC] a reconheça.

O arquivo [binding/LanguageResolver.java]:

package example12.binding;

import org.springframework.core.MethodParameter;
import org.springframework.web.bind.support.WebDataBinderFactory;
import org.springframework.web.context.request.NativeWebRequest;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.method.support.ModelAndViewContainer;

// um "argument resolver": ele fornece o valor dos parâmetros anotados com @Language,
// lido do cabeçalho "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr"
public class LanguageResolver implements HandlerMethodArgumentResolver {

    // este resolver trata este parâmetro?
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(Language.class) && parameter.getParameterType() == String.class;
    }

    // o valor do parâmetro
    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
            NativeWebRequest request, WebDataBinderFactory binderFactory) {
        String header = request.getHeader("Accept-Language");
        String first = header == null ? "" : header.split(",")[0].trim();
        return first.length() >= 2 ? first.substring(0, 2).toLowerCase() : "fr";
    }
}
  • linha 11: um resolver implementa a interface [HandlerMethodArgumentResolver];
  • linhas 14–17: [supportsParameter] devolve [true] para os parâmetros que ele trata: aqueles marcados com a anotação [@Language] e do tipo [String]. [MethodParameter] descreve um parâmetro da action;
  • Linhas 20–26: [resolveArgument] fornece o valor do parâmetro. Entre seus argumentos, [NativeWebRequest] dá acesso à requisição. Linha 23: o cabeçalho [Accept-Language], que especifica os idiomas preferidos do usuário. Linhas 24–25: As duas primeiras letras do primeiro idioma, em minúsculas, ou ["fr"] se o cabeçalho estiver ausente. O operador [? :] devolve seu segundo operando se a condição for verdadeira e, caso contrário, o terceiro operando.

3.6.3. Uma restrição de validação: @NoSpace

Uma restrição de validação personalizada consiste em dois elementos: uma anotação e a classe que realiza a validação. O arquivo [binding/NoSpace.java]:

package example12.binding;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;

// uma restrição de validação "caseira": @NoSpace.
// @Constraint designa a classe que faz a verificação.
@Target({ ElementType.FIELD, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = NoSpaceValidator.class)
public @interface NoSpace {

    // a mensagem de erro padrão
    String message() default "the field must not contain any space";

    // dois atributos exigidos pelo padrão Bean Validation (raramente usados)
    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}
  • linha 13: a restrição pode ser aplicada a um campo de classe ou a um parâmetro de método;
  • linha 15: [@Constraint] transforma a anotação em uma restrição [Bean Validation] e especifica a classe que a valida;
  • linha 19: a mensagem de erro padrão. Um atributo de anotação é declarado como um método sem parâmetros, e [default] lhe dá um valor padrão: escreveríamos [@NoSpace] ou [@NoSpace(message = "...")];
  • linhas 22–24: dois atributos exigidos pelo padrão: [groups] permite verificar apenas um subconjunto das restrições, e [payload] permite anexar informações a uma restrição. Não os utilizamos, mas eles precisam ser declarados.

O arquivo [binding/NoSpaceValidator.java]:

package example12.binding;

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

// a verificação da restrição @NoSpace, para um valor do tipo String
public class NoSpaceValidator implements ConstraintValidator<NoSpace, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // null é aceito: exigi-lo é tarefa de @NotNull
        return value == null || !value.contains(" ");
    }
}
  • linha 7: a classe de validação implementa [ConstraintValidator<A, T>], em que [A] é a anotação e [T] é o tipo dos valores validados;
  • Linhas 10–13: [isValid] devolve [true] se o valor for aceitável. O valor [null] é aceito, pois satisfaz todas as restrições padrão, exceto [@NotNull] e [@NotBlank].

3.6.4. Configuração: WebConfig

O conversor e o resolver precisam ser declarados no [Spring MVC]; a restrição é identificada pela anotação [@Constraint]. O arquivo [binding/WebConfig.java]:

package example12.binding;

import java.util.List;

import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

// WebMvcConfigurer: uma classe de configuração que complementa a do Spring MVC.
// Sobrescrevemos os métodos que nos interessam.
@Configuration
public class WebConfig implements WebMvcConfigurer {

    // os conversores: String -> LocalDate
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new DateFrConverter());
    }

    // os "argument resolvers": os parâmetros @Language
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new LanguageResolver());
    }
}
  • Linha 12: [@Configuration] designa uma classe de configuração: [Spring Boot] a descobre na inicialização (ela está em um subpacote daquele que contém a classe [Example12Application]), cria uma instância dela e a utiliza;
  • Linha 13: A interface [WebMvcConfigurer] permite estender a configuração do [Spring MVC] estabelecida pelo [Spring Boot], sem substituí-la. Ela tem muitos métodos, que por padrão não fazem nada; sobrescrevemos ([@Override]) aqueles que nos interessam;
  • linhas 16–19: [addFormatters] registra conversores. [DateFrConverter] será usado para qualquer parâmetro do tipo [LocalDate] na aplicação;
  • Linhas 22–25: [addArgumentResolvers] adiciona resolvers à lista dos que existem no [Spring MVC].

3.6.5. O controller

O arquivo [controllers/ExamplesController.java]:

package example12.controllers;

import java.time.LocalDate;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.method.annotation.HandlerMethodValidationException;
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;

import example12.binding.Language;
import example12.binding.NoSpace;

@RestController
@RequestMapping("/examples")
public class ExamplesController {

    // /examples/schedule?day=23/09/2026: um conversor personalizado (DateFrConverter)
    @GetMapping("/schedule")
    public String schedule(@RequestParam LocalDate day) {
        return "schedule for the day [" + day + "]";
    }

    // /examples/hello: um parâmetro que não vem da URL, mas de um cabeçalho
    @GetMapping("/hello")
    public String hello(@Language String language) {
        return "en".equals(language) ? "Hello!" : "Bonjour !";
    }

    // /examples/search?keyword=spring: uma restrição de validação personalizada,
    // colocada diretamente em um parâmetro da ação
    @GetMapping("/search")
    public String search(@RequestParam(required = false) @NoSpace String keyword) {
        return "search for [" + keyword + "]";
    }

    // ——— erros
    // @ExceptionHandler: um método do controller que transforma uma exceção lançada
    // por uma de suas ações (ou pelo binding de seus parâmetros) em uma resposta

    // uma conversão impossível (DateFrConverter lançou uma exceção)
    @ExceptionHandler
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String conversion(MethodArgumentTypeMismatchException e) {
        // a exceção original, a do DateFrConverter: sua mensagem é nossa
        return e.getMostSpecificCause().getMessage();
    }

    // um parâmetro que viola uma restrição de validação (@NoSpace)
    @ExceptionHandler
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String validation(HandlerMethodValidationException e) {
        return e.getAllErrors().get(0).getDefaultMessage();
    }
}
  • linha 24: um parâmetro comum do tipo [LocalDate]: não há nenhuma indicação de que [DateFrConverter] deva ser usado; é o tipo que determina isso;
  • linha 30: o parâmetro [language] é fornecido pelo [LanguageResolver], por meio da anotação [@Language];
  • linha 37: Uma restrição de validação também pode ser aplicada diretamente a um parâmetro de action (aqui, com [@RequestParam]). Não há necessidade de [@Valid]: [Spring MVC] valida automaticamente os parâmetros que têm uma restrição. Se a validação falhar, ele lança a exceção [HandlerMethodValidationException];
  • linhas 46–51: um método anotado com [@ExceptionHandler] é um tratador de exceções: se uma action do controller, ou o binding de seus parâmetros, lançar uma exceção do mesmo tipo que seu parâmetro (aqui, [MethodArgumentTypeMismatchException], uma falha de conversão), o [Spring MVC] o chama em vez de gerar sua própria resposta de erro. O que ele devolve torna-se a resposta, com o código definido por [@ResponseStatus]: 400 ([HttpStatus.BAD_REQUEST]). Linha 50: [getMostSpecificCause()] devolve a exceção original, aquela lançada pelo [DateFrConverter], que contém nossa mensagem;
  • Linhas 54–58: O mesmo se aplica à falha na validação de um parâmetro. [getAllErrors()] devolve a lista de erros, da qual retemos a mensagem do primeiro.

Sem esses dois tratadores, a resposta seria o erro JSON do [Spring Boot], com uma mensagem técnica em inglês para a data, que não incluiria a nossa. Um tratador de exceções se aplica apenas ao seu controller; no Exemplo 24, veremos como escrever um para a aplicação inteira ([@ControllerAdvice]).

Os resultados:

curl -i "http://localhost:5000/examples/schedule?day=23/09/2026"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 33

schedule for the day [2026-09-23]
curl -i "http://localhost:5000/examples/schedule?day=2026-09-23"
1
2
3
4
5
HTTP/1.1 400
Content-Type: text/plain;charset=UTF-8
Content-Length: 43

[2026-09-23] is not a valid dd/mm/yyyy date
curl -i "http://localhost:5000/examples/schedule?day=31/02/2026"
1
2
3
4
5
HTTP/1.1 400
Content-Type: text/plain;charset=UTF-8
Content-Length: 43

[31/02/2026] is not a valid dd/mm/yyyy date

Uma data [LocalDate] é escrita como [2026-09-23] quando convertida em string (formato ISO). O idioma:

curl -i -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:5000/examples/hello
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 9

Bonjour !
curl -i -H "Accept-Language: en-US,en;q=0.9" http://localhost:5000/examples/hello
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 6

Hello!

A restrição [@NoSpace]:

curl -i "http://localhost:5000/examples/search?keyword=spring"
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 19

search for [spring]
curl -i "http://localhost:5000/examples/search?keyword=spring%20mvc"
1
2
3
4
5
HTTP/1.1 400
Content-Type: text/plain;charset=UTF-8
Content-Length: 36

the field must not contain any space

([%20] é a codificação de um espaço em uma URL)

3.6.6. Conclusão

O modelo da action é construído vinculando dados da requisição: parâmetros da URL e campos de formulário ([@RequestParam], objeto de comando), o corpo JSON ([@RequestBody]), cabeçalhos ([@RequestHeader]) e tudo o que um resolver personalizado possa fornecer. Os valores são convertidos para o tipo do parâmetro e, em seguida, validados em relação às restrições do [Bean Validation] quando o modelo é anotado com [@Valid]. Um erro de conversão envolvendo um [@RequestParam], ou um modelo inválido sem um [BindingResult], resulta em um erro 400 sem executar a action: isso é apropriado para um servidor JSON. Para uma aplicação HTML, o formulário é um JavaBean anotado com [@Valid], seguido de um parâmetro [BindingResult] que a action consulta (exemplo 09), a fim de poder reexibir o formulário com seus erros. Esse é o assunto do próximo capítulo.