4. A view e seu modelo
Até este ponto, as actions geraram suas próprias respostas: texto, JSON e algumas tags HTML escritas como uma string. Em uma aplicação MVC, esse é o papel de uma view: um arquivo que descreve a página HTML, com marcadores de posição para os dados que a action lhe repassa, o modelo da view. [Spring MVC] não fornece uma linguagem de views por si só: ele pode trabalhar com várias engines de views ([Thymeleaf], [FreeMarker], [Mustache], [JSP]...). Este curso usa o [Thymeleaf], a engine de views mais utilizada junto com o [Spring MVC], que o [Spring Boot] consegue configurar sozinho.
Uma view [Thymeleaf] é um arquivo [.html] padrão: um arquivo HTML válido que pode ser aberto como está em um navegador. Os dados são inseridos nele por meio de atributos adicionais com o prefixo [th:] ([th:text], [th:if], [th:each]...), que o [Thymeleaf] executa no servidor e depois remove da página. É o que o [Thymeleaf] chama de templates naturais ([natural templates]): um designer gráfico pode trabalhar na view sem iniciar a aplicação, e o desenvolvedor adiciona a ela os atributos [th:]. Isso difere do [Razor], a engine de views do [ASP.NET Core MVC], que combina HTML e código [C#] precedido pelo caractere [@].
4.1. Exemplo 13: Uma primeira view
Para usar o [Thymeleaf], basta adicionar uma dependência ao arquivo [pom.xml] do exemplo:
- Linhas 3–6: o [spring-boot-starter-thymeleaf] starter. Um starter é uma dependência “tudo em um”: ele fornece o [Thymeleaf], sua integração com o [Spring] (a biblioteca [thymeleaf-spring6]) e a configuração automática do [Spring Boot], que os vincula ao [Spring MVC]. Não há mais nada a escrever: nenhuma versão (ela é definida pelo projeto pai [spring-boot-starter-parent]), nenhuma classe de configuração.
O modelo da view é uma classe simples. O arquivo [models/PageModel.java]:
- Linha 4: Um record [Java] (veja o Exemplo 03) é uma classe cujos campos são definidos de uma vez por todas pelo construtor: neste caso, três strings [title], [message], and [time]. O compilador gera automaticamente o construtor e os acessores que leem os campos para nós. Observação: esses acessores têm o nome do campo ([title()]), e não [getTitle()] como em uma classe chamada [JavaBean] (veja o Exemplo 08). É uma forma concisa de escrever uma classe que apenas transporta dados.
O arquivo [controllers/ViewsController.java]:
Vamos comentar este código:
- Linha 17: A anotação [@Controller] substitui a anotação [@RestController] dos exemplos anteriores. Com [@RestController], o que uma action devolve é a resposta (texto, JSON). Com [@Controller], uma action que devolve uma string devolve o nome de uma view: é a view que gerará a resposta;
- linha 25: a action recebe um parâmetro do tipo [Model], fornecido pelo [Spring MVC]. Este é o modelo da view: um dicionário, em que cada entrada (um atributo) associa um nome a um objeto;
- Linhas 26–30: A action cria um objeto [PageModel] (um título, uma mensagem, a hora atual) e o armazena no modelo com o nome [model]. A view o recuperará com esse nome;
- linha 31: a action devolve o nome da view, [views/index]. Ela não cria mais a resposta; em vez disso, faz referência a uma view e preparou seus dados;
- linha 36: a action [hello] devolve um objeto [ModelAndView], que combina o nome da view e seu modelo em um único objeto. Esta é outra forma de escrever uma action que usa uma view;
- Linha 38: Quando a view depende da requisição, a action seleciona a view. Aqui, o nome [unknown] exibe a view [views/unknown], com código de status 404: o terceiro argumento do construtor de [ModelAndView] é o código da resposta. O modelo dessa view contém uma string simples: o nome solicitado. [Map.of(...)] cria um dicionário somente leitura;
- linha 44: as duas actions compartilham a mesma view, [views/index], com modelos diferentes.
Onde o [Spring MVC] procura a view [views/index]? Ele passa o nome da view a um view resolver ([ViewResolver]), que o converte em uma view específica. O configurado pelo [Spring Boot] para o [Thymeleaf] ([ThymeleafViewResolver]) adiciona um prefixo, [classpath:/templates/], e um sufixo, [.html]: A view [views/index] é o arquivo [templates/views/index.html] no classpath, ou seja, as pastas e os arquivos compactados em que a máquina virtual [Java] procura as classes e os recursos da aplicação. A pasta [src/main/resources] do projeto faz parte dele: seu conteúdo é copiado pelo [Maven] para [target/classes], junto com as classes compiladas. Esses dois valores podem ser alterados em [application.properties] (propriedades [spring.thymeleaf.prefix] e [spring.thymeleaf.suffix]). Diferentemente do [ASP.NET Core MVC], não há nenhuma convenção que derive o nome da view dos nomes do controller e da action: a action sempre especifica o caminho da view, relativo à pasta [templates]. Os arquivos do projeto:
O arquivo [templates/views/index.html]:
Vamos comentar este código:
- Linha 2: Um comentário [Thymeleaf] é escrito como [<!--/* ... */-->]. É um comentário HTML cujo conteúdo é delimitado por [/*] e [*/]: o [Thymeleaf] o remove da página renderizada, ao passo que um comentário HTML comum ([<!-- -->]) seria enviado ao navegador;
- Linha 3: O atributo [xmlns:th] declara o namespace dos atributos [th:]. Ele se destina exclusivamente aos editores de código (autocompletar, validação): o [Thymeleaf] processa os atributos [th:] mesmo sem ele, e o remove da página gerada;
- Linha 6: O atributo [th:text] substitui o conteúdo da tag pelo valor da expressão. [${model.title}] é uma expressão de variável: [model] é o atributo do modelo definido pela action, e [.title] chama seu acessor, [title()]. O texto “Page Title” escrito dentro da tag é apenas um exemplo, exibido quando o arquivo é aberto diretamente em um navegador; ele desaparece da página gerada;
- linhas 9–11: o mesmo princípio se aplica ao título, à mensagem e à hora. Para inserir um valor no meio de um texto, envolva-o em uma tag [<span>], que contém o atributo [th:text].
[${...}] expressões são escritas na linguagem de expressões do [Spring], [SpEL] ([Spring Expression Language]). [model.title] chama o método [getTitle()] de um [JavaBean], ou o método [title()] de um record: o mesmo código é escrito nos dois casos.
Uma view [Thymeleaf] não é compilada com a aplicação: ela é lida e interpretada quando a página é solicitada. Um erro em uma view, portanto, não é relatado em tempo de compilação, mas sim quando a página é exibida. Se você escrever [${model.titl}] na view, a requisição falha (código de status 500) e o console do servidor exibe: [Property or field 'titl' cannot be found on object of type 'example13.models.PageModel']. Da mesma forma, um nome de view que não corresponde a nenhum arquivo causa o erro [Error resolving template [views/missing], template might not exist or might not be accessible by any of the configured Template Resolvers]. O resultado, em http://localhost:5000/:

O código-fonte da página recebida pelo navegador não contém mais nenhum vestígio do [Thymeleaf]:
Observe que:
- os atributos [th:text] desapareceram, substituídos pelos valores do modelo, assim como o atributo [xmlns:th];
- o comentário [Thymeleaf] desapareceu, mas deixa uma linha em branco;
- os caracteres acentuados, se houver (esta página em inglês não tem nenhum), são escritos como estão ([é], [è]...): [Thymeleaf] escapa apenas os caracteres que têm significado em HTML ([<], [>], [&], ["], [']). [Razor], por outro lado, codifica por padrão os caracteres acentuados ([è] para [è]), o que obriga o curso de [ASP.NET Core MVC] a alterar uma configuração; aqui não há essa exigência.
A URL http://localhost:5000/hello/martin exibe a mesma view usando um modelo diferente:

Se o texto contivesse um apóstrofo, o código HTML desta página o mostraria como [']: este é um dos caracteres escapados por [th:text]. A URL http://localhost:5000/hello/unknown mostra uma view diferente:
A resposta tem de fato o código de status 404 definido pelo objeto [ModelAndView] (o [Tomcat] envia apenas o código, sem seu rótulo [Not Found]). O arquivo [templates/views/unknown.html]:
- linha 9: o texto delimitado por duas barras verticais, [|...|], é uma substituição literal: as expressões [${...}] que ele contém são substituídas por seus valores. Isso é mais legível do que uma sequência de [<span>]. [${name}] é o atributo [name] do modelo, uma string simples.
4.2. Exemplo 14: A linguagem do Thymeleaf
Uma view [Thymeleaf] não contém nenhum código [Java]: tudo é tratado por meio dos atributos [th:] e das expressões que eles contêm. Ainda assim, ela contém condições, laços, variáveis locais e chamadas de método. Esse poder exige disciplina: a view deve continuar sendo um elemento de formatação; os cálculos e as decisões pertencem à action e aos serviços. O Exemplo 14 apresenta uma visão geral da sintaxe. O modelo, arquivo [models/BasicsModel.java]:
- linhas 6–15: o modelo é um record: algumas strings, um booleano, duas listas de produtos e um endereço;
- Linhas 17–21: Dois records aninhados dentro do primeiro: [BasicsModel.Product] e [BasicsModel.Address]. Um preço é um [BigDecimal]; esse tipo [Java] representa números decimais exatos (um [double] não consegue representar exatamente [0.1]).
O arquivo [controllers/BasicsController.java]:
- Linhas 19–31: A action preenche o modelo: algumas strings, um booleano, uma lista de três produtos, um carrinho de compras vazio e um endereço. O apelido (linha 22) é intencionalmente definido como [null]. [List.of(...)] cria uma lista somente leitura; [List.of()] cria uma lista vazia.
A view, arquivo [templates/basics/index.html]:
Vamos comentar este código:
- Linha 8: O atributo [th:with] declara variáveis locais que podem ser usadas dentro da tag que o contém e em todas as suas tags filhas (neste caso, [total] e [count]) em todo o corpo da página. [model.products.![price]] é uma projeção do [SpEL]: a lista de preços dos produtos. [#aggregates] e [#lists] são objetos utilitários do [Thymeleaf] (eles começam com [#]): [#aggregates.sum] calcula a soma de uma lista de números; [#lists.size] conta os elementos de uma lista;
- linhas 10–11: um comentário [Thymeleaf], que está ausente da página gerada;
- linha 12: um valor [null] ([${model.nickname}]) não exibe nada, sem erro;
- linhas 14–15: [th:text] escapa os caracteres especiais do HTML ([<] torna-se [<]...): o texto é exibido como está. [th:utext] ([unescaped text]) o insere sem escape: ele é interpretado como HTML. [th:utext] é usado apenas para HTML gerado pela aplicação, nunca para dados digitados por um usuário: o usuário poderia injetar HTML, ou até mesmo [JavaScript], na página (um ataque conhecido como [XSS], [cross-site scripting]);
- Linhas 17–18: uma condição. [th:if] mantém a tag (e seu conteúdo) se a expressão for verdadeira e a remove caso contrário; [th:unless] faz o oposto. Não existe [th:else]: escrevemos a condição oposta;
- Linha 22: um laço. O atributo [th:each] repete a tag que o contém, neste caso, [<li>], uma vez para cada item da lista. [product] é o item atual; [stat], que é opcional, é o contador da iteração: [stat.index] (começando em 0), [stat.count] (começando em 1), [stat.size], [stat.first], [stat.last], [stat.even], [stat.odd]. No texto da tag, [[[${product.name}]]] é uma expressão inline: ela insere o valor, escapado como em [th:text], sem a tag [<span>] (a forma [[(...)]] insere sem escape, como [th:utext]);
- linha 23: o operador condicional [condition ? value1 : value2]. As strings literais são escritas entre aspas simples;
- linhas 24–25: [th:block] é uma tag específica do [Thymeleaf]: ela serve apenas para carregar os atributos [th:] e desaparece da página gerada, deixando somente seu conteúdo. [stat.first] e [stat.last] verificam a posição no laço;
- linhas 30–31: o caso de uma lista vazia. [#lists.isEmpty] verifica se a lista está vazia; um laço [th:each] sobre uma lista vazia não produz nada;
- linha 34: uma substituição literal [|...|] que usa as variáveis de [th:with], e duas chamadas de método: [total.doubleValue()] converte [BigDecimal] em [double], e [#numbers.formatDecimal(value, 1, 2)] formata um número com pelo menos um dígito antes da vírgula decimal e exatamente dois depois;
- linha 35: uma referência a [model.address.street], e o objeto utilitário [#strings], que agrupa operações sobre strings ([toUpperCase], [isEmpty], [contains], [startsWith]...);
- linha 36: o [Thymeleaf] processa apenas os atributos [th:] e as expressões inline [[[...]]]; o restante do texto é copiado como está. O caractere [@] não tem significado específico aqui.
O resultado, em http://localhost:5000/:

O código HTML produzido:
Observe que:
- as tags [th:block], os comentários [Thymeleaf] e as tags removidas por [th:if] / [th:unless] deixam linhas em branco que não têm efeito sobre a exibição;
- O preço médio é [62.17] no [curl] e [62,17] no navegador. [#numbers.formatDecimal] usa o idioma da requisição. Por padrão, o [Spring MVC] o lê do cabeçalho HTTP [Accept-Language] enviado pelo navegador: um navegador configurado em francês envia [Accept-Language: fr-FR] e recebe uma vírgula; [curl] não envia esse cabeçalho, e o idioma passa a ser o do sistema em que o servidor está sendo executado (neste caso, o inglês; em um computador configurado em francês, o [curl] também receberia uma vírgula). O Exemplo 16 e o capítulo “Internacionalização” tratam desse mecanismo;
- os próprios preços ([12.5]) são gerados pelo método [toString] de [BigDecimal], que independe do idioma. O Exemplo 16 os formata.
Para concluir este exemplo, aqui estão os cinco tipos de expressões do [Thymeleaf], que serão usados nos exemplos deste capítulo e do próximo:
Expressão | Função | Exemplo |
[${...}] | expressão de variável ([SpEL]): um atributo do modelo, uma propriedade, uma chamada de método, um bean ([${@name...}]), um objeto utilitário ([${#strings...}]) | 13, 14, 16 |
[*{...}] | expressão de seleção: uma propriedade do objeto designado pelo atributo [th:object] | 18, 19, 21 |
[#{...}] | mensagem: texto do arquivo [messages.properties], no idioma da requisição | Próximo capítulo |
[@{...}] | link: uma URL, com suas variáveis e parâmetros | 16, 21 |
[~{...}] | fragmento: uma seção de página a ser inserida | 15 a 21 |
Existem inúmeros objetos utilitários: [#strings], [#numbers], [#lists], [#aggregates], [#dates] (datas [java.util.Date]), [#temporals] (datas [java.time]: [LocalDate], [LocalDateTime]...), [#locale] (o idioma da requisição), [#ids], e [#fields] (formulários, exemplos 18 e 19)... A documentação do [Thymeleaf] (https://www.thymeleaf.org) descreve todos eles.
4.3. Exemplo 15: Template, fragmentos, arquivos estáticos
As páginas de um site compartilham um template comum (cabeçalho, barra de navegação, rodapé). Para o [Thymeleaf], os componentes de página reutilizáveis são os fragmentos; e o próprio template é um fragmento, no qual cada página insere seu conteúdo. Por fim, as páginas precisam de arquivos estáticos (folhas de estilo, imagens, scripts), que são servidos como estão, sem passar por um controller. Os arquivos do exemplo:
4.3.1. Os arquivos estáticos
O [Spring Boot] serve automaticamente, sem controller, os arquivos da pasta de recursos [static] : O arquivo [src/main/resources/static/css/styles.css] é servido na URL [/css/styles.css]. Se nenhum arquivo corresponder à URL e nenhuma action a tratar, a resposta é um 404. Vamos verificar:
O cabeçalho [Last-Modified] informa a data de modificação do arquivo: o navegador só solicitará o arquivo novamente, enviando essa data de volta, se ele tiver sido alterado.
O framework CSS [Bootstrap] é comum a todos os exemplos: ele é armazenado uma única vez, na pasta [examples/common/bootstrap], fora dos recursos dos exemplos. É preciso, portanto, informar ao [Spring MVC] onde encontrá-lo. O arquivo [config/WebConfig.java]:
Vamos comentar este código:
- linha 8: uma classe de configuração (veja o Exemplo 06);
- linha 9: a interface [WebMvcConfigurer] nos permite complementar a configuração do [Spring MVC] criada pelo [Spring Boot], sem substituí-la: redefinimos apenas os métodos que nos interessam (todos os outros têm uma implementação padrão, vazia);
- linhas 14–19: O método [addResourceHandlers] declara diretórios de arquivos estáticos. Os arquivos da URL que começam com [/bootstrap/] (linha 15; [**] designa qualquer sequência de diretórios e arquivos) são servidos a partir do diretório [common/bootstrap];
- linha 18: o prefixo [file:] designa uma pasta no disco (e não no classpath). O caminho é relativo ao diretório atual, aquele a partir do qual a aplicação foi iniciada: [../common/bootstrap/] se iniciada a partir do diretório do exemplo, [common/bootstrap/] se iniciada a partir do diretório [examples]. Os dois locais são verificados em ordem. Assim, [examples/common/bootstrap/css/bootstrap.min.css] é servido na URL [/bootstrap/css/bootstrap.min.css]. O estudo de caso, por sua vez, coloca o [Bootstrap] em sua própria pasta, [static].
Todos os exemplos a seguir usam este arquivo: [WebConfig.java].
4.3.2. O template
O arquivo [templates/layout.html]:
Vamos analisar este código:
- Linha 4: O atributo [th:fragment] transforma a tag [<html>], e portanto a página inteira, em um fragmento chamado [page], que espera dois parâmetros: [title] e [content]. As páginas da aplicação chamarão esse fragmento, passando a ele seu título e seu conteúdo;
- linha 8: o parâmetro [title] é usado como um atributo do modelo;
- linhas 9–10: as folhas de estilo, servidas como arquivos estáticos;
- linha 15: o atributo [th:replace] substitui a tag que o contém (aqui, [<nav>]) por um fragmento. [~{fragments/navbar :: navbar}] é uma expressão de fragmento: o fragmento [navbar] do arquivo [templates/fragments/navbar.html] (à esquerda de [::], o nome da view; à direita, o nome do fragmento);
- linha 17: o local onde o conteúdo da página, recebido no parâmetro [content], é inserido; esse parâmetro é ele próprio um fragmento, que [th:replace] insere no lugar da tag [<main>];
- linha 19: [path] é o caminho da página solicitada. Este não é um parâmetro do fragmento: é um atributo adicionado ao modelo de todas as views por uma classe que veremos mais adiante. [#dates.createNow()] é a data atual, e [#dates.year] extrai o ano dela.
Existe um segundo atributo de inserção, [th:insert], que insere o fragmento dentro da tag hospedeira em vez de substituí-la. Com um fragmento [<span th:fragment="f">...</span>], escrever [<div th:replace="~{:: f}"></div>] produz [<span>...</span>], e [<div th:insert="~{:: f}"></div>] produz [<div><span>...</span></div>] ([~{:: f}], sem nome de view, refere-se a um fragmento da view atual). Os exemplos deste curso usam [th:replace].
O arquivo [templates/fragments/navbar.html]:
- Linha 2: Um arquivo de fragmentos não é uma página completa; ele contém uma ou mais tags com o atributo [th:fragment]. Este fragmento não tem parâmetros. Observe que o arquivo não declara o namespace [xmlns:th]; isso não é necessário.
O arquivo [templates/fragments/card.html]:
- Linha 2: O fragmento [card] tem dois parâmetros, um nome e uma função;
- linhas 4–5: os parâmetros são usados como atributos do modelo.
4.3.3. As páginas
O arquivo [controllers/PagesController.java]:
- Linhas 13–14: o tipo dos membros da equipe, um record declarado no controller ([PagesController.Member]);
- linhas 17–19: a action [home] não tem modelo; ela não exige o parâmetro [Model];
- linhas 22–28: a action [team] passa uma lista de membros.
O arquivo [templates/pages/home.html]:
Vamos analisar este código:
- linha 4: o atributo [th:replace] da tag [<html>] substitui a página inteira pelo fragmento [page] do template [layout.html]. Ele lhe passa dois parâmetros: o título, uma string literal entre aspas simples, e o conteúdo, [~{::main}]. Essa expressão de fragmento, que não tem nome de view, refere-se a uma tag da view atual: neste caso, a tag [<main>] (linhas 6–12). O template é assim gerado, com a tag da página substituindo a sua própria tag, [<main>];
- linha 11: a chamada ao fragmento [card], com dois parâmetros definidos diretamente.
Tudo o que está na página fora da tag [<main>] (a tag [<body>], por exemplo) desaparece: só importa o fragmento passado ao template. As tags [<html>] e [<body>] são incluídas unicamente para garantir que o arquivo continue sendo uma página HTML válida, que pode ser aberta em um navegador.
O arquivo [templates/pages/team.html]:
- linha 7: a tag [<div class="col-md-4">] é repetida para cada membro;
- linha 9: o fragmento recebe o nome e o papel do membro atual: a tag marcada com [th:replace] está aninhada na marcada com [th:each], em que a variável [member] é definida.
O arquivo [templates/pages/raw.html]:
- Linhas 3–11: Esta view não chama o template; é uma página completa, sem atributos [th:]. O [Thymeleaf] a copia como está (exceto pelo comentário da linha 2). Não há obrigação de uma view usar o template.
O código HTML da página http://localhost:5000/team mostra o resultado da montagem:
O título, a barra de navegação, três cartões e o rodapé foram montados a partir de quatro arquivos: [layout.html], [navbar.html], [team.html], and [card.html].
4.3.4. Um atributo comum a todas as views
O rodapé do template exibe o caminho da página solicitada, [path]. Com o [Razor], uma view tem acesso direto à requisição atual. Uma view [Thymeleaf] também podia fazer isso, até a versão 3.0, usando o objeto [#request]: teria sido escrito [${#request.requestURI}]. Isso não vale mais a partir da versão 3.1. Uma view que usa [#request] causa um erro 500, e o console exibe:
Os objetos [#request], [#session], [#servletContext], e [#response] foram removidos: eles permitiam que uma view lesse qualquer parâmetro da requisição, o que abria caminho para injeções, e vinculavam o [Thymeleaf] à API de servlets. A entrada [${#ctx.request.requestURI}] também não funciona: [#ctx.request] é igual a [null]. A mensagem de erro indica a solução: adicionar ao modelo o que a view precisa. Para que isso valha para todas as views sem que cada action precise fazê-lo, criamos o arquivo [config/CommonModel.java]:
Vamos comentar este código:
- linha 9: a anotação [@ControllerAdvice] designa uma classe que estende todos os controllers da aplicação. O que ela declara se aplica a cada um deles, como se estivesse escrito em cada um;
- linha 14: um método anotado com [@ModelAttribute("path")] é executado antes de cada action; seu valor de retorno é adicionado ao modelo com o nome [path]. Quando escrito em um controller, aplica-se às actions desse controller (veja o Exemplo 18); quando escrito em uma classe [@ControllerAdvice], aplica-se a todas as actions da aplicação;
- Linhas 15–16: O método pode aceitar os mesmos parâmetros que uma action: neste caso, a requisição atual, [HttpServletRequest] (veja o Exemplo 05). [getRequestURI()] devolve o caminho solicitado, sem os parâmetros.
O estudo de caso usa o mesmo processo (seu arquivo [web/CommonModel.java]) para fornecer a todas as suas views o caminho, o idioma e o usuário conectado.
As páginas resultantes, na URL http://localhost:5000/, http://localhost:5000/team e http://localhost:5000/raw:



O template, os fragmentos e o atributo comum [path] são exatamente o que o estudo de caso usa: um template [layout.html], fragmentos para a barra de navegação, as mensagens e as janelas de confirmação.
4.4. Exemplo 16: Helpers
Uma view costuma precisar de pequenas funções de formatação: formatar uma data ou um preço, colocar um texto em maiúsculas, criar o HTML de um badge... Elas são chamadas de helpers. Com o [Thymeleaf], são métodos de beans do [Spring], chamados dentro de uma expressão ou de um fragmento. O [Thymeleaf] também permite criar seus próprios atributos, agrupados em um dialeto.
4.4.1. Um bean chamado pelas views
O arquivo [helpers/Formats.java]:
Vamos comentar este código:
- Linha 16: a anotação [@Component] transforma a classe em um bean: o [Spring] a encontra na inicialização (assim como encontra os controllers), cria uma instância dela e a mantém. ["formats"] é o nome do bean: é o nome que as views usarão para chamá-lo;
- linhas 20 a 22: colocar em maiúsculas. [Locale.ROOT] torna o resultado independente do idioma do usuário;
- linhas 25 a 31: um valor em uma moeda, formatado de acordo com o idioma da requisição. [LocaleContextHolder.getLocale()] (linha 27) obtém esse idioma, um objeto [Locale] definido pelo [Spring MVC] no início de cada requisição. [NumberFormat.getCurrencyInstance] fornece o formato de moeda desse idioma: separador decimal, separador de milhares e posição do símbolo da moeda; [setCurrency] seleciona a moeda, identificada por seu código internacional ([EUR], [USD]);
- linhas 34 a 36: um método sobrecarregado: mesmo nome, parâmetros diferentes. Se nenhuma moeda for especificada, o padrão é o euro;
- linhas 39 a 41: uma data por extenso ([FormatStyle.FULL]), no idioma da requisição.
A página [templates/pages/products.html] chama esses métodos:
- linhas 10 a 12: em uma expressão [${...}], a notação [@formats] refere-se ao bean chamado [formats]: [${@formats.money(product.price)}] chama seu método [money]. O valor de retorno do método é inserido por [th:text] e, portanto, passa por escape;
- Linha 14: o badge é criado por um fragmento, descrito a seguir.
O arquivo [templates/fragments/badge.html]:
- linha 3: um helper que gera HTML é, no [Thymeleaf], um fragmento: neste caso, uma tag [<span>] que recebe o estoque do produto como parâmetro;
- linha 4: o atributo [th:classappend] adiciona uma classe CSS às classes já existentes da tag ([badge]): verde ([text-bg-success]) se o produto estiver em estoque, vermelho caso contrário;
- linha 5: o texto do badge, com escape feito por [th:text]. Ao contrário de um helper que geraria HTML em uma string, um fragmento não precisa se preocupar com o escape: o [th:text] cuida disso.
O controller, arquivo [controllers/PagesController.java]:
- linha 19: a página inicial recebe a data de hoje, um [LocalDate] (uma data sem hora);
- linhas 25 a 28: a lista de produtos.
O arquivo [templates/pages/home.html]:
- linha 7: a chamada ao método [date] do bean [formats], em uma substituição literal;
- linha 9: o objeto utilitário [#locale] é o idioma da requisição.
4.4.2. O idioma da requisição
O que determina o idioma da requisição? Um bean do [Spring MVC], o resolvedor de idioma ([LocaleResolver]). O que o [Spring Boot] instala por padrão, [AcceptHeaderLocaleResolver], lê o cabeçalho [Accept-Language] enviado pelo navegador: foi isso que causou resultados diferentes para o navegador e para o [curl] no Exemplo 14. Para facilitar o teste dos dois idiomas, o Exemplo 16 o substitui por um resolvedor que lê o parâmetro [lang] da URL. O arquivo [config/WebConfig.java]:
Vamos comentar este código:
- linhas 21 a 27: os arquivos do [Bootstrap], como no Exemplo 15;
- linhas 30 a 33: nosso dialeto do [Thymeleaf], descrito a seguir, declarado como um bean. O [Spring Boot] adiciona automaticamente ao engine do [Thymeleaf] todos os beans que são dialetos;
- linhas 38 a 41: nosso resolvedor de idioma. O bean deve se chamar [localeResolver]: é o nome com o qual o [Spring MVC] o procura. O nome do método anotado com [@Bean] fornece o nome do bean: [localeResolver()]. Ao declarar este bean, substituímos aquele do [Spring Boot];
- linhas 45 a 56: o resolvedor é uma classe aninhada que implementa a interface [LocaleResolver];
- linhas 48 a 50: o método [resolveLocale] é chamado no início de cada requisição: ele retorna o francês ([Locale.FRANCE]) se a URL contiver [lang=fr]; caso contrário, retorna o inglês dos EUA ([Locale.US]). O [Spring MVC] armazena esse idioma em [LocaleContextHolder], de onde ele é obtido pelo bean [formats] e pelos objetos utilitários do [Thymeleaf];
- linhas 53 a 55: o método [setLocale] permitiria alterar o idioma (armazenando-o, por exemplo, em um cookie). Aqui, o idioma vem da URL: o método se recusa a funcionar lançando uma exceção.
Esta é uma forma simples de testar; o próximo capítulo tratará do assunto com mais profundidade.
4.4.3. Um dialeto do Thymeleaf
A barra de navegação destaca o link da página atual (classe CSS [active] do [Bootstrap]). O arquivo [templates/fragments/navbar.html] mostra três maneiras de escrever links:
Vamos detalhar este código:
- linha 3: o namespace [xmlns:ex], assim como [xmlns:th], destina-se apenas aos editores;
- linha 7: a primeira maneira de destacar o link da página atual: uma condição escrita na view, usando o atributo [path] fornecido pela classe [CommonModel] (idêntica à do Exemplo 15). Sem a cláusula “else”, o operador condicional não produz nada quando a condição é falsa e, portanto, o [th:classappend] não adiciona nenhuma classe. Este é o método usado no estudo de caso;
- linha 9: segunda abordagem, mais concisa: um atributo “home”, [ex:active], fornecido por nosso dialeto;
- linha 11: uma expressão de link [@{...}]. O [Spring] gera a URL: os parênteses contêm parâmetros, que são adicionados à URL ([?lang=fr]). Veremos no Exemplo 21 que eles também servem para preencher variáveis de caminho. Uma expressão de link também adiciona, se necessário, o caminho base da aplicação quando ela não está instalada na raiz do servidor.
Um dialeto é um conjunto de atributos (ou tags) que compartilham um prefixo: os atributos [th:] são os do dialeto padrão do [Thymeleaf]. Cada atributo é processado por um processador. O arquivo [helpers/ActiveDialect.java]:
- linha 12: um dialeto que fornece apenas processadores deriva da classe [AbstractProcessorDialect];
- linha 16: o nome do dialeto, o prefixo de seus atributos ([ex]) e sua prioridade: a mesma dos atributos [th:];
- linhas 21 a 23: os processadores do dialeto: apenas um, o do atributo [ex:active]. [Set.of(...)] cria um conjunto imutável.
O arquivo [helpers/ActiveProcessor.java]:
Vamos comentar este código:
- linha 13: um processador de atributo derivado da classe [AbstractAttributeTagProcessor];
- linha 18: seu construtor descreve o que ele processa: o modo HTML, o prefixo do dialeto, apenas tags [<a>], o atributo [active] (com prefixo: [ex:active]), uma prioridade e [true]: o atributo [ex:active] será removido da página gerada;
- linhas 23 e 24: o método [doProcess] é chamado para cada tag [<a>] que tenha o atributo [ex:active]. Ele recebe o contexto da view, a tag e o valor do atributo; o objeto [structure] permite modificar a tag;
- linha 26: o processador é código [Java], não uma expressão de view: ele tem autorização para ler a requisição atual. Quando a view é renderizada para uma requisição web, o contexto é um [IWebContext], que dá acesso à troca de mensagens (a requisição e sua resposta); [getRequestPath()] retorna o caminho solicitado. A expressão [context instanceof IWebContext web] verifica o tipo do contexto e, se for o caso, o armazena na variável [web];
- linhas 27 a 32: se o caminho da página começar com o valor do atributo, a classe [active] é adicionada ao atributo [class] da tag.
O código HTML da barra de navegação, na URL [/products]:
O link “Products” recebeu a classe [active], e o atributo [ex:active] foi removido. A expressão de link produziu [/products?lang=fr]. Observe que o [Thymeleaf] removeu o atributo [xmlns:th], mas não o atributo [xmlns:ex]: ele não reconhece este último. Ele poderia ter sido omitido, já que só é usado pelos editores.
O template [layout.html] é o do Exemplo 15, sem o rodapé (e os títulos das páginas terminam com [- Helpers] em vez de [- My site]). As páginas resultantes, em inglês (http://localhost:5000/, http://localhost:5000/products) e depois em francês (http://localhost:5000/products?lang=fr):



Os preços mudam de formato conforme o idioma: [1 149,90 €] em francês, [€1,149.90] em inglês. Em francês, os dólares são indicados como [$US] para distingui-los de outras moedas (canadense, australiana etc.). O código HTML da tabela, em francês ([/products?lang=fr]):
e em inglês ([/products]), em que o dólar é escrito simplesmente como [$]:
Apenas os valores mudaram: o texto dos badges está fixo no fragmento (o próximo capítulo traduzirá os textos).
4.5. Exemplo 17: Um formulário GET
Um formulário HTML enviado pelo método GET coloca seus campos na URL. Este é o método apropriado para uma busca: ele não modifica nada, e a URL resultante pode ser salva nos favoritos ou compartilhada. O estudo de caso o usa para selecionar um médico e uma data.
Os arquivos [models/Book.java] e [models/SearchModel.java] :
- Linha 6: o modelo da view contém os valores digitados ([keyword], [genre]) para que o formulário possa exibi-los novamente, junto com a lista de gêneros e os resultados.
O arquivo [controllers/BooksController.java]:
Vamos detalhar este código:
- linhas 17 a 24: os livros e os gêneros, em memória;
- linha 27: uma única ação pode corresponder a vários caminhos; ela trata tanto [GET /] quanto [GET /search];
- linhas 28 e 29: os parâmetros [keyword] e [genre] são vinculados aos parâmetros de mesmo nome na URL (veja o exemplo 07). [required = false] os torna opcionais: na primeira visita, o formulário ainda não foi enviado, e seus valores são [null];
- linhas 31 a 35: filtragem, usando um stream ([stream]) [Java] (veja o Exemplo 06): [stream()] percorre a lista; cada [filter] mantém apenas os livros que satisfazem uma condição; e [toList()] reúne os livros selecionados em uma nova lista. As condições são expressões lambda: [b -> ...] é uma função anônima que recebe um livro [b] e retorna um booleano. Uma palavra-chave vazia ou um gênero vazio não filtra nada;
- linhas 36 e 37: o modelo da view. Aqui, os [null] são substituídos por strings vazias.
O template [templates/layout.html] é simplificado: um único parâmetro, o conteúdo da página, e um título fixo:
- linha 2: o fragmento [page] agora tem apenas um parâmetro, [content];
- Linha 5: o título é o mesmo para todas as páginas.
O arquivo [templates/books/search.html]:
Vamos detalhar este código:
- Linha 2: a página passa seu único parâmetro, a tag [<main>], para o template;
- Linha 7: [method="get"] e [action="/search"]: o envio do formulário é uma requisição [GET /search?keyword=...&genre=...]. Os nomes dos parâmetros são o atributo [name] de cada campo;
- Linha 11: o atributo [th:value] define o atributo [value] do campo: ele restaura o valor digitado. De modo geral, [th:xxx] calcula o valor dos atributos HTML [xxx]: [th:value], [th:href], [th:action], [th:class]...
- Linhas 18 e 19: uma opção por gênero. Dentro da mesma tag, [th:each] é processado primeiro, seguido de [th:value] e [th:text], que usam a variável do laço. [th:selected] é um atributo booleano: se a expressão for verdadeira, o [Thymeleaf] escreve [selected="selected"]; se for falsa, ele não escreve o atributo. É exatamente o que o HTML exige; para este atributo, a mera presença do atributo [selected] basta para selecionar a opção. O mesmo vale para [th:checked], [th:disabled], [th:required], [th:readonly]...;
- linha 26: o número de resultados;
- linha 28: a lista de resultados, com uma tag [<i>] e duas expressões inline.
O código HTML da lista suspensa, após uma busca como [poetry]:
Na exibição inicial (http://localhost:5000/) e depois de uma busca:


A barra de endereços mostra os parâmetros que foram enviados. Aqui eles contêm apenas letras simples; caracteres especiais seriam codificados ali (um [é] acentuado se torna [%C3%A9], por exemplo): é a codificação de URL, que o [Spring MVC] decodifica antes de os parâmetros serem concatenados.
4.6. Exemplo 18: Campos de formulário
O Exemplo 18 combina todos os tipos de campos HTML: texto, senha, data, botões de opção, caixas de seleção, lista suspensa, lista de seleção múltipla, caixa de texto e campo oculto. Ele mostra como o servidor os recebe e como a view os exibe. Também apresenta o atributo [th:field], que vincula um campo de formulário a uma propriedade de um objeto do modelo.
O arquivo [services/ListsService.java]:
- Linha 11: a anotação [@Service] transforma a classe em um bean, assim como [@Component] (Exemplo 16): o [Spring] a encontra na inicialização e cria uma única instância dela, um singleton (veja o Exemplo 06), que pode ser injetado nos controllers. [@Service] difere de [@Component] apenas pela intenção que expressa: a classe é um serviço. As listas fornecidas pelo formulário são as mesmas para todos os usuários: um singleton é o lugar natural para armazená-las;
- linhas 14 e 15: um país, ou seja, um código e um nome;
- linhas 17 a 32: as listas, retornadas pelos métodos [getXxx()]. Para uma view, essas são as propriedades do bean [titles], [countries], [hobbies] e [languages] : [${lists.titles}] chamará [getTitles()].
O arquivo [models/Input.java]:
Vamos comentar este código:
- Linhas 13 a 23: a entrada é uma classe [JavaBean] (campos privados, um construtor sem parâmetros e os acessores [getXxx] e [setXxx]), e não um record: o binding do modelo a cria vazia e depois preenche cada propriedade com o parâmetro de mesmo nome, por meio de seu setter [setXxx];
- linhas 17 e 19: as caixas de seleção e a lista de seleção múltipla são listas: elas recebem todos os valores enviados (veja o Exemplo 10). São inicializadas com uma lista vazia, nunca com [null];
- Linhas 21 e 22: um campo [<input type="date">] envia a data no formato [ISO 8601] [yyyy-mm-dd]. A anotação [@DateTimeFormat(iso = DateTimeFormat.ISO.DATE)] especifica esse formato para o [Spring], que o usa nos dois sentidos: para converter o texto recebido em [LocalDate] e para reescrever a data no campo.
O arquivo [controllers/FormController.java]:
Vamos detalhar este código:
- linhas 22 a 26: o serviço de listas é injetado pelo construtor (veja o Exemplo 06);
- linhas 30 a 33: um método anotado com [@ModelAttribute("lists")], declarado em um controller, é executado antes de cada ação desse controller: as duas ações encontrarão o atributo [lists] em seu modelo, sem precisar adicioná-lo (veja [CommonModel], Exemplo 15, para todas as ações da aplicação);
- linhas 36 a 45: [GET /form] exibe o formulário com valores iniciais. O objeto é armazenado no modelo com o nome [input];
- linha 50: [POST /form] recebe a entrada do usuário. A anotação [@ModelAttribute], aplicada a um parâmetro, instrui o binding do modelo a criar o objeto a partir dos parâmetros da requisição (este é o comportamento padrão para um parâmetro de tipo classe; veja o Exemplo 08) e a armazená-lo no modelo da view. Sem um nome explícito, o nome do atributo é o da classe, com a primeira letra minúscula: [input]. O formulário é exibido novamente com os valores recebidos;
- linhas 52 a 56: [getParameterMap()] também dá acesso aos parâmetros como foram enviados: um dicionário em que cada valor é um array de strings (um parâmetro pode se repetir). Ele é convertido em texto, uma linha por parâmetro, armazenado no modelo com o nome [received]. [Collectors.joining("\n")] concatena as linhas, separadas por uma quebra de linha.
O template [templates/layout.html] é o do Exemplo 17 (só o título muda). O arquivo [templates/form/form.html]:
Vamos detalhar este código:
- Linha 7: o atributo [th:object] especifica o objeto do formulário: o atributo [input] do template. Dentro da tag, uma expressão de seleção [*{name}] refere-se à propriedade [name] desse objeto: é equivalente a [${input.name}];
- Linha 9: o atributo [th:field="*{token}"] vincula o campo à propriedade [token]: ele escreve os atributos [id] e [name] (o nome da propriedade) e o atributo [value] (seu valor). Um campo oculto é enviado com o formulário, mas não é exibido. Ele serve para passar informações de uma página para a seguinte (no estudo de caso, por exemplo, contém a versão de um registro). Atenção: o usuário pode modificá-lo;
- Linhas 14 a 18: os botões de opção compartilham o mesmo [name]; apenas um pode ser selecionado, e apenas um valor é enviado. Para um botão de opção, [th:field] não escreve o valor da propriedade em [value] ([th:value] é quem fornece o valor do botão): ele seleciona o botão se seu valor corresponder à propriedade. Como todos os botões têm o mesmo nome, [th:field] atribui a eles valores de [id] numerados: [title1], [title2]... O objeto utilitário [#ids.prev('title')] (linha 17) define o valor do último campo [title] como o [id] informado, para o atributo [for] de seu rótulo;
- linha 25: um campo de texto: o [th:field] escreve [id="name"], [name="name"] e o valor. O rótulo da linha 23 pode, portanto, fixar [for="name"];
- linha 30: uma senha nunca é devolvida em uma página: o campo não usa [th:field] e não tem um atributo [value];
- linha 35: um campo de data. O navegador exibe a data em seu próprio formato, mas sempre envia e recebe [yyyy-mm-dd]; o [th:field] escreve a data nesse formato, graças à anotação [@DateTimeFormat];
- linhas 42 a 45: caixas de seleção com o mesmo [name]: cada caixa marcada envia seu valor, de modo que o parâmetro se repete. O [th:field] marca a caixa se seu valor estiver na lista [hobbies];
- linhas 51 a 53: uma lista suspensa. O [th:field] na tag [<select>] seleciona a opção cujo valor é igual à propriedade [country];
- linhas 58 a 60: o atributo [multiple] permite selecionar várias opções: o [th:field] seleciona todas as opções que pertencem à lista [languages];
- linha 67: o valor de uma caixa de texto fica dentro de suas tags, e não em um atributo [value]: o [th:field] sabe disso;
- linhas 73 a 76: o que o servidor recebeu, exibido apenas após o envio, dentro de uma tag [<pre>], que preserva as quebras de linha.
Veja um trecho do código HTML gerado por esses atributos [th:field] (o campo oculto, o segundo botão de opção, as duas primeiras caixas de seleção, a lista suspensa):
Observe os campos ocultos que nós não escrevemos: [_hobbies] depois de cada caixa de seleção, [_languages] antes da lista suspensa. Eles resolvem um problema do HTML: uma caixa desmarcada simplesmente não é enviada. Se o usuário desmarcar todas as caixas, o parâmetro [hobbies] não estará na requisição, e o binding do modelo não atualizaria a propriedade [hobbies], que manteria seu valor anterior. O [_hobbies] marcador, por outro lado, é sempre enviado: quando o [Spring] o encontra sem o parâmetro [hobbies], ele limpa a lista (ou define [false] para um valor booleano). Aqui, a entrada é um objeto novo cuja lista já está vazia, então a diferença não aparece; ela importa quando o objeto do formulário já foi preenchido anteriormente (por exemplo, armazenado em uma sessão; veja o capítulo “Escopos de dados”).
O formulário inicial (http://localhost:5000/form) e depois do envio:


Observe que:
- A caixa de texto exibiu "[Hello <b>whole</b> world]" exatamente como foi digitado: "[th:field]" faz o escape do valor, e as tags digitadas não são interpretadas;
- A senha foi recebida, mas não é exibida;
- O navegador enviou os marcadores [_hobbies] (um por caixa de seleção) e [_languages].
Com o [curl], podemos ver a diferença quando uma caixa está marcada:
e duas caixas marcadas:
(apenas a tag [<pre>] da página é reproduzida). A opção [-d] do [curl] envia uma requisição POST, com este corpo, e o cabeçalho [Content-Type: application/x-www-form-urlencoded] de um formulário HTML.
4.7. Exemplo 19: Validação de formulário
Um formulário inválido deve ser exibido novamente, mostrando os valores digitados e uma mensagem abaixo de cada campo com erro. O Exemplo 19 aplica a técnica do Exemplo 09 (validação feita pela ação, usando o parâmetro [BindingResult]) a um formulário de cadastro e demonstra como o [Thymeleaf] exibe os erros.
A validação requer uma dependência adicional. O arquivo [pom.xml]:
- linhas 7 a 11: o starter de validação: a API [Bean Validation] (as anotações [@NotBlank], [@Size]...) e sua implementação, [Hibernate Validator] (veja o Exemplo 08).
O arquivo [models/RegistrationModel.java]:
Vamos comentar este código:
- linhas 16 a 18: o nome é obrigatório ([@NotBlank] rejeita [null], uma string vazia e uma string formada apenas por espaços) e limitado a 20 caracteres;
- linhas 20 a 22: [@Email] valida o formato de um endereço de e-mail;
- linhas 25 a 28: a idade é convertida em um inteiro e depois validada. O tipo [Integer] (e não [int]) admite o valor [null]: uma idade ausente permanece como [null], e [@NotNull] sinaliza isso;
- linhas 30 a 32: pelo menos 6 caracteres. [@Size] não valida um valor [null]: esse é o papel de [@NotBlank];
- linhas 38 a 41: a regra “a confirmação é igual à senha” envolve dois campos. O [Bean Validation] não tem uma anotação predefinida para isso; a solução mais simples é um método booleano que faz a comparação, anotado com [@AssertTrue]: a restrição é violada se o método retornar [false]. Para o [Bean Validation], um método chamado [isXxx()] serve como acessor de uma propriedade booleana: qualquer erro será, portanto, associado à propriedade [confirmationValid]. [Objects.equals] compara dois objetos, assim como [null].
O arquivo [controllers/RegistrationController.java]:
Vamos detalhar este código:
- Linhas 25 a 28: um método anotado com [@InitBinder] configura o binding do modelo para as ações deste controller. Ele recebe o objeto [WebDataBinder], que realiza o binding. Um editor de propriedade é registrado ali para o tipo [String]: [StringTrimmerEditor] remove os espaços no início e no fim de cada string recebida; com o argumento [true], uma string vazia se torna [null]. Um nome digitado como [" Martin "] se torna ["Martin"]. Atenção: isso se aplica a todas as strings, inclusive às senhas;
- linhas 31 a 36: o formulário vazio. O parâmetro [html5] será explicado mais adiante. O objeto do formulário é armazenado no template com o nome [registration];
- linha 40: [@Valid] solicita a validação do objeto; [@ModelAttribute("registration")] o armazena no modelo com o nome [registration], o mesmo da linha 33, que é o usado pela view. O parâmetro [BindingResult] deve seguir imediatamente o objeto validado: ele recebe os erros de binding e de validação, e a ação é então sempre executada (veja o Exemplo 09);
- linha 41: [@RequestParam] lê um parâmetro da URL ou do corpo da requisição: aqui, [html5] vem da URL do formulário;
- linhas 42 a 50: se houver erros, o formulário é exibido novamente com os valores digitados (exceto as senhas) e uma mensagem geral armazenada no template. Não há mais nada a fazer: o objeto [registration] e seus erros ([BindingResult]) já estão no modelo, onde a view os encontrará;
- linha 51: caso contrário, a página de boas-vindas, que também usa o objeto [registration] do modelo.
Um erro de conversão (uma idade [abc]) gera uma mensagem padrão em inglês difícil de ler: [Failed to convert property value of type java.lang.String to required type java.lang.Integer for property age; For input string: "abc"]. O arquivo [messages.properties] a substitui:
- Linha 3: o [Spring Boot] lê automaticamente o arquivo de recursos [messages.properties]: é o arquivo de mensagens da aplicação (o próximo capítulo explicará como ele é localizado em vários idiomas). Em caso de erro de conversão, o [Spring] procura uma mensagem em várias chaves, da mais específica à mais geral: [typeMismatch.registration.age] (o objeto e sua propriedade), [typeMismatch.age] (a propriedade), [typeMismatch.java.lang.Integer] (o tipo esperado) e, por fim, [typeMismatch]. A primeira encontrada tem precedência; caso contrário, usa-se a mensagem em inglês. Em um arquivo como esse, o apóstrofo deve ser escrito duas vezes (em francês, por exemplo: [n''est]): as mensagens são processadas pela classe [MessageFormat] do [Java], para a qual o apóstrofo simples é um caractere especial. O estudo de caso substitui, assim, todas essas mensagens.
4.7.1. Um fragmento de campo
Todos os campos seguem o mesmo padrão: um rótulo, um campo e uma mensagem de erro. Um fragmento extrai esses componentes. O arquivo [templates/fragments/field.html]:
Vamos comentar este código:
- Linha 5: o fragmento [field] é declarado sem assinatura, isto é, sem lista de parâmetros. Ele será chamado com parâmetros nomeados ([field(name='age', label='Age', ...)]), que se tornam variáveis do fragmento; um parâmetro não fornecido simplesmente é definido como [null]. Isso é útil para um fragmento com muitos parâmetros opcionais. [th:with] declara a variável [key]: o nome da propriedade para a qual o erro é exibido. O operador [?:] (conhecido como “Elvis”) retorna seu operando da esquerda se ele não for [null]e, caso contrário, seu operando da direita: [errorOf] se fornecido, [name] caso contrário;
- Linha 9: [th:type] escreve o atributo [type]. [th:field] deve receber o nome da propriedade, que está armazenado na variável [name]. Não é possível escrever [*{name}] (isso seria a propriedade [name]): use a etapa de pré-processamento [__...__]. A expressão entre os sublinhados duplos é avaliada primeiro, e seu resultado substitui o texto: se [name] for igual a [email], o atributo se torna [th:field="*{email}"], que é então avaliado normalmente. O [th:field] usa o objeto do formulário ([th:object]), declarado pela view que insere o fragmento;
- linha 10: [#fields.hasErrors(key)] indica se a propriedade tem erros no [BindingResult] do objeto do formulário. As classes [Bootstrap] e [is-invalid] destacam então o campo em vermelho;
- linha 11: o atributo booleano [required] é escrito se [required] for verdadeiro; caso contrário, é omitido;
- linha 12: [th:attr] escreve vários atributos de uma só vez. Um atributo com valor [null] não é escrito: cada campo recebe apenas as restrições HTML5 que se aplicam a ele;
- linha 14: a mensagem de erro, abaixo do campo (classe [Bootstrap] [invalid-feedback]). [#fields.errors(key)] retorna a lista de mensagens da propriedade; uma propriedade pode violar várias restrições, e apenas a primeira é exibida ([[0]]).
O arquivo [templates/registration/registration.html]:
- linhas 6 e 7: o link que ativa ou desativa a validação pelo navegador;
- linha 10: o atributo [action] do formulário armazena o parâmetro [html5];
- linha 11: o atributo booleano [novalidate] é definido quando [html5] é falso. [th:object] refere-se ao objeto do formulário, [registration];
- Linhas 12 a 16: cada campo é uma inserção do fragmento, com parâmetros nomeados. Para a confirmação (linha 16), o erro a exibir é o da propriedade [confirmationValid], e o da regra [@AssertTrue].
O arquivo [templates/layout.html]:
- Linha 13: a mensagem global é exibida na parte inferior da página, sobre um fundo rosa claro (classe [error-area] derivada de [static/css/styles.css]), como mostrado no estudo de caso.
O arquivo [templates/registration/welcome.html]:
- Linha 4: [th:object] não é reservado para formulários: na tag [<main>], ele permite escrever [*{name}] em vez de [${registration.name}];
- Linhas 5 e 6: os valores convertidos e limpos: a idade é um número, e o nome não contém mais espaços.
O formulário vazio (http://localhost:5000/register) e, em seguida, enviado com vários erros (um nome formado por espaços, um endereço incompleto, uma idade muito baixa e senhas curtas demais e diferentes):


depois preenchido corretamente (com espaços em volta do nome):

E com uma idade não numérica, enviada pelo [curl] (o navegador a teria rejeitado em um campo [type="number"]):
Observe que:
- o erro de conversão da idade usa a mensagem de [messages.properties];
- o campo [age] não exibe novamente o valor rejeitado [abc]: em um campo [type="number"], o [th:field] não escreve um valor que não seja um número (com [type="text"], ele teria escrito [value="abc"]);
- a senha ausente tem apenas um erro, “obrigatório”: [@Size] não valida um valor [null]. A confirmação, porém, não tem erros: duas senhas ausentes são iguais;
- os campos sem erros não têm a classe [is-invalid], e seu fragmento não gera mensagem.
4.7.2. Validação pelo navegador
Os atributos [required], [maxlength], [min], [max], [type="email"]... instruem o navegador a validar o formulário antes de enviá-lo: o usuário é avisado imediatamente por meio de uma dica de tela, sem nenhuma comunicação de ida e volta com o servidor. Esse é o comportamento obtido ao clicar no link “enable it” (http://localhost:5000/register?html5=true), que remove o atributo [novalidate] do formulário.
Essa validação é uma conveniência, não uma medida de segurança: ela pode ser contornada simplesmente removendo o atributo [required] com as ferramentas de desenvolvedor do navegador ou enviando a requisição com o [curl]. A validação no servidor continua essencial. É por isso que o exemplo desativa a validação do navegador por padrão: para demonstrar o funcionamento do servidor. O estudo de caso, porém, mantém as duas: os atributos HTML5 por conveniência e a validação no servidor por segurança.
4.8. Exemplo 20: O padrão Post/Redirect/Get
Quando um formulário POST é enviado com sucesso, a ação pode exibir uma página diretamente. O problema surge se o usuário recarregar essa página (tecla F5): o navegador reenvia o formulário, e a operação é executada uma segunda vez (um pedido feito duas vezes, uma consulta marcada duas vezes...). O padrão Post / Redirect / Get (PRG) evita esse problema: uma ação POST bem-sucedida não gera uma página; em vez disso, ela redireciona para uma página GET. Recarregar essa página apenas dispara outro GET, sem nenhum efeito.
Resta um detalhe: a página GET deve exibir uma mensagem (“a tarefa foi adicionada”), embora essa mensagem tenha sido gerada pela ação POST em outra requisição. O [Spring MVC] fornece para isso os atributos flash: atributos definidos antes do redirecionamento, que persistem até a próxima requisição, onde são adicionados ao template e depois desaparecem. Isso é conhecido como mensagem flash. Por padrão, o [Spring MVC] armazena os atributos flash na sessão HTTP do usuário: um espaço de memória que o servidor associa a cada navegador (o capítulo “Escopos de dados” é dedicado a esse tema).
O arquivo [services/TasksService.java]:
- linha 13: um singleton é compartilhado por todas as requisições, que podem ser executadas simultaneamente. Um [ArrayList] comum não suporta isso; [CopyOnWriteArrayList] é uma lista projetada para essa finalidade;
- Linhas 15 a 17: [List.copyOf] retorna uma cópia somente leitura da lista: quem chama não pode modificar a lista do serviço.
O arquivo [controllers/TasksController.java]:
Vamos comentar este código:
- linhas 24 a 28: a página de listagem;
- linha 33: um parâmetro do tipo [RedirectAttributes], fornecido pelo [Spring MVC]: os atributos de redirecionamento;
- linhas 35 a 40: uma entrada inválida: a página é exibida novamente sem redirecionamento (a entrada e a mensagem de erro precisam ser mantidas). A linha 39 simplesmente chama o método [display], como qualquer método [Java]: ele adiciona a lista de tarefas ao template e retorna o nome da view;
- Linha 43: uma entrada válida: depois da operação, [addFlashAttribute] define a mensagem flash a exibir;
- linha 45: uma string iniciada por [redirect:] não é um nome de view: [Spring MVC] responde com um redirecionamento (código 302) para o endereço seguinte (veja o exemplo 04);
- linhas 49 a 54: o contraexemplo, para comparação: uma página como resposta a um POST.
O arquivo [templates/tasks/tasks.html]:
- linha 10: a entrada, exibida novamente após um erro (o atributo [label] não existe nos outros casos: o campo fica vazio);
- linha 13: o atributo [formaction] de um botão envia o formulário para um endereço diferente do atributo [action] do formulário. O formulário tem, assim, dois botões, que disparam duas ações diferentes. O estudo de caso usa essa abordagem em sua página de login;
- linha 15: um atributo ausente do template é definido como [null], e [th:if] trata [null] como falso.
O arquivo [templates/layout.html]:
A mensagem flash é exibida no topo da página (linha 12), e o erro na parte inferior (linha 14). Do ponto de vista da view, um atributo flash é apenas mais um atributo do modelo.
Veja o que o [curl] enxerga quando o formulário é enviado com sucesso. A opção [-c file] salva os cookies recebidos, [-b file] os envia de volta; [--data-urlencode] codifica os espaços e os acentos no campo:
A resposta é um redirecionamento para [/tasks]. Para armazenar a mensagem flash, o [Spring MVC] criou uma sessão HTTP: o servidor ([Tomcat]) atribuiu a ela um identificador, que foi enviado ao navegador no cookie [JSESSIONID]. A requisição seguinte devolve esse cookie, permitindo que o servidor recupere a sessão e a mensagem:
A mensagem flash é exibida; se a página for recarregada, ela desaparece. A sessão, porém, continua aberta: seu identificador não muda, e o servidor não reenvia o cookie.
O arquivo [application.properties] contém uma configuração relacionada à sessão:
- Linha 7: a sessão é rastreada apenas por um cookie. Sem essa configuração, o [Tomcat] não sabe, durante a primeira resposta, se o navegador aceita cookies: ele envia o cookie, mas também acrescenta o identificador da sessão à URL do redirecionamento. O resultado é:
A URL e [/tasks;jsessionid=...] funcionam, mas aparecem na barra de endereços do navegador, e um identificador de sessão circulando na URL (histórico de navegação, favoritos, links copiados) representa um risco de segurança. Todos os exemplos que usam atributos flash têm essa configuração.
No navegador (http://localhost:5000/tasks), depois de adicionar uma tarefa:

A barra de endereços exibe [/tasks]: é a página GET. Você pode recarregá-la sem receio; a mensagem desaparece. Uma entrada contendo espaços:

E o contraexemplo:

Aqui, a barra de endereços exibe [/tasks/without-prg], o endereço do POST. Recarregar a página dispara um aviso do navegador (“Confirm form submission”) e, em seguida, adiciona a tarefa uma segunda vez. Todos os formulários POST do estudo de caso seguem o esquema PRG. No entanto, o estudo de caso armazena seus atributos flash em um cookie, e não na sessão, porque seu servidor não retém nenhum dado entre as requisições.
4.9. Exemplo 21: Links, botões e confirmação
Uma regra simples orienta a escolha entre um link e um botão:
- um link ([<a href>]) gera uma requisição (GET). Uma requisição (GET) não deve modificar nada: navegadores, mecanismos de busca e antivírus podem seguir links por conta própria para preparar uma página ou analisá-la;
- uma operação que modifica dados (adicionar, editar, excluir, sair) é um botão em um formulário POST.
O Exemplo 21 gerencia uma lista de contatos: você visualiza um contato por meio de um link e o exclui por meio de um botão, que abre uma janela de confirmação. Os arquivos deste exemplo:
O arquivo [services/ContactsService.java]:
Vamos comentar este código:
- linhas 14 e 15: um contato;
- linhas 17 a 20: a lista de contatos: um [ArrayList] (editável), inicializado com três contatos;
- linha 24: a palavra-chave [synchronized] garante que apenas uma requisição por vez execute um método [synchronized] do objeto: requisições simultâneas não podem modificar a lista ao mesmo tempo. É uma solução diferente da lista [CopyOnWriteArrayList] do Exemplo 20;
- linhas 29 a 31: [read] retorna um [Optional<Contact>] (veja o Exemplo 06): um objeto que contém um contato ou nada, se nenhum contato tiver esse ID. [findFirst()] retorna o primeiro elemento do stream como um [Optional];
- linhas 36 a 38: um record é imutável: seus campos não são modificados; em vez disso, ele é substituído por um novo;
- linha 46: [++lastId] incrementa o contador antes de usá-lo: os identificadores seguintes são 4, 5...;
- linha 53: [ifPresent] executa uma ação se o [Optional] contiver um contato. [contacts::remove] é uma referência de método: uma forma abreviada de escrever a lambda [c -> contacts.remove(c)].
O arquivo [controllers/ContactsController.java]:
Vamos comentar este código:
- linhas 28 a 38: as duas páginas, a lista e o perfil do contato. A restrição [{id:\\d+}] (veja o Exemplo 02) aceita apenas um identificador formado por dígitos;
- linha 36: [orElseThrow] retorna o contato contido no [Optional] ou, se ele estiver vazio, lança a exceção gerada pela função que lhe é passada: aqui, a referência de método [ContactsController::notFound];
- linhas 41 a 47: gravação de um registro em PRG. Os parâmetros [name] e [phone] são obrigatórios: [@RequestParam] não pode ser usado sem [required = false];
- linhas 50 a 56: duplicação, disparada por um segundo botão no mesmo formulário (atributo [formaction]);
- linhas 58 a 63: exclusão, por meio de um POST;
- linhas 66 a 68: uma exceção [ResponseStatusException] carrega um código HTTP e um motivo. Disparada por uma ação, ela gera uma resposta de erro com esse código: neste caso, 404. Um contato inexistente dispara, assim, um 404 nas ações [details], [save] e [delete]; a duplicação, por outro lado, não relê o contato: ela cria uma cópia com base nos campos recebidos.
O arquivo [templates/contacts/list.html]:
- Linha 13: View: um link, exibido como botão pelo [Bootstrap]. A expressão de link [@{/contacts/{id}(id=${contact.id})}] contém uma variável de caminho [{id}], preenchida pelo parâmetro de mesmo nome entre parênteses: [/contacts/1]. Um parâmetro que não corresponde a nenhuma variável de caminho é adicionado depois de [?] (veja o Exemplo 16);
- linhas 15 e 16: excluir: um pequeno formulário POST, reduzido ao seu botão. O atributo [data-confirmation] contém a pergunta a ser feita antes do envio. Os atributos [data-*] são livres: o HTML os ignora, enquanto o [JavaScript] da página pode lê-los. O [Thymeleaf] pode escrever qualquer atributo: [th:data-confirmation] calcula o atributo [data-confirmation], cujo valor passa por escape.
O arquivo [templates/contacts/details.html]:
- linha 4: [th:object] na tag [<main>]: o contato é o objeto selecionado, e [*{id}] refere-se ao seu ID;
- linha 6: o endereço do formulário, com uma variável de caminho preenchida por uma expressão de seleção;
- Linhas 9 e 13: este formulário não usa [th:field]: os campos não estão vinculados a um objeto de formulário, portanto [th:value] é suficiente;
- linhas 16 e 17: dois botões de envio para o mesmo formulário; o segundo tem seu próprio atributo [formaction].
4.9.1. A janela de confirmação
A caixa de diálogo do navegador ([window.confirm]) não pode ser formatada nem traduzida: seus botões permanecem no idioma do navegador. Ela é substituída por uma janela do [Bootstrap], incorporada à página e oculta até ser necessária. O arquivo [templates/fragments/confirmation.html]:
- linha 2: um fragmento sem parâmetros. A classe [d-none] oculta a janela;
- linha 3: o fundo cinza;
- linha 11: o local da pergunta;
- linhas 14 e 15: os dois botões, identificados pelo atributo [data-action].
O arquivo [templates/layout.html]:
- linha 11: a mensagem flash;
- linha 15: a janela aparece em todas as páginas;
- linha 17: o script é carregado no final da página; quando ele é executado, os elementos que ele procura já existem. Ele é servido como arquivo estático a partir de [static/js/app.js].
Uma pequena porção de [JavaScript] vincula os formulários à janela. O arquivo [static/js/app.js]:
- linha 3: o código é envolvido em uma função que é executada imediatamente, para evitar a criação de variáveis globais;
- linhas 9 a 16: o envio de cada formulário que tenha o atributo [data-confirmation] é interceptado. [preventDefault()] suspende o envio; o formulário é guardado, a pergunta é colocada na janela ([textContent], e não [innerHTML]: a pergunta é exibida como texto, nunca interpretada como HTML), e a janela é exibida;
- Linhas 19 a 27: “Yes” envia o formulário guardado. O método [submit()] de um formulário o envia sem disparar o evento [submit]: não há uma nova solicitação de confirmação. “No” oculta a janela.
Se o [JavaScript] estiver desativado, os formulários são simplesmente enviados sem confirmação: a aplicação continua funcionando. Esse é o princípio do aprimoramento incremental: o [JavaScript] acrescenta conveniência, mas não é essencial. O estudo de caso segue esse princípio (seu script [static/js/app.js] acrescenta o tratamento do teclado: tecla Esc, foco). As páginas resultantes, a partir de http://localhost:5000/contacts: a lista, a solicitação de confirmação, a lista após a exclusão e o perfil de um contato:




Por fim, verificamos que a exclusão não pode ser disparada por uma requisição GET:
O caminho existe, mas não para o método GET: o [Spring MVC] retorna [405 Method Not Allowed], e o cabeçalho [Allow] indica o método aceito. O corpo da resposta é a resposta de erro do [Spring Boot], como visto em JSON para o [curl] (um navegador que solicita HTML recebe uma página de erro). Com POST:
A exclusão ocorreu, seguida de um redirecionamento para a lista; o cookie [JSESSIONID] é o cookie de sessão que transporta a mensagem flash. E um contato inexistente:
A resposta 404 repete o motivo informado para a exceção [ResponseStatusException] ([unknown contact]). Esse campo, [message], só está presente durante o desenvolvimento: as ferramentas de desenvolvimento do [Spring Boot] ([devtools], uma dependência de todos os exemplos) ativam sua exibição; sem elas, a resposta contém apenas o código, o erro e o caminho.