Skip to content

11. Estudo de caso: a aplicação RdvMedecins

11.1. O problema

A aplicação RdvMedecins gerencia as consultas de um consultório médico. Cada médico tem horários (das 8h às 12h, em intervalos de 20 minutos, por exemplo); uma consulta é composta por um dia, um horário e um cliente (um paciente). Esta é a implementação exata, em [Spring MVC], da aplicação [ASP.NET Core MVC] da lição anterior: mesmo banco de dados, mesmas regras de negócio, mesmas páginas, mesmas URLs, mesmos dicionários de tradução. As páginas HTML são geradas pelo servidor por meio de views [Thymeleaf]; o acesso ao banco de dados é feito pelo [Spring Data JPA] e pelo [Hibernate].

Três papéis de usuário compartilham a aplicação:

Papel
Quem
O que pode fazer
ADMIN
O administrador ([admin])
Ver agendas, marcar e cancelar consultas para qualquer paciente; gerenciar (listar, adicionar, editar, excluir) médicos e clientes
DOCTOR
Médicos
ver agendas, marcar consultas e cancelar consultas de qualquer paciente
USER
clientes (pacientes)
ver agendas sem ver os nomes dos outros pacientes; marcar uma consulta para si mesmos; cancelar sua consulta; gerenciar sua conta; criar uma conta

Principais regras de gestão:

  • nenhuma consulta no passado;
  • um horário só pode ser reservado uma vez por dia;
  • um paciente só pode ter uma consulta futura por vez;
  • dois médicos (ou dois clientes) não podem ter o mesmo nome e sobrenome, e um login pertence a uma única conta;
  • um médico com consultas não pode ser excluído; um cliente é excluído junto com suas consultas;
  • a página de login é protegida contra bots (CAPTCHA, tentativas limitadas), e criar uma conta de cliente exige antes resolver o CAPTCHA dessa página.

11.2. Usando a aplicação

11.2.1. A página de login

Image

A página apresenta dois botões: Entrar e Criar uma conta de paciente. Ambos exigem que você digite os caracteres mostrados na imagem. Os botões FR / EN mudam o idioma:

Image

Um erro (neste caso, um CAPTCHA digitado incorretamente) é exibido no final da página, sobre um fundo rosa claro:

Image

11.2.2. A agenda, vista pelo administrador e pelos médicos

Após o login, o administrador é levado à página da agenda. Ele seleciona um médico e um dia:

Image

Image

Cada horário está disponível (botão Reservar) ou ocupado (nome do paciente, botão Cancelar). Clicar em Reservar abre uma janela que solicita as informações do paciente. Essa janela é gerada pelo servidor, assim como o restante da página: a URL passa a conter o parâmetro [book=4], que é o número do horário selecionado:

Image

Clicar em “Cancelar” exibe uma confirmação (aqui pela Dra. Pélissier, cuja barra de navegação não inclui os menus de administração):

Image

11.2.3. O portal do paciente

Um paciente (papel USER) chega a Minha área: sua próxima consulta, que ele pode cancelar, e links para o gerenciamento de sua conta e para a agenda:

Image

Na agenda, ele vê sua própria consulta (em azul), mas não os nomes dos outros pacientes, que são substituídos por “Reservado”: esse nome nem sequer aparece no código-fonte da página. Como ele já tem uma consulta futura, não pode marcar outra: nenhum botão “Reservar” é exibido (na agenda de outro dia ou de outro médico, em que sua consulta não aparece, uma mensagem explica o motivo):

Image

Um paciente sem consulta pode reservar um horário disponível para si mesmo: a janela de reserva não pede que se selecione um paciente.

Image

Gerenciamento da conta: editar os dados pessoais, alterar a senha ou excluir a conta (e suas consultas). A senha atual é exigida para qualquer alteração:

Image

Um paciente que tenta abrir uma página reservada ao administrador (aqui, [/doctors], digitada manualmente) recebe uma página de erro:

Image

11.2.4. Gerenciamento de médicos e pacientes

O administrador tem dois menus adicionais, Médicos e Pacientes:

Image

Image

O formulário de inclusão de um médico, enviado com erros:

Image

Um nome idêntico ao de um médico existente é rejeitado, mesmo escrito em minúsculas (veremos que é o próprio banco de dados que compara os nomes sem distinguir maiúsculas de minúsculas nem acentos):

Image

A exclusão de um paciente exige confirmação:

Image

11.2.5. Criação de uma conta de paciente

A partir da página de login, o botão “Criar uma conta de paciente” só abre o formulário se o CAPTCHA tiver sido digitado corretamente:

Image

Image

11.3. Instalação e execução

A aplicação está na pasta [rdvmedecins2-spring-mvc], ao lado da pasta [examples]. É um projeto [Maven] independente: não depende do projeto pai que contém os exemplos e tem seu próprio Maven Wrapper (veja adiante). O arquivo [README.md] da pasta contém tudo o que se segue.

11.3.1. Softwares necessários

Dois softwares bastam:

  • o JDK 21 ([Java Development Kit]), que contém o compilador [javac] e a máquina virtual [java]. O [Java] 21 é uma versão LTS (suporte de longo prazo). Uma distribuição gratuita é adequada, por exemplo o [Eclipse Temurin] (https://adoptium.net); no [Linux], o pacote [openjdk-21-jdk]. Verifique a instalação em um terminal:
java -version
1
2
3
openjdk version "21.0.10" 2026-01-20
OpenJDK Runtime Environment (build 21.0.10+7-Ubuntu-124.04)
OpenJDK 64-Bit Server VM (build 21.0.10+7-Ubuntu-124.04, mixed mode, sharing)
  • um servidor [MySQL] 8, por exemplo o do [Laragon] no [Windows] (veja o exemplo 28). O [MariaDB] também serve: a aplicação foi testada com ele.

[Maven] não precisa ser instalado: o script [mvnw] (Maven Wrapper) o baixa automaticamente na primeira execução, e depois o [Maven] baixa as bibliotecas do projeto do repositório [Maven Central]. Portanto, é preciso estar conectado à Internet durante a primeira compilação. O editor recomendado é o [Visual Studio Code], com o “Extension Pack for Java” e o “Spring Boot Extension Pack”; no entanto, tudo pode ser feito pela linha de comando.

11.3.2. Criar o banco de dados

O banco de dados [dbrdvmedecins2] é criado pelo script [database/dbrdvmedecins2.sql]. Usando o [Laragon], abra a ferramenta [HeidiSQL] (botão Banco de dados) e execute o script pelo menu Arquivo / Executar arquivo SQL. Pela linha de comando, na pasta da aplicação:

mysql -u root -p < database/dbrdvmedecins2.sql

A opção [-p] solicita a senha de [root]; omita-a se a conta não tiver senha (como é o caso do [Laragon]). Este é o mesmo banco de dados usado pela versão [ASP.NET Core]: se ele já existir, esta etapa é opcional. O script pode ser executado a qualquer momento para voltar aos dados originais.

11.3.3. Configurar o acesso ao banco de dados

Todos os parâmetros de configuração estão no arquivo [src/main/resources/application.properties] (comentado adiante). Por padrão, a aplicação se conecta ao [MySQL] em [localhost], porta 3306, com o usuário [root] sem senha: esses são os parâmetros padrão do [Laragon]. Se a sua conta [root] tiver senha, o mais simples é escrevê-la neste arquivo, na chave [spring.datasource.password]. Para evitar escrever uma senha em um arquivo do projeto, você também pode informá-la por meio de uma variável de ambiente, que tem precedência sobre o arquivo. Seu nome deriva do nome da chave: letras maiúsculas, com [.] e [-] substituídos por [_]:

1
2
3
export SPRING_DATASOURCE_PASSWORD=myPassword          # Linux, macOS
set SPRING_DATASOURCE_PASSWORD=myPassword             # Windows (cmd)
$env:SPRING_DATASOURCE_PASSWORD="myPassword"          # Windows (PowerShell)

A variável vale apenas para o terminal em que foi definida: a aplicação é então iniciada nele.

11.3.4. Iniciar a aplicação

Abra a pasta [rdvmedecins2-spring-mvc] no [Visual Studio Code] (menu Arquivo / Abrir Pasta), abra um terminal (menu Terminal / Novo Terminal) e digite:

./mvnw spring-boot:run

No [Windows], digite [mvnw spring-boot:run] no prompt de comando, ou [.\mvnw spring-boot:run] no [PowerShell]. Na primeira execução, o [mvnw] baixa o [Maven], que por sua vez baixa as bibliotecas, compila a aplicação e a inicia. Após as mensagens do [Maven], o console exibe as mensagens da aplicação:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

 :: Spring Boot ::                (v4.1.1)

2026-09-25T18:46:42.404+02:00  INFO 19025 --- [  restartedMain] rdvmedecins.RdvMedecinsApplication       : Starting RdvMedecinsApplication using Java 21.0.10 with PID 19025 (/home/serge/cours/rdvmedecins2-spring-mvc/target/classes started by serge in /home/serge/cours/rdvmedecins2-spring-mvc)
2026-09-25T18:46:42.422+02:00  INFO 19025 --- [  restartedMain] rdvmedecins.RdvMedecinsApplication       : The following 1 profile is active: "dev"
2026-09-25T18:46:42.598+02:00  INFO 19025 --- [  restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : Devtools property defaults active! Set 'spring.devtools.add-properties' to 'false' to disable
2026-09-25T18:46:42.598+02:00  INFO 19025 --- [  restartedMain] .e.DevToolsPropertyDefaultsPostProcessor : For additional web related logging consider setting the 'logging.level.web' property to 'DEBUG'
2026-09-25T18:46:43.729+02:00  INFO 19025 --- [  restartedMain] .s.d.r.c.RepositoryConfigurationDelegate : Bootstrapping Spring Data JPA repositories in DEFAULT mode.
2026-09-25T18:46:43.795+02:00  INFO 19025 --- [  restartedMain] .s.d.r.c.RepositoryConfigurationDelegate : Finished Spring Data repository scanning in 55 ms. Found 5 JPA repository interfaces.
2026-09-25T18:46:44.511+02:00  INFO 19025 --- [  restartedMain] o.s.boot.tomcat.TomcatWebServer          : Tomcat initialized with port 8081 (http)
2026-09-25T18:46:44.524+02:00  INFO 19025 --- [  restartedMain] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2026-09-25T18:46:44.525+02:00  INFO 19025 --- [  restartedMain] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/11.0.24]
2026-09-25T18:46:44.552+02:00  INFO 19025 --- [  restartedMain] b.w.c.s.WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 1949 ms
2026-09-25T18:46:44.747+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.jpa                    : HHH008540: Processing PersistenceUnitInfo [name: default]
2026-09-25T18:46:44.783+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.core                   : HHH000001: Hibernate ORM core version 7.4.5.Final
2026-09-25T18:46:45.287+02:00  INFO 19025 --- [  restartedMain] o.s.o.j.p.SpringPersistenceUnitInfo      : No LoadTimeWeaver setup: ignoring JPA class transformer
2026-09-25T18:46:45.317+02:00  INFO 19025 --- [  restartedMain] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Starting...
2026-09-25T18:46:45.487+02:00  INFO 19025 --- [  restartedMain] com.zaxxer.hikari.pool.HikariPool        : HikariPool-1 - Added connection com.mysql.cj.jdbc.ConnectionImpl@4a05c6b0
2026-09-25T18:46:45.488+02:00  INFO 19025 --- [  restartedMain] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Start completed.
2026-09-25T18:46:45.537+02:00  WARN 19025 --- [  restartedMain] org.hibernate.orm.core                   : HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported, hence certain features may not work properly.The minimum supported version is 8.0.0. Check the community dialects project for available legacy versions.
2026-09-25T18:46:45.554+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.connections.pooling    : HHH10001005: Database info:
    Database JDBC URL [jdbc:mysql://localhost:3306/dbrdvmedecins2]
    Database driver: MySQL Connector/J
    Database dialect: MySQLDialect
    Database version: 5.5.5
    Default catalog/schema: dbrdvmedecins2/undefined
    Autocommit mode: undefined/unknown
    Isolation level: REPEATABLE_READ [default REPEATABLE_READ]
    JDBC fetch size: none
    Pool: DataSourceConnectionProvider
    Minimum pool size: undefined/unknown
    Maximum pool size: undefined/unknown
2026-09-25T18:46:47.573+02:00  INFO 19025 --- [  restartedMain] org.hibernate.orm.core                   : HHH000489: No JTA platform available (set 'hibernate.transaction.jta.platform' to enable JTA platform integration)
2026-09-25T18:46:47.597+02:00  INFO 19025 --- [  restartedMain] j.LocalContainerEntityManagerFactoryBean : Initialized JPA EntityManagerFactory for persistence unit 'default'
2026-09-25T18:46:47.688+02:00  INFO 19025 --- [  restartedMain] o.s.d.j.r.query.QueryEnhancerFactories   : Hibernate is in classpath; If applicable, HQL parser will be used.
Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,d1_0.`user`,d1_0.version from doctors d1_0 left join users u1_0 on u1_0.id=d1_0.`user` order by d1_0.last_name,d1_0.first_name
Hibernate: select c1_0.id,c1_0.first_name,c1_0.last_name,c1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,c1_0.`user`,c1_0.version from clients c1_0 left join users u1_0 on u1_0.id=c1_0.`user` order by c1_0.last_name,c1_0.first_name
2026-09-25T18:46:52.549+02:00  INFO 19025 --- [  restartedMain] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 8081 (http) with context path '/'
2026-09-25T18:46:52.563+02:00  INFO 19025 --- [  restartedMain] rdvmedecins.RdvMedecinsApplication       : Started RdvMedecinsApplication in 10.82 seconds (process running for 11.321)
2026-09-25T18:46:52.928+02:00  INFO 19025 --- [omcat-handler-0] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet 'dispatcherServlet'
2026-09-25T18:46:52.929+02:00  INFO 19025 --- [omcat-handler-0] o.s.web.servlet.DispatcherServlet        : Initializing Servlet 'dispatcherServlet'
2026-09-25T18:46:52.930+02:00  INFO 19025 --- [omcat-handler-0] o.s.web.servlet.DispatcherServlet        : Completed initialization in 1 ms

Voltaremos a este console na seção “Inicialização da aplicação”. Por ora, observe a linha [Tomcat started on port 8081]: a aplicação está pronta no endereço [http://localhost:8081]. A porta 8081 permite executar ao mesmo tempo um exemplo do curso (porta 5000). A versão [ASP.NET Core] da aplicação também escuta na porta 8081: não execute as duas ao mesmo tempo.

Pare a aplicação digitando [Ctrl-C] no terminal.

11.3.5. Contas de demonstração

A senha de cada conta é o seu nome de usuário; você também deve digitar os caracteres da imagem, em maiúsculas ou minúsculas:

Nome de usuário
Papel
[admin]
ADMIN (o administrador)
[pelissier], [tatou], [dupont]
DOCTOR (os médicos)
[martin], [durand], [bistrou], [german]
USER (pacientes)

Um roteiro para explorar a aplicação:

  • [admin]: agenda, da Sra. Marie PELISSIER, hoje: um horário já está reservado pela Sra. Brigitte BISTROU. Reserve um horário para o Sr. Jean MARTIN e depois tente marcar uma segunda consulta para ele (recusada). Menus Médicos e Pacientes: adicionar, editar, excluir (a Dra. PELISSIER, que tem consultas, não pode ser excluída);
  • [pelissier]: sua agenda do dia é exibida diretamente; o endereço [/doctors], digitado manualmente, retorna uma página de erro 403;
  • [martin]: Minha área, sua consulta, a agenda em que os outros pacientes aparecem como “Reservado”; Gerenciar minha conta;
  • página de login: Criar uma conta de paciente e depois entrar com a nova conta;
  • Botões FR / EN: toda a interface muda de idioma, inclusive as datas.

11.3.6. Modo de desenvolvimento

O comando [./mvnw spring-boot:run] inicia a aplicação com o perfil [dev] (veja [pom.xml], adiante): o console passa então a exibir cada comando SQL enviado ao banco de dados pelo [Hibernate] (as duas linhas [Hibernate: select ...] no console acima). Duas outras ferramentas facilitam o desenvolvimento:

  • a biblioteca [Spring Boot DevTools] (veja [pom.xml]) reinicia automaticamente a aplicação assim que uma classe é recompilada na pasta [target/classes]. O [Visual Studio Code] recompila um arquivo [.java] a cada gravação; sem ele, seria preciso digitar [./mvnw compile] em um segundo terminal. A reinicialização leva apenas alguns segundos: somente as classes da aplicação são recarregadas, não as bibliotecas. Já uma view [templates/*.html] modificada é recarregada na próxima vez que a página for exibida, depois de copiada para [target/classes] da mesma forma;
  • o depurador: com o “Extension Pack for Java”, os links Run e Debug aparecem acima do método [main] em [RdvMedecinsApplication.java]; Debug inicia a aplicação sob o controle do depurador. Defina um ponto de interrupção clicando na margem de uma linha de código. A view Spring Boot Dashboard do “Spring Boot Extension Pack” oferece os mesmos comandos.

11.3.7. Um arquivo executável

Para instalar a aplicação em um servidor, empacote-a em um único arquivo:

./mvnw package
java -jar target/rdvmedecins-1.0.jar

O primeiro comando compila a aplicação e cria o arquivo [target/rdvmedecins-1.0.jar] (cerca de 60 MB): ele contém a aplicação, todas as suas bibliotecas e o próprio servidor [Tomcat]. O segundo comando o inicia: só é necessário um JDK (ou um JRE) 21 na máquina. Quando iniciada assim, a aplicação não tem o perfil [dev] (o console não exibe os comandos SQL), e o [Spring Boot DevTools] não está no arquivo. Cada chave de [application.properties] pode ser substituída na linha de comando, por exemplo, com [java -jar target/rdvmedecins-1.0.jar --server.port=9000].

11.3.8. Problemas comuns

Na inicialização, o [Hibernate] consulta o banco de dados para determinar sua versão, e em seguida a aplicação lê nele as listas de médicos e clientes: se o banco de dados estiver inacessível, a aplicação para imediatamente, com um erro exibido no console. Esse erro costuma estar enterrado em uma longa pilha de chamadas, e a última linha, [Caused by: ...], não é muito descritiva ([Unable to determine Dialect without JDBC metadata]: o [Hibernate] não conseguiu consultar o banco de dados). Procure, em vez disso, a mensagem do próprio banco de dados, que o [Hibernate] também escreve em um aviso no início do erro. Por exemplo, com um banco de dados que não existe:

1
2
3
4
5
6
... WARN ... org.hibernate.orm.jdbc.error : HHH000247: ErrorCode: 1049, SQLState: 42000
... WARN ... org.hibernate.orm.jdbc.error : Unknown database 'dbunknown'
...
Caused by: java.sql.SQLSyntaxErrorException: Unknown database 'dbunknown'
...
Caused by: org.hibernate.HibernateException: Unable to determine Dialect without JDBC metadata (please set 'jakarta.persistence.jdbc.url' for common cases or 'hibernate.dialect' when a custom Dialect implementation must be provided)

As mensagens mais comuns:

Mensagem
Causa provável
[Communications link failure] ou [Connection refused]
[MySQL] não foi iniciado ou não está escutando em [localhost:3306]
[Access denied for user 'root'@'localhost']
É preciso informar a senha do [MySQL] (veja “Configurar o acesso ao banco de dados”)
[Unknown database 'dbrdvmedecins2']
O script [database/dbrdvmedecins2.sql] não foi executado
[rdvmedecins.auth.jwt-secret must be at least 32 characters long]
A chave secreta dos tokens é curta demais em [application.properties]
[Port 8081 was already in use]
A porta 8081 já está em uso (a versão [ASP.NET Core] está em execução?): pare-a ou mude [server.port]
[JAVA_HOME is not set] ou [release version 21 not supported]
O JDK está ausente ou é anterior à versão 21
[Could not transfer artifact] durante a execução do [mvnw]
O repositório [Maven Central] está inacessível (sem conexão com a Internet, proxy)

Com o [MariaDB], o [Hibernate] também exibe um aviso inofensivo na inicialização: [HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported]. Na verdade, o [MariaDB] se apresenta ao driver do [MySQL] com o número de versão “5.5.5”, que o [Hibernate] interpreta como um [MySQL] muito antigo.

11.4. A arquitetura da aplicação

Image

  • O navegador envia suas requisições ao servidor [Tomcat], integrado à aplicação. Cada requisição passa primeiro pela cadeia de filtros do [Spring Security] (configurada por [config/SecurityConfig.java]), que identifica o usuário com base no token JWT de seu cookie e nega o acesso às páginas protegidas;
  • [controllers]: os controllers da camada web. Todos passam por um único bean, o [ApplicationModel] (arquivo [web]), que armazena em memória as listas de médicos e clientes e encaminha as demais requisições à camada de negócio;
  • [auth]: o login, os tokens JWT, o CAPTCHA, os limites de tentativas e o passe de criação de conta;
  • [web]: elementos comuns à camada web: o cache e a fachada [ApplicationModel], a tradução, as mensagens flash, a validação, os atributos comuns a todas as views e o tratamento de exceções; [models]: os modelos de formulários e de views;
  • [business]: as regras de negócio e as transações;
  • [repositories]: a camada DAO, uma interface [Spring Data JPA] por tabela;
  • [entities]: as entidades [JPA], que o [Hibernate] lê e grava no banco de dados; [domain]: os objetos da agenda, calculados pela camada de negócio;
  • [templates]: as views [Thymeleaf], que geram as páginas HTML; [i18n]: os dicionários, usados pelo tradutor; [static]: a folha de estilo, o script da página e o [Bootstrap];
  • [config]: a configuração escrita em [Java] (segurança, idioma, mensagens flash, propriedades tipadas); [RdvMedecinsApplication.java] inicia todo o conjunto.

A pasta da aplicação:

rdvmedecins2-spring-mvc/
├── .mvn/
│   └── wrapper/
│       └── maven-wrapper.properties
├── database/
│   ├── dbrdvmedecins2.sql
│   └── README.md
├── src/
│   └── main/
│       ├── java/
│       │   └── rdvmedecins/
│       │       ├── auth/
│       │       │   ├── AuthService.java
│       │       │   ├── Captcha.java
│       │       │   ├── CaptchaService.java
│       │       │   ├── CaptchaDrawing.java
│       │       │   ├── AttemptLimiterService.java
│       │       │   ├── RegistrationPassService.java
│       │       │   ├── README.md
│       │       │   ├── InvalidSessionException.java
│       │       │   └── ConnectedUser.java
│       │       ├── config/
│       │       │   ├── AuthProperties.java
│       │       │   ├── ProtectionProperties.java
│       │       │   ├── README.md
│       │       │   ├── SecurityConfig.java
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   ├── ScheduleController.java
│       │       │   ├── AuthController.java
│       │       │   ├── ClientsController.java
│       │       │   ├── ErrorController.java
│       │       │   ├── PatientAreaController.java
│       │       │   ├── RegistrationController.java
│       │       │   ├── LanguageController.java
│       │       │   ├── DoctorsController.java
│       │       │   ├── PersonsControllerBase.java
│       │       │   └── README.md
│       │       ├── domain/
│       │       │   ├── DoctorDaySchedule.java
│       │       │   ├── DoctorDaySlot.java
│       │       │   └── README.md
│       │       ├── entities/
│       │       │   ├── AbstractEntity.java
│       │       │   ├── Client.java
│       │       │   ├── Slot.java
│       │       │   ├── Doctor.java
│       │       │   ├── Person.java
│       │       │   ├── README.md
│       │       │   ├── Role.java
│       │       │   ├── Appointment.java
│       │       │   └── User.java
│       │       ├── business/
│       │       │   ├── Dates.java
│       │       │   ├── PersonData.java
│       │       │   ├── Business.java
│       │       │   ├── BusinessException.java
│       │       │   ├── BusinessService.java
│       │       │   └── README.md
│       │       ├── models/
│       │       │   ├── Forms.java
│       │       │   ├── ViewModels.java
│       │       │   ├── README.md
│       │       │   └── InputRules.java
│       │       ├── repositories/
│       │       │   ├── ClientRepository.java
│       │       │   ├── SlotRepository.java
│       │       │   ├── DoctorRepository.java
│       │       │   ├── PersonRepository.java
│       │       │   ├── README.md
│       │       │   ├── AppointmentRepository.java
│       │       │   └── UserRepository.java
│       │       ├── web/
│       │       │   ├── ApplicationModel.java
│       │       │   ├── CookieFlashMapManager.java
│       │       │   ├── Flash.java
│       │       │   ├── HtmlExceptionHandler.java
│       │       │   ├── FlashMessage.java
│       │       │   ├── CommonModel.java
│       │       │   ├── Utils.java
│       │       │   ├── README.md
│       │       │   ├── Translator.java
│       │       │   ├── FlashType.java
│       │       │   └── Validation.java
│       │       └── RdvMedecinsApplication.java
│       └── resources/
│           ├── i18n/
│           │   ├── en.json
│           │   └── fr.json
│           ├── static/
│           │   ├── css/
│           │   │   └── styles.css
│           │   ├── js/
│           │   │   └── app.js
│           │   └── lib/
│           │       └── bootstrap/
│           │           ├── css/
│           │           │   └── bootstrap.min.css
│           │           └── LICENSE
│           ├── templates/
│           │   ├── fragments/
│           │   │   ├── captcha.html
│           │   │   ├── person-fields.html
│           │   │   ├── confirmation.html
│           │   │   ├── errors.html
│           │   │   ├── flash.html
│           │   │   ├── navbar.html
│           │   │   └── booking.html
│           │   ├── persons/
│           │   │   ├── form.html
│           │   │   └── list.html
│           │   ├── schedule.html
│           │   ├── account.html
│           │   ├── error.html
│           │   ├── area.html
│           │   ├── registration.html
│           │   ├── layout.html
│           │   ├── login.html
│           │   └── README.md
│           ├── application-dev.properties
│           └── application.properties
├── mvnw
├── mvnw.cmd
├── pom.xml
└── README.md

Esta é a organização padrão de um projeto [Maven], como visto nos exemplos: o código [Java] em [src/main/java], organizado em pacotes (um pacote [Java] é uma pasta de classes, cujo nome, aqui, por exemplo, [rdvmedecins.web], reflete o caminho); todo o resto (configuração, views, dicionários, arquivos estáticos) em [src/main/resources]. Durante a compilação, o [Maven] copia o conteúdo de [src/main/resources] para [target/classes], junto das classes compiladas: juntos, eles formam o classpath da aplicação, o conjunto de pastas e arquivos em que a máquina virtual procura classes e arquivos. É por isso que o código se refere a um dicionário como [i18n/fr.json], sem o prefixo [src/main/resources]. A pasta [target], criada pelo [Maven], não é mostrada.

Cada pasta principal contém um arquivo chamado [README.md] que lista seus arquivos. A tabela a seguir compara as pastas das duas versões da aplicação:

ASP.NET Core MVC
Spring MVC
Conteúdo
[Program.cs]
[RdvMedecinsApplication.java], [config/]
Inicialização, configuração
[Config/]
[config/]
propriedades tipadas
[Auth/]
[auth/]
Autenticação
[Controllers/]
[controllers/]
controllers
[Web/], [Models/]
[web/], [models/]
Serviços comuns da camada web, templates
[Business/]
[business/]
camada de negócio
[Repositories/], [Data/]
[repositories/]
camada DAO
[Entities/], [Domain/]
[entities/], [domain/]
entidades, itens da agenda
[Views/]
[templates/]
views
[i18n/]
[i18n/]
dicionários
[wwwroot/]
[static/]
arquivos estáticos
[appsettings.json]
[application.properties]
Configuração
[RdvMedecins.csproj]
[pom.xml]
O arquivo do projeto

A seguir, comentamos todos os arquivos, das camadas inferiores (banco de dados) às camadas superiores (views).

11.5. O banco de dados

O banco de dados [dbrdvmedecins2] é criado pelo script [database/dbrdvmedecins2.sql] (veja “Criar o banco de dados”). É, palavra por palavra, o script da versão [ASP.NET Core], precedido de uma linha [SET NAMES]: as duas aplicações podem trabalhar sobre o mesmo banco de dados, e uma pode substituir a outra sem nenhuma alteração. Demonstramos isso com dois trechos: a estrutura e, em seguida, os dados.

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Banco de dados [dbrdvmedecins2] - MySQL 8
--
-- Evolução de [dbrdvmedecins]:
--   1. as tabelas [doctors] e [clients] ganham uma coluna [user],
--      chave estrangeira para users(id): cada médico e cada cliente é
--      agora também um usuário capaz de fazer login;
--   2. um terceiro papel aparece: DOCTOR (além de ADMIN e USER);
--   3. o script cria uma linha em [users] para cada médico (papel DOCTOR)
--      e para cada cliente (papel USER):
--        - login        = sobrenome em minúsculas
--        - senha        = sobrenome em minúsculas, com hash bcrypt (10 rounds)
--        - nome de exibição = nome + sobrenome
--
--   4. restrições de unicidade, todas NOMEADAS (a aplicação reconhece
--      o nome da restrição violada na mensagem de erro do MySQL):
--        - unq_users_login                   : um login pertence a uma única conta;
--        - unq_doctors_first_name_last_name  : dois médicos não podem ter o
--                                              mesmo nome e sobrenome;
--        - unq_clients_first_name_last_name  : o mesmo para os clientes.
--      Atenção: a collation utf8mb4_unicode_ci compara sem distinguir
--      maiúsculas de minúsculas nem acentos - "Hélène DUPONT" e "helene dupont"
--      são, portanto, consideradas idênticas.
--
-- A tabela [users] agora deve ser criada ANTES de [doctors] e [clients]
-- (elas a referenciam) e removida DEPOIS delas.
-- =========================================================================

-- o script é escrito em UTF-8
SET NAMES utf8mb4;

-- recomeçamos de um banco de dados vazio a cada execução do script (prático em desenvolvimento)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- ordem de remoção: das tabelas "filhas" para as tabelas "pais"
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;

-- -------------------------------------------------------------------------
-- tabela [users]: os usuários autorizados a fazer login na aplicação
-- -------------------------------------------------------------------------
CREATE TABLE users (
  id       INT AUTO_INCREMENT PRIMARY KEY,
  version  INT NOT NULL DEFAULT 0,
  login    VARCHAR(30) NOT NULL,                 -- login identifier
  password VARCHAR(100) NOT NULL,                -- HASHED password (bcrypt) - never in clear
  name     VARCHAR(40) NOT NULL,                 -- name displayed once logged in
  role     VARCHAR(10) NOT NULL,                 -- 'ADMIN', 'DOCTOR' or 'USER'
  -- um login pode pertencer a uma única conta
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- tabela [doctors]: os médicos do consultório
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
  id         INT AUTO_INCREMENT PRIMARY KEY,   -- primary key (technical identifier)
  version    INT NOT NULL DEFAULT 0,            -- row version number (optimistic lock)
  title      VARCHAR(5)  NOT NULL,              -- Melle, Mme, Mr
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- uma conta por médico e um médico por conta
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- dois médicos não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabela [clients]: os pacientes dos médicos
-- -------------------------------------------------------------------------
CREATE TABLE clients (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  title      VARCHAR(5)  NOT NULL,
  last_name  VARCHAR(20) NOT NULL,
  first_name VARCHAR(20) NOT NULL,
  `user`     INT NOT NULL,                      -- foreign key -> users(id)
  CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
  -- uma conta por cliente e um cliente por conta
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- dois clientes não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabela [slots]: os horários de cada médico
-- -------------------------------------------------------------------------
CREATE TABLE slots (
  id           INT AUTO_INCREMENT PRIMARY KEY,
  version      INT NOT NULL DEFAULT 0,
  doctor_id    INT NOT NULL,                     -- foreign key -> doctors(id)
  start_hour   INT NOT NULL,                     -- start hour of the slot
  start_minute INT NOT NULL,                     -- start minute of the slot
  end_hour     INT NOT NULL,                     -- end hour of the slot
  end_minute   INT NOT NULL,                     -- end minute of the slot
  CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);

-- -------------------------------------------------------------------------
-- tabela [appointments]: as consultas marcadas pelos clientes
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  version    INT NOT NULL DEFAULT 0,
  day        DATE NOT NULL,                      -- day of the appointment
  slot_id    INT NOT NULL,                       -- foreign key -> slots(id)
  client_id  INT NOT NULL,                       -- foreign key -> clients(id)
  CONSTRAINT fk_appointments_slot   FOREIGN KEY (slot_id)   REFERENCES slots(id),
  CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
  -- o mesmo horário, no mesmo dia, só pode ser reservado uma vez
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

Vamos comentar esta primeira parte:

  • linha 30: o script informa ao servidor que está escrito em UTF-8. Sem esta linha, o cliente [mysql] de certos sistemas enviaria os caracteres acentuados (“Hélène”) em outra codificação, e eles seriam armazenados incorretamente;
  • linha 33: o banco de dados é criado se ainda não existir, com o conjunto de caracteres [utf8mb4] e a collation [utf8mb4_unicode_ci], como no exemplo 28: as comparações de strings ignoram maiúsculas e acentos. Isso vale também para as restrições de unicidade: [Hélène DUPONT] e [helene dupont] são, para o [MySQL], duas ocorrências da mesma pessoa, e “Admin” é o mesmo login que “admin”;
  • Linhas 37–41: o script parte de um banco de dados vazio a cada execução. As tabelas são excluídas das tabelas “filhas” para as tabelas “pais”: uma tabela referenciada por uma chave estrangeira ([users], por exemplo, referenciada por [doctors] e [clients]) não pode ser excluída enquanto outra tabela ainda a referenciar. As tabelas são criadas na ordem inversa;
  • linhas 46–55: as contas de usuário. Cada tabela começa com uma chave primária [id], atribuída pelo banco de dados ([AUTO_INCREMENT]), e uma coluna [version], que vale 0 quando a linha é criada;
  • linhas 49–52: o login, a senha, o nome de exibição após o login e o papel ([ADMIN], [DOCTOR], ou [USER]). A coluna [password] nunca contém a senha em si, mas o seu hash, [bcrypt] (veja o exemplo 25): 60 caracteres, que a coluna (100 caracteres) comporta com folga;
  • Linha 54: um login pertence a uma única conta. Como no exemplo 28, a restrição é nomeada: quando o [MySQL] rejeita uma operação de escrita, sua mensagem de erro especifica o nome da restrição violada, e a camada de negócio usa isso para escolher a mensagem a exibir (veja “A camada de negócio”);
  • linhas 60–72: os médicos: título, sobrenome, nome;
  • linha 62: a coluna [version] é usada para o bloqueio otimista (veja o exemplo 28): ela é incrementada a cada modificação da linha, o que permite detectar se outro usuário modificou a linha entre o momento em que ela foi lida e o momento em que foi gravada. Aqui, quem a incrementa é o [Hibernate] , graças à anotação [@Version] das entidades (veja “Entidades”);
  • Linhas 66–67: cada médico tem uma conta: a coluna [user] é uma chave estrangeira que referencia [users(id)]. O banco de dados rejeita um valor que não se refira a nenhuma conta e se recusa a excluir uma conta que ainda seja referenciada por um médico. Como [user] é uma palavra reservada do [MySQL], o nome da coluna é colocado entre crases;
  • linha 69: uma conta pertence a um único médico: a relação entre [doctors] e [users] é uma relação “um para um”;
  • linha 71: dois médicos não podem ter o mesmo nome e sobrenome. A restrição se aplica ao par de colunas: dois médicos podem ter o mesmo sobrenome se não tiverem o mesmo nome. Um médico e um cliente, porém, podem ter o mesmo sobrenome: são duas tabelas diferentes;
  • Linhas 77–89: os clientes (pacientes) seguem o mesmo modelo: uma conta por cliente (chave estrangeira [fk_clients_user], restrição de unicidade [unq_clients_user]); dois clientes não podem ter o mesmo nome e sobrenome;
  • linhas 94–103: os horários de cada médico (chave estrangeira [doctor_id]): hora e minuto de início, hora e minuto de término. Um horário não tem data: ele se repete todos os dias;
  • linhas 108–118: as consultas: uma data (tipo [DATE], sem hora), um horário e um cliente, identificados por duas chaves estrangeiras;
  • linha 117: o mesmo horário só pode ser reservado uma vez por dia. O próprio banco de dados garante essa regra: se dois usuários reservarem o mesmo horário ao mesmo tempo, o segundo [INSERT] é rejeitado, independentemente do que a aplicação tenha verificado logo antes.

A segunda parte do script insere os dados de exemplo:

-- =========================================================================
-- Dados de demonstração
-- =========================================================================

-- os usuários: senhas com hash bcrypt (10 rounds de salt)
--   admin/admin (ADMIN)
--   uma conta DOCTOR por médico, uma conta USER por cliente
--   (a conta de demonstração user/user não existe mais: uma conta USER agora é
--   SEMPRE a conta de um cliente, que pode marcar e gerenciar consultas)
--   (login = senha = sobrenome em minúsculas)
INSERT INTO users (login, password, name, role) VALUES
  ('admin',     '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator',    'ADMIN'),
  -- doctors
  ('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER',  'DOCTOR'),
  ('tatou',     '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU',       'DOCTOR'),
  ('dupont',    '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT',    'DOCTOR'),
  -- clients
  ('martin',    '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN',      'USER'),
  ('durand',    '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND',     'USER'),
  ('bistrou',   '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
  ('german',    '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN',       'USER');

-- os médicos: a coluna [user] é buscada a partir do login,
-- em vez de supor os valores das chaves primárias de [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
  ('Mme',  'PELISSIER', 'Marie',  (SELECT id FROM users WHERE login = 'pelissier')),
  ('Mr',   'TATOU',     'Paul',   (SELECT id FROM users WHERE login = 'tatou')),
  ('Melle','DUPONT',    'Sophie', (SELECT id FROM users WHERE login = 'dupont'));

INSERT INTO clients (title, last_name, first_name, `user`) VALUES
  ('Mr',   'MARTIN',  'Jean',     (SELECT id FROM users WHERE login = 'martin')),
  ('Mme',  'DURAND',  'Alice',    (SELECT id FROM users WHERE login = 'durand')),
  ('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
  ('Mr',   'GERMAN',  'Luc',      (SELECT id FROM users WHERE login = 'german'));

-- horários do médico PELISSIER (doctor_id = 1): das 8h às 12h, de 20 em 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- horários do médico TATOU (doctor_id = 2): das 14h às 18h, de 20 em 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- uma consulta já marcada, para ver de imediato um horário ocupado na agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • linhas 5–21: as contas de demonstração: o administrador, três médicos (papel [DOCTOR]) e quatro clientes (papel [USER]). A senha de cada usuário é o seu login ([admin] / [admin], [pelissier] / [pelissier]...). Os hashes começam com [$2b$10$]: o algoritmo [bcrypt], em sua versão [2b], com custo 10 (veja o exemplo 25). O encoder [BCryptPasswordEncoder] do [Spring Security], configurado para essa mesma versão, consegue verificá-los (veja “Autenticação”);
  • linhas 25–28: a coluna [user] de cada médico é obtida por meio de uma subconsulta sobre o login, em vez de pressupor os identificadores atribuídos pelo banco de dados às contas;
  • linhas 30–34: os clientes são tratados da mesma forma;
  • linhas 36–41: doze horários de 20 minutos, das 8h às 12h, para a Dra. PELISSIER. Aqui, o ID do médico (1) é escrito diretamente no código: a tabela [doctors] acabou de ser criada, portanto seus IDs começam em 1;
  • linhas 43–48: doze horários, das 14h às 18h, para o Dr. TATOU. O Dr. DUPONT não tem horários: sua agenda está vazia;
  • linhas 50–52: uma consulta já foi marcada para Brigitte BISTROU (cliente nº 3) no segundo horário da Dra. PELISSIER (8h20). [CURDATE()] é a data em que o script é executado: no primeiro login, a agenda de hoje mostra um horário já reservado.

11.6. Configuração do projeto

11.6.1. pom.xml

O arquivo [pom.xml] ([Project Object Model]) descreve o projeto no [Maven]: seu identificador, a versão do [Java], as bibliotecas usadas e como iniciar a aplicação. É o equivalente do arquivo [RdvMedecins.csproj] da versão [ASP.NET Core]. Os exemplos tinham, cada um, um arquivo [pom.xml], todos derivados de um arquivo [pom.xml] comum, localizado na pasta [examples]; o estudo de caso, um projeto independente, escreve tudo em seu próprio arquivo.

<?xml version="1.0" encoding="UTF-8"?>
<!--
  =========================================================================
  pom.xml - o arquivo de projeto Maven: identidade do projeto, versão do Java,
  bibliotecas usadas e plugin que compila e executa a aplicação.

  As bibliotecas (dependências) são baixadas do Maven Central
  durante o primeiro build e armazenadas na pasta ~/.m2 do
  usuário. Suas versões não são escritas aqui: elas são definidas,
  todas compatíveis entre si, pelo projeto parent do Spring Boot.
  =========================================================================
-->
<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>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>
    <relativePath/>
  </parent>

  <groupId>course.springmvc</groupId>
  <artifactId>rdvmedecins</artifactId>
  <version>1.0</version>
  <name>RdvMedecins</name>

  <properties>
    <!-- Java 21, versão LTS (suporte de longo prazo) -->
    <java.version>21</java.version>
  </properties>

  <dependencies>
    <!-- Spring MVC e o servidor web Tomcat, embutido na aplicação -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <!-- as views Thymeleaf -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- validação de formulários (Bean Validation, Hibernate Validator) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- Spring Security: autenticação por token JWT, papéis, hash bcrypt -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
    </dependency>
    <!-- Spring Data JPA: o ORM Hibernate, transações, repositórios -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <!-- o driver JDBC do MySQL (serve também para o MariaDB) -->
    <dependency>
      <groupId>com.mysql</groupId>
      <artifactId>mysql-connector-j</artifactId>
      <scope>runtime</scope>
    </dependency>
    <!-- as ferramentas de desenvolvimento: reinício automático após uma alteração -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-devtools</artifactId>
      <optional>true</optional>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <!-- mvnw spring-boot:run executa a aplicação, com o perfil [dev]
           (veja src/main/resources/application-dev.properties) -->
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <configuration>
          <profiles>
            <profile>dev</profile>
          </profiles>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Vamos comentar este arquivo:

  • Linhas 18–23: o projeto pai, [spring-boot-starter-parent], na versão 4.1.1 do [Spring Boot]. O projeto herda suas configurações: a codificação UTF-8 dos arquivos-fonte, a configuração do compilador, a configuração dos plugins e, principalmente, as versões de todas as bibliotecas que o [Spring Boot] pode integrar, escolhidas para serem compatíveis entre si. É por isso que nenhuma das dependências listadas a seguir especifica sua versão. Para atualizar para uma versão mais recente do [Spring Boot], basta alterar a linha 21;
  • linha 22: o elemento vazio [relativePath] diz ao [Maven] para não procurar o pai na pasta superior do projeto (que era onde ficava o pai dos exemplos), mas nos repositórios de bibliotecas;
  • linhas 25–28: a identidade do projeto: o grupo (um nome de domínio invertido, por convenção), o nome do artefato, sua versão e um nome legível. O arquivo criado por [./mvnw package] se chama [artifact-version.jar], ou seja, [rdvmedecins-1.0.jar]. Como nenhum elemento [packaging] é informado, trata-se de um arquivo [jar], que é o caso padrão;
  • linhas 30–33: a versão do [Java]: o compilador gera código para o [Java] 21 e se recusa a compilar com um JDK mais antigo;
  • linhas 35–73: as dependências. Quase todas são starters do [Spring Boot]: um starter é uma dependência que não fornece código próprio, mas traz um conjunto coerente de bibliotecas para determinada funcionalidade. Cada starter também aciona a autoconfiguração correspondente na inicialização (veja “Inicialização da aplicação”);
  • linhas 37–40: o [Spring MVC] e o servidor web [Tomcat], integrado à aplicação: não é preciso instalar nenhum servidor; a própria aplicação é um servidor web;
  • linhas 42–45: a engine de views [Thymeleaf] (veja o exemplo 13);
  • linhas 47–50: validação de formulários: a API [Bean Validation] ([@NotBlank], [@Size]...) e sua implementação, [Hibernate Validator] (veja o exemplo 19);
  • linhas 52–55: o [Spring Security], com seu módulo de “servidor de recursos” [OAuth2], que pode verificar um token JWT (veja o exemplo 25). Ele fornece também o hash [bcrypt] para senhas: sem biblioteca separada;
  • linhas 57–60: o [Spring Data JPA], junto com o ORM [Hibernate], o gerenciador de transações e o pool de conexões [HikariCP] (veja o exemplo 28);
  • linhas 62–66: o driver JDBC do [MySQL] e [mysql-connector-j], que também serve para o [MariaDB]. O escopo [runtime] (linha 65) significa que o código da aplicação não precisa dele para ser compilado (ele só se comunica com o JPA e o JDBC); o driver é carregado apenas em tempo de execução;
  • linhas 68–72: o [Spring Boot DevTools], as ferramentas de desenvolvimento (reinicialização automática). [optional] (linha 71): a dependência não é repassada aos projetos que dependam deste, e o plugin do [Spring Boot] não a inclui no arquivo executável: ela é usada apenas durante o desenvolvimento;
  • Linhas 79–87: o plugin do [Spring Boot] para o [Maven]. Esse plugin fornece o comando [spring-boot:run] e, durante uma execução de [./mvnw package], converte o arquivo [jar] padrão em um arquivo executável que contém todas as bibliotecas;
  • Linhas 82–86: [spring-boot:run] ativa o perfil [dev], que adiciona o arquivo [application-dev.properties] à configuração (veja adiante). Um perfil é um nome que designa um conjunto de configurações; este se aplica apenas ao [spring-boot:run]: uma aplicação iniciada por [java -jar] não tem nenhum perfil ativo, a menos que um seja especificado ([java -jar target/rdvmedecins-1.0.jar --spring.profiles.active=dev]).

11.6.2. O Maven Wrapper

O Maven Wrapper permite compilar o projeto sem ter o [Maven] instalado. Ele é composto por três arquivos:

  • [mvnw] (para [Linux] e [macOS]) e [mvnw.cmd] (para [Windows]): dois scripts, fornecidos pelo projeto [Apache Maven], que não devem ser modificados e não são reproduzidos aqui. Eles leem o arquivo seguinte, baixam a versão do [Maven] nele especificada, caso ainda não esteja presente, a colocam na pasta [.m2/wrapper] dentro do diretório pessoal do usuário e, em seguida, executam o comando: [./mvnw spring-boot:run] executa [mvn spring-boot:run] com a versão correta do [Maven];
  • [.mvn/wrapper/maven-wrapper.properties]:
1
2
3
wrapperVersion=3.3.4
distributionType=only-script
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
  • linha 1: a versão do próprio Maven Wrapper;
  • linha 2: [only-script]: o wrapper é composto somente pelos scripts [mvnw] e [mvnw.cmd], sem o arquivo [maven-wrapper.jar] usado por suas versões anteriores;
  • linha 3: o link de download da distribuição do [Maven]: versão 3.9.11. Todos que compilam o projeto usam assim a mesma versão do [Maven], qualquer que seja a versão instalada em sua máquina.

As bibliotecas baixadas pelo [Maven] são armazenadas na pasta [.m2/repository] dentro do diretório pessoal: elas são compartilhadas por todos os projetos e baixadas uma única vez.

11.6.3. src/main/resources/application.properties

O arquivo [application.properties] tem a mesma função do arquivo [appsettings.json] da versão [ASP.NET Core]. Cada linha associa um valor a uma chave; as chaves são separadas por pontos ([spring.datasource.url]). O [Spring Boot] contém centenas de chaves que configuram seus componentes (as que começam com [server.], [spring.] etc.); a aplicação pode acrescentar as suas próprias (neste caso, as que começam com [rdvmedecins.]). Uma linha que começa com [#] é um comentário.

# =========================================================================
# application.properties - a configuração da aplicação.
#
# Cada valor pode ser substituído sem modificar este arquivo, por uma
# variável de ambiente: spring.datasource.password é então escrita
# SPRING_DATASOURCE_PASSWORD (maiúsculas, "." e "-" substituídos por "_").
# =========================================================================

# a porta de escuta: nem 8080 (porta padrão do Spring Boot, frequentemente já
# ocupada), nem 5000 (a dos exemplos) - assim tudo pode rodar ao mesmo tempo
server.port=8081

# ——— o banco de dados MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# o Hibernate não cria nem modifica as tabelas: esse é o papel do script SQL
spring.jpa.hibernate.ddl-auto=none
# a conexão com o banco de dados não é mantida aberta enquanto a view é construída
spring.jpa.open-in-view=false

# ——— as requisições são processadas por threads "virtuais" (Java 21): uma
# thread que espera pelo banco de dados não bloqueia mais uma thread do sistema
spring.threads.virtual.enabled=true

# ——— as respostas de erro nunca contêm o stack trace
spring.web.error.include-stacktrace=never

# ——— autenticação (veja config/AuthProperties.java)
# chave secreta dos tokens JWT: pelo menos 32 caracteres (HMAC-SHA256).
# Deve absolutamente ser alterada em produção (string aleatória longa).
rdvmedecins.auth.jwt-secret=change-me-to-a-long-random-string
# duração de validade de um token, em segundos (7200 s = 2 h); o cookie que
# carrega o token tem a mesma duração
rdvmedecins.auth.jwt-expires-in-seconds=7200
# true em produção (site servido por HTTPS): o cookie de autenticação
# nunca é então enviado por uma conexão não criptografada
rdvmedecins.auth.cookie-secure=false

# ——— proteção contra robôs (veja config/ProtectionProperties.java)
# login: falhas permitidas para o mesmo login a partir do mesmo endereço IP...
rdvmedecins.protection.login-max-failures=5
# ... antes de um bloqueio desta duração (o endereço IP inteiro também é bloqueado
# se acumular 5 vezes mais falhas, todos os logins juntos)
rdvmedecins.protection.login-block-minutes=15
# criação de conta de cliente: máximo de contas criadas por hora e por endereço
# IP. Em uma sala de aula, todos os computadores costumam sair pelo mesmo endereço:
# aumente se necessário.
rdvmedecins.protection.registration-max-per-hour=10

Vamos comentar este arquivo:

  • linha 11: a porta de escuta do servidor [Tomcat]. A porta padrão do [Spring Boot] é a 8080; os exemplos escutavam na porta 5000; a aplicação escuta na porta 8081, como a versão [ASP.NET Core];
  • Linha 14: o endereço do banco de dados, no formato URL JDBC (veja o exemplo 28): o protocolo [jdbc:mysql], seguido do servidor, da porta e do nome do banco de dados. O [Spring Boot] usa isso para determinar qual driver carregar;
  • Linhas 15–16: o nome de usuário e a senha do [MySQL]; por padrão, os do [Laragon] são [root], sem senha. A linha 16 é a que deve ser preenchida se a conta [root] tiver senha;
  • linha 18: o [Hibernate] pode criar ou modificar tabelas por conta própria com base nas entidades; aqui, ele não as modifica: a estrutura do banco de dados é a do script SQL, compartilhado com a versão [ASP.NET Core];
  • linha 20: por padrão, o [Spring Boot] mantém a conexão com o banco de dados aberta até o fim da requisição, inclusive enquanto a view está sendo gerada (o modo “open in view”), e sinaliza essa escolha com um aviso na inicialização. A aplicação desativa esse comportamento, como mostrado no exemplo 28: todos os dados necessários a uma view são lidos pela camada de negócio, dentro de sua transação, antes de a view ser renderizada. Assim, uma conexão nunca fica aberta por mais tempo que o necessário;
  • Linha 24: as requisições são processadas por threads virtuais, um recurso novo do [Java] 21. Um servidor web processa cada requisição em uma thread (uma thread de execução); uma thread do sistema é um recurso caro, e o [Tomcat] mantém apenas um número limitado delas (200 por padrão). No entanto, uma thread que espera a resposta do banco de dados não faz nada, mas continua ocupada. Uma thread virtual é uma thread leve, gerenciada pela máquina virtual: enquanto ela espera, a thread do sistema que a hospedava executa outra thread. O código da aplicação não precisa ser alterado para aproveitar isso;
  • linha 27: as respostas de erro nunca contêm a pilha de chamadas, que revelaria o funcionamento interno da aplicação a um atacante (veja o Capítulo 1);
  • linhas 32–38: as chaves de autenticação: a chave secreta que assina os tokens (pelo menos 32 caracteres; deve ser substituída em produção por uma longa string aleatória), a duração do token (duas horas) e a opção [Secure] do cookie que o transporta. Em produção, o site é servido em HTTPS, e o cookie nunca deve trafegar por uma conexão não criptografada: a opção é definida como [true];
  • Linhas 42–49: os limites da proteção contra bots (veja o exemplo 27): o número de tentativas de login malsucedidas permitidas e a duração do bloqueio resultante; o número de contas de cliente criadas por hora a partir do mesmo endereço IP.

As chaves [rdvmedecins.auth.*] e [rdvmedecins.protection.*] são lidas como records tipados (veja [config/AuthProperties.java], adiante). No arquivo, os nomes compostos são escritos em letras minúsculas separadas por hifens ([jwt-secret]): essa é a convenção usada pelo [Spring Boot], que os mapeia para os nomes em [Java] ([jwtSecret]).

[Spring Boot] lê a configuração de várias fontes sucessivas, cada uma das quais pode sobrescrever os valores das anteriores: [application.properties], depois [application-{profile}.properties] para cada perfil ativo (veja o arquivo seguinte), depois as variáveis de ambiente e, por fim, os argumentos da linha de comando ([--server.port=9000]). O nome de uma variável de ambiente é derivado da chave: letras maiúsculas, com [.] e [-] substituídos por [_]. [spring.datasource.password] se torna, assim, [SPRING_DATASOURCE_PASSWORD], e [rdvmedecins.auth.jwt-secret] se torna [RDVMEDECINS_AUTH_JWT_SECRET]: é assim que se fornece um segredo à aplicação em produção sem escrevê-lo em um arquivo do projeto.

11.6.4. src/main/resources/application-dev.properties

1
2
3
4
5
6
# =========================================================================
# application-dev.properties - complementa application.properties quando o
# perfil [dev] está ativo (mvnw spring-boot:run o ativa, veja pom.xml):
# as instruções SQL enviadas pelo Hibernate são exibidas no console.
# =========================================================================
spring.jpa.show-sql=true
  • Linha 6: quando o perfil [dev] está ativo, o [Spring Boot] lê o arquivo [application-dev.properties] depois de [application.properties] e mescla os dois: as chaves presentes no segundo arquivo substituem as do primeiro; as demais são mantidas. Durante o desenvolvimento, a chave [spring.jpa.show-sql] é, portanto, adicionada: o [Hibernate] escreve no console cada comando SQL que envia ao banco de dados, precedido de [Hibernate:]. Isso equivale ao arquivo [appsettings.Development.json] da versão [ASP.NET Core], com o perfil fazendo o papel do ambiente [Development]. Vimos que é o [pom.xml] que ativa esse perfil para o [spring-boot:run].

11.6.5. config/AuthProperties.java

// =========================================================================
// config/AuthProperties.java
// -------------------------------------------------------------------------
// As propriedades [rdvmedecins.auth.*] de application.properties, como
// um record tipado. O Spring Boot associa os nomes:
//   rdvmedecins.auth.jwt-secret             -> jwtSecret
//   rdvmedecins.auth.jwt-expires-in-seconds -> jwtExpiresInSeconds
//   rdvmedecins.auth.cookie-secure          -> cookieSecure
// e converte os valores para o tipo dos componentes (int, boolean).
// Uma classe que precisa dele recebe este record por injeção de dependência:
// evitamos assim ler strings por toda parte.
// =========================================================================
package rdvmedecins.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("rdvmedecins.auth")
public record AuthProperties(
        // chave secreta usada para assinar / verificar os tokens JWT. O algoritmo
        // HMAC-SHA256 exige uma chave de pelo menos 256 bits, ou seja, 32 bytes.
        String jwtSecret,
        // duração de validade de um token, em segundos; o cookie que o carrega
        // tem a mesma duração
        int jwtExpiresInSeconds,
        // true em produção (HTTPS): o cookie de autenticação nunca é
        // enviado por uma conexão não criptografada
        boolean cookieSecure) {
}

Vamos comentar este código:

  • linha 18: as chaves [rdvmedecins.auth.*] de [application.properties], na forma de um record: uma classe cujos campos, declarados entre parênteses (os “componentes” do record), são definidos de uma vez por todas pelo construtor. O compilador gera esse construtor por conta própria, junto com um método getter para cada componente, com o mesmo nome: [jwtSecret()], [jwtExpiresInSeconds()], [cookieSecure()];
  • Linha 17: a anotação [@ConfigurationProperties] especifica o prefixo das chaves. Na inicialização, o [Spring Boot] cria o record chamando seu construtor com os valores das chaves [rdvmedecins.auth.jwt-secret], [rdvmedecins.auth.jwt-expires-in-seconds] e [rdvmedecins.auth.cookie-secure], convertidos para o tipo de cada componente (["7200"] se torna o inteiro 7200, [false] se torna o booleano [false]). Um valor que não pode ser convertido (texto onde se espera um número) faz a aplicação falhar na inicialização, com uma mensagem que indica a chave problemática. Uma chave ausente resulta no valor padrão do tipo: [null], 0 ou [false];
  • linhas 21–27: os três componentes. O record se torna um bean, que uma classe que precise dele recebe pelo construtor (injeção de dependência; veja o exemplo 06): é o que fazem [config/SecurityConfig.java] e [auth/AuthService.java] (veja “Autenticação”). Isso evita ter de ler strings por toda parte: os nomes são verificados pelo compilador, e os valores já estão convertidos.

Esta é a técnica usada no exemplo 25, que declarava seu record com a anotação [@EnableConfigurationProperties(JwtProperties.class)]. O estudo de caso tem dois deles e deixa o [Spring Boot] encontrá-los sozinho, graças à anotação [@ConfigurationPropertiesScan] na classe principal (veja “Inicialização da aplicação”).

11.6.6. config/ProtectionProperties.java

// =========================================================================
// config/ProtectionProperties.java
// -------------------------------------------------------------------------
// As propriedades [rdvmedecins.protection.*]: os limites da proteção
// contra robôs (veja auth/AttemptLimiterService.java).
// =========================================================================
package rdvmedecins.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("rdvmedecins.protection")
public record ProtectionProperties(
        // login: número de falhas (captcha ou senha errados) permitidas
        // para o mesmo login a partir do mesmo endereço IP, antes de este par ser bloqueado...
        int loginMaxFailures,
        // ... por esta duração (um endereço IP também é bloqueado se acumular
        // 5 vezes mais falhas, todos os logins juntos)
        int loginBlockMinutes,
        // criação de conta de cliente: número máximo de contas criadas por hora
        // a partir do mesmo endereço IP
        int registrationMaxPerHour) {
}
  • Linhas 11–21: as chaves [rdvmedecins.protection.*], seguindo o mesmo padrão. O record é injetado em [auth/AttemptLimiterService.java], que lê seus limites a partir dele (veja “Autenticação”).

11.7. Inicialização da aplicação

A versão [ASP.NET Core] concentrava toda a funcionalidade relacionada à inicialização em [Program.cs]: registro de cada serviço e, em seguida, construção do pipeline de middleware em uma ordem específica. Com [Spring Boot], esse trabalho é distribuído: a classe principal apenas inicia o [Spring Boot]; este, por sua vez, configura o essencial por conta própria, com base nas bibliotecas disponíveis e em [application.properties]; e cada aspecto que a aplicação deseja configurar de forma diferente tem sua própria classe de configuração, localizada na pasta [config].

11.7.1. RdvMedecinsApplication.java

// =========================================================================
// RdvMedecinsApplication.java
// -------------------------------------------------------------------------
// O ponto de entrada da aplicação: o método main inicia o Spring Boot.
//
// @SpringBootApplication reúne três anotações:
//   - @Configuration: a classe pode declarar beans (@Bean);
//   - @EnableAutoConfiguration: o próprio Spring Boot configura o que as
//     bibliotecas presentes exigem (Spring MVC, Thymeleaf, JPA, Spring
//     Security...), de acordo com application.properties;
//   - @ComponentScan: o Spring procura as classes anotadas (@Controller,
//     @Service, @Component, @Repository...) no pacote [rdvmedecins] e em
//     seus subpacotes, e as transforma em beans, que fornece a quem
//     precisar deles (injeção de dependência).
//
// @ConfigurationPropertiesScan: os records anotados com @ConfigurationProperties
// (pacote config) recebem os valores de application.properties.
//
// Nenhum equivalente aqui ao "pipeline de middleware" do Program.cs do ASP.NET
// Core: a ordem dos filtros é definida pelo Spring Boot e pelo Spring Security, e
// cada aspecto é configurado em sua própria classe (config/SecurityConfig,
// config/WebConfig...).
// =========================================================================
package rdvmedecins;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan
public class RdvMedecinsApplication {

    public static void main(String[] args) {
        SpringApplication.run(RdvMedecinsApplication.class, args);
    }
}

Vamos comentar este código:

  • linhas 34–36: o método [main], o ponto de entrada de qualquer programa [Java], como visto nos exemplos. [SpringApplication.run] cria o contêiner do [Spring] (o “contexto da aplicação”, que cria e gerencia todos os beans), inicia o servidor [Tomcat]e, em seguida, devolve o controle; o programa continua em execução enquanto o servidor estiver escutando. A classe passada como parâmetro serve de ponto de partida para a configuração;
  • linha 30: a anotação [@SpringBootApplication] — que já estava presente em todos os exemplos — combina as três anotações detalhadas no comentário do arquivo (linhas 6–14). [@ComponentScan] faz com que o [Spring] percorra o pacote [rdvmedecins] e todos os seus subpacotes: cada classe anotada — [@Controller], [@Service], [@Component] (ou [@Configuration], [@ControllerAdvice]...) — torna-se um bean nele. As interfaces de repositório do [Spring Data JPA] são encontradas da mesma forma, nos mesmos pacotes, por meio da autoconfiguração do [Spring Data JPA] (veja abaixo). Portanto, diferentemente do que ocorre em [Program.cs], não há lista de serviços a manter: basta adicionar uma classe anotada a um desses pacotes. É por isso que a classe principal fica no pacote raiz, acima de todos os outros;
  • linha 31: [@ConfigurationPropertiesScan] faz o mesmo para os records anotados com [@ConfigurationProperties] (veja [config/AuthProperties.java]).

Todos os beans da aplicação são singletons: uma única instância compartilhada por todas as requisições. A versão [ASP.NET Core] distinguia três tempos de vida ([Singleton], [Scoped], [Transient]) porque sua camada DAO dependia de uma instância de [DbContext] criada para cada requisição. Com o [Spring], os repositórios e a camada de negócio não dependem de nenhuma requisição: é o [Spring] que fornece a cada tarefa de processamento uma conexão retirada do pool de conexões (um conjunto de conexões abertas, reutilizadas de uma consulta para a seguinte) e, nas gravações feitas pela camada de negócio, sua transação. Esse ponto é discutido com mais detalhes nas seções sobre a camada DAO e a camada de negócio.

11.7.2. O que o Spring Boot configura automaticamente

[@EnableAutoConfiguration], contida em [@SpringBootApplication], aciona a autoconfiguração: na inicialização, o [Spring Boot] examina as bibliotecas presentes no classpath e os beans já declarados pela aplicação, e cria por conta própria os beans que faltam, configurados de acordo com [application.properties]. O console de inicialização, mostrado acima, permite acompanhar esse processo:

O que é configurado
Presente graças a
Logs do console
o servidor [Tomcat], na porta [server.port]
[spring-boot-starter-webmvc]
[Tomcat initialized with port 8081], depois [Tomcat started on port 8081]
o servlet [DispatcherServlet], o controller frontal do [Spring MVC], que recebe todas as requisições e as distribui entre as ações
[spring-boot-starter-webmvc]
[Initializing Servlet 'dispatcherServlet'], na primeira requisição
os arquivos estáticos da pasta [static/], servidos como estão ([/css/styles.css]...)
[spring-boot-starter-webmvc]
nenhum
a engine [Thymeleaf]: a view [schedule] é o arquivo [templates/schedule.html]
[spring-boot-starter-thymeleaf]
nenhum
o validador de formulários ([Hibernate Validator])
[spring-boot-starter-validation]
nenhum
A fonte de dados ([DataSource]): um pool de conexões [HikariCP] para a URL [spring.datasource.url]
[spring-boot-starter-data-jpa], [mysql-connector-j]
[HikariPool-1 - Start completed]
[Hibernate] (a “fábrica” de [EntityManager] e [JPA]), o gerenciador de transações e o bean [TransactionTemplate] usado pela camada de negócio
[spring-boot-starter-data-jpa]
[Hibernate ORM core version 7.4.5.Final], [Database info], [Initialized JPA EntityManagerFactory]
uma implementação de cada uma das cinco interfaces de repositório da pasta [repositories/] (a sexta, [PersonRepository], um modelo comum a médicos e clientes, é marcada como [@NoRepositoryBean]: o [Spring Data JPA] não a implementa)
[spring-boot-starter-data-jpa]
[Found 5 JPA repository interfaces]
reinício automático e desativação do cache de views do [Thymeleaf]
[spring-boot-devtools]
[Devtools property defaults active!], [restartedMain]

Vamos comentar algumas linhas deste console:

  • [The following 1 profile is active: "dev"]: o perfil ativado por [pom.xml]; portanto, [application-dev.properties] é lido;
  • [restartedMain] é o nome da thread que inicia a aplicação: a do [Spring Boot DevTools], que a reiniciará após cada recompilação. Quando iniciada por [java -jar], sem o DevTools, a aplicação inicia na thread [main];
  • o aviso [HHH000511] aparece apenas com o [MariaDB] (veja “Problemas comuns”);
  • as duas linhas [Hibernate: select ...] são consultas de carga do cache (veja abaixo), exibidas por causa do perfil [dev]. Vemos aqui o join que o [Hibernate] derivou das entidades para recuperar cada médico junto com sua conta [users];
  • [Tomcat started on port 8081] vem depois dessas consultas: o servidor só aceita requisições depois que todos os beans foram criados, inclusive o cache;
  • As três últimas linhas só aparecem com a primeira requisição: o [Spring Boot] inicializa o [DispatcherServlet] somente quando ele é necessário. A thread delas, [tomcat-handler-0] (da qual o console exibe apenas o final do nome), é uma thread virtual (veja [application.properties]).

A autoconfiguração fica em segundo plano em relação à aplicação: ela só cria um bean se a aplicação não tiver declarado um com o mesmo papel. É assim que a aplicação substitui configurações padrão que não atendem às suas necessidades:

  • segurança: sem configuração, o [Spring Boot] protegeria todas as páginas com um formulário de login e uma senha gerada na inicialização; [config/SecurityConfig.java] declara sua própria cadeia de filtros e seu próprio decodificador de tokens JWT (veja “Autenticação”);
  • traduções: o bean [messageSource], que o [Thymeleaf] usa para suas expressões [#{...}], é a classe [web/Translator.java], que lê os dicionários JSON (veja o Exemplo 22 e “A camada web: serviços compartilhados”);
  • a página de erro: os erros (400, 403, 404, 500...) são tratados pelo servidor no endereço [/error]. [Spring Boot] normalmente coloca ali seu próprio controller; [controllers/ErrorController.java] toma o seu lugar (veja o Exemplo 24 e “A camada web: controllers”);
  • o idioma de cada requisição e os atributos Flash: são os dois beans de [config/WebConfig.java], discutidos a seguir.

Também não há, como em [Program.cs], um pipeline de middleware a configurar: cada requisição passa pela cadeia de filtros do [Spring Security] — cuja ordem é determinada pelo próprio [Spring Security] — antes de chegar ao [DispatcherServlet], que seleciona a ação com base nas anotações dos controllers (veja o Exemplo 24).

11.7.3. config/WebConfig.java

// =========================================================================
// config/WebConfig.java
// -------------------------------------------------------------------------
// Os acréscimos à configuração do Spring MVC:
//   - o idioma de cada requisição, lido de um cookie (veja o exemplo 22);
//   - os atributos flash, armazenados em um cookie (veja web/CookieFlashMapManager).
// Os arquivos estáticos da pasta src/main/resources/static (css/, js/,
// lib/bootstrap/) são servidos pelo Spring Boot sem configuração.
// =========================================================================
package rdvmedecins.config;

import java.time.Duration;
import java.util.Locale;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.FlashMapManager;
import org.springframework.web.servlet.LocaleResolver;
import org.springframework.web.servlet.i18n.CookieLocaleResolver;

import rdvmedecins.web.CookieFlashMapManager;

@Configuration
public class WebConfig {

    // o idioma de cada requisição: o do cookie [rdvmedecins_language],
    // definido por LanguageController; inglês caso contrário. O bean deve se chamar
    // [localeResolver]: é com este nome que o Spring MVC o procura.
    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("rdvmedecins_language");
        resolver.setDefaultLocale(Locale.ENGLISH);
        resolver.setCookieMaxAge(Duration.ofDays(365));
        resolver.setCookieHttpOnly(true);
        resolver.setCookieSameSite("Lax");
        return resolver;
    }

    // os atributos flash em um cookie, e não na sessão HTTP. O bean
    // deve se chamar [flashMapManager]: ele substitui então o do Spring MVC.
    @Bean
    public FlashMapManager flashMapManager() {
        return new CookieFlashMapManager();
    }
}

Vamos comentar este código:

  • linha 23: uma classe anotada com [@Configuration] declara beans por meio de métodos anotados com [@Bean] (veja o Exemplo 06). Na inicialização, o [Spring] chama cada um desses métodos uma vez e armazena o objeto resultante como um bean. O bean recebe o nome do método;
  • Linha 30: [LocaleResolver] determina o idioma ([Locale]) de cada requisição. [Spring MVC] o procura com o nome [localeResolver]: é o nome do método que o torna o substituto do [Spring Boot], que seguiria o idioma preferido do navegador;
  • Linha 31: o idioma é lido do cookie [rdvmedecins_language], como no Exemplo 22. Esse cookie é definido pelo mesmo objeto quando [controllers/LanguageController.java] lhe envia o idioma selecionado (botões FR / EN);
  • linha 32: sem cookie, o idioma é o inglês;
  • linhas 33–35: o cookie dura um ano; é [HttpOnly] (o script da página não consegue lê-lo) e [SameSite=Lax] (o navegador não o envia com requisições feitas por outro site, exceto na simples navegação até a aplicação);
  • Linhas 41–44: [FlashMapManager] preserva os atributos Flash entre um POST e o redirecionamento seguinte (o padrão Post/Redirect/Get; veja o Exemplo 20). O bean do [Spring MVC] os armazena na sessão HTTP; no entanto, a aplicação é stateless: ela não retém nenhum dado do usuário entre requisições, pois o usuário é identificado pelo token JWT em seu cookie. O bean chamado [flashMapManager] substitui, portanto, o chamado [Spring MVC] pela classe [web/CookieFlashMapManager.java], que armazena os atributos flash em um cookie (veja “A camada web: serviços comuns”).

11.7.4. Carga do cache na inicialização

As listas de médicos e clientes são exibidas em quase todas as páginas (listas suspensas na agenda, páginas de administração). Em vez de recuperá-las do banco de dados a cada requisição, a aplicação as mantém em memória no bean [web/ApplicationModel.java], pelo qual passam todos os controllers. Esse bean as recarrega após cada inclusão, alteração ou exclusão de um médico ou cliente.

A carga inicial ocorre na inicialização, em um método desse bean anotado com [@PostConstruct]. Essa anotação instrui o [Spring] a chamar o método assim que o objeto for criado e suas dependências forem injetadas (neste caso, a camada de negócio): portanto, durante a inicialização, antes de o servidor aceitar a primeira requisição. São as duas consultas [Hibernate: select ...] no console. Um erro de leitura não é capturado: a aplicação para imediatamente, com o erro aparecendo no console. Um banco de dados inacessível (erro de URL, servidor [MySQL] parado) na verdade interrompe a aplicação ainda mais cedo, assim que o [Hibernate] é inicializado (veja “Problemas comuns”).

Para essa carga, a versão [ASP.NET Core] precisava criar explicitamente um “escopo” em [Program.cs], porque sua fachada dependia do [DbContext] de uma requisição. Não é o caso aqui: [ApplicationModel] é um singleton, assim como a camada de negócio que ele usa. O arquivo é documentado na seção “A camada web: serviços comuns”.

11.7.5. Do Program.cs do ASP.NET Core ao Spring Boot

Para quem conhece a versão [ASP.NET Core], eis onde se encontra cada parte de [Program.cs]:

Program.cs (ASP.NET Core)
Spring Boot
[WebApplication.CreateBuilder(args)] ... [app.Run()]
[SpringApplication.run(...)] ([RdvMedecinsApplication.java])
[builder.Services.AddScoped<...>()], uma chamada por serviço
[@ComponentScan]: classes anotadas com [@Service], [@Component], [@Controller]... ; as interfaces de registro (autoconfiguração do [Spring Data JPA]); os métodos [@Bean] das classes [@Configuration]
[Configure<AuthOptions>(...)] e [IOptions<AuthOptions>]
records [@ConfigurationProperties] e [@ConfigurationPropertiesScan]
[AddDbContext] e [UseMySql]
Configuração automática da fonte de dados e do [Hibernate], com base em [spring.datasource.*]
[AddControllersWithViews]
Autoconfiguração do [DispatcherServlet] e do [Thymeleaf]
[AddJwtAuthentication], [UseAuthentication], [UseAuthorization]
[config/SecurityConfig.java] (cadeia de filtros do [Spring Security])
[UseStaticFiles] (pasta [wwwroot])
Automático (pasta [static])
[UseRequestLocalization] e [CookieRequestCultureProvider]
bean [localeResolver] ([CookieLocaleResolver], [config/WebConfig.java])
[TempData] (cookie)
bean [flashMapManager] ([CookieFlashMapManager], [config/WebConfig.java])
[UseExceptionHandler], [UseStatusCodePagesWithReExecute]
o endereço [/error], processado por [controllers/ErrorController.java]
[CreateScope()], depois [LoadAsync()], antes de [app.Run()]
método [@PostConstruct] de [web/ApplicationModel.java]
[appsettings.Development.json] e [ASPNETCORE_ENVIRONMENT]
[application-dev.properties] e o perfil [dev]
[dotnet watch]
[Spring Boot DevTools]

11.8. As entidades

As entidades [JPA] mapeiam as tabelas do banco de dados para classes [Java] (veja o Exemplo 28). Cada classe de entidade é anotada com [@Entity]; seus campos são associados a colunas por meio de anotações ([@Column], [@Id], [@JoinColumn]...) do pacote [jakarta.persistence]. Essas anotações são as definidas pelo padrão [JPA] (Jakarta Persistence); o [Hibernate], a implementação do padrão usada pelo [Spring Boot], as lê quando a aplicação inicia para determinar qual classe vai para qual tabela e qual campo vai para qual coluna. O banco de dados não é criado pelo [Hibernate], mas pelo script SQL [database/dbrdvmedecins2.sql] (veja a seção “O banco de dados”): as entidades devem simplesmente descrever com exatidão as tabelas que já existem.

As entidades da aplicação ficam na pasta [entities]:

Arquivo
Tabela
Papel
[AbstractEntity.java]
-
Os campos comuns [id] e [version] (bloqueio otimista)
[Person.java]
-
Campos comuns a médicos e clientes: [title], [lastName], [firstName], e a conta de usuário
[Doctor.java]
[doctors]
um médico
[Client.java]
[clients]
um paciente
[Slot.java]
[slots]
um horário de consulta de um médico
[Appointment.java]
[appointments]
uma consulta
[User.java]
[users]
uma conta de usuário
[Role.java]
-
uma lista dos três papéis

11.8.1. entities/AbstractEntity.java

// =========================================================================
// entities/AbstractEntity.java
// -------------------------------------------------------------------------
// Os dois campos comuns a todas as entidades: o identificador [id] e o
// número de versão [version] (bloqueio otimista).
//
// @MappedSuperclass: esta classe não tem tabela; seus campos são adicionados
// às tabelas das classes filhas (Doctor, Client, Slot, Appointment, User).
//
// As anotações @Id, @Column, @Version... vêm do padrão JPA (Jakarta
// Persistence, pacote jakarta.persistence): o Hibernate as lê na inicialização
// para saber qual classe vai em qual tabela, qual campo em qual coluna.
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.Version;

@MappedSuperclass
public abstract class AbstractEntity {

    // a chave primária, gerada pelo banco de dados (coluna AUTO_INCREMENT): o Hibernate
    // lê seu valor de volta após cada INSERT. Integer (e não int): uma entidade
    // ainda não salva tem id nulo.
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Integer id;

    // @Version: o bloqueio otimista. Cada UPDATE enviado pelo Hibernate carrega
    // a condição "WHERE id = ... AND version = <valor lido>" e grava a
    // versão incrementada em 1. Se alguém modificou a linha nesse meio-tempo,
    // nenhuma linha é atualizada: o Hibernate lança uma exceção
    // (OptimisticLockException, que o Spring traduz em
    // ObjectOptimisticLockingFailureException, veja business/BusinessService.java).
    @Version
    @Column(name = "version")
    private Integer version;

    public Integer getId() {
        return id;
    }

    public Integer getVersion() {
        return version;
    }
}
  • Linha 23: [@MappedSuperclass] designa uma classe-mãe sem tabela: ela não corresponde a nenhuma tabela, mas seus campos e suas anotações são adicionados aos de suas classes-filhas. Todas as entidades da aplicação herdam dela e, portanto, têm um identificador e uma versão. A classe também é [abstract]: um objeto [AbstractEntity] nunca é criado;
  • linhas 29–32: a chave primária ([@Id]), coluna [id]. [@GeneratedValue(strategy = GenerationType.IDENTITY)] indica que o valor é gerado pelo banco de dados (coluna [AUTO_INCREMENT]): o [Hibernate] envia [INSERT] sem identificador e depois lê de volta o atribuído pelo banco. Ponto-chave para lembrar mais adiante: o [INSERT] de uma nova entidade é enviado imediatamente ao chamar [save], porque o [Hibernate] precisa do identificador de imediato. O tipo é [Integer], e não [int]: um [Integer] pode ser igual a [null], o que ocorre com uma entidade que ainda não foi registrada;
  • Linhas 40–42: a versão da linha, para o bloqueio otimista (veja o Exemplo 28). Com [@Version], [Hibernate] faz todo o trabalho: cada [UPDATE] que ele envia traz a condição [WHERE id = ... AND version = <value read>] e grava a versão incrementada em 1. Se a linha foi modificada nesse meio-tempo por outra pessoa, nenhuma linha é atualizada, e o [Hibernate] lança uma exceção, que o [Spring] traduz em [ObjectOptimisticLockingFailureException] (veja “A camada de negócio”). Isso difere do [Entity Framework Core], em que a aplicação precisava incrementar a versão por conta própria antes de cada gravação;
  • Linhas 44–50: acessores somente leitura. Não há métodos chamados [setId] ou [setVersion]: esses valores são gravados somente pelo [Hibernate]. Como a anotação [@Id] está colocada em um campo (e não em um método [getId]), o [Hibernate] lê e grava os campos diretamente — mesmo os privados — sem passar pelos acessores. Isso é chamado de acesso por campo.

11.8.2. entities/Person.java

// =========================================================================
// entities/Person.java
// -------------------------------------------------------------------------
// Classe pai (sem tabela) das entidades [Doctor] e [Client]: um título, um
// sobrenome, um nome - e a conta de usuário associada (coluna [user]).
//
// Uma relação declarada em uma @MappedSuperclass é herdada pelas
// classes filhas exatamente como as colunas: a relação [user] existe, portanto,
// na tabela [doctors] E na tabela [clients].
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.MappedSuperclass;
import jakarta.persistence.OneToOne;

@MappedSuperclass
public abstract class Person extends AbstractEntity {

    @Column(name = "title", length = 5)
    private String title; // Melle, Mme, Mr

    @Column(name = "last_name", length = 20)
    private String lastName;

    @Column(name = "first_name", length = 20)
    private String firstName;

    // -----------------------------------------------------------------------
    // A relação com a conta de usuário: um médico (um cliente) tem UMA
    // conta, e uma conta pertence a UMA pessoa (coluna [user] UNIQUE).
    //   - @OneToOne: relação "um para um";
    //   - fetch = LAZY: o User só é lido do banco de dados se solicitado (na
    //     consulta, veja @EntityGraph em repositories/, ou acessando o campo
    //     durante uma transação);
    //   - @JoinColumn: a coluna da chave estrangeira. Os acentos graves
    //     (`user`) pedem ao Hibernate que "proteja" este nome, que é uma
    //     palavra reservada do MySQL.
    // -----------------------------------------------------------------------
    @OneToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "`user`")
    private User user;

    // a mesma coluna, lida como um simples número: assim conhecemos o id da
    // conta sem carregar o User. insertable / updatable = false: é o campo
    // [user] acima que escreve a coluna, este apenas lê.
    @Column(name = "`user`", insertable = false, updatable = false)
    private Integer userId;

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

    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }

    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }

    public User getUser() { return user; }
    public void setUser(User user) { this.user = user; }

    public Integer getUserId() { return userId; }
}
  • Linhas 19–20: a classe-mãe — que também não tem tabela associada ([@MappedSuperclass]) — de [Doctor] e [Client], ela própria filha de [AbstractEntity]. Médicos e clientes têm as mesmas colunas: elas são declaradas uma única vez;
  • linhas 22–29: o título (Sra., Sr. etc.), o sobrenome e o nome. O atributo [length] de [@Column] especifica a largura da coluna; na prática, só é usado se o [Hibernate] criar as tabelas por conta própria, o que não é o caso aqui (veja a seção “JPA, Hibernate e Spring Data”): não é uma regra de validação, mas apenas uma documentação fiel do script SQL;
  • Linhas 42–44: a relação com a conta de usuário, na forma de um campo do tipo [User] (o próprio objeto, não seu identificador). [@OneToOne] define uma relação “um para um”: um médico (um cliente) tem uma conta, e uma conta pertence a no máximo uma pessoa (a coluna [user] é [UNIQUE] no script SQL). [@JoinColumn] nomeia a coluna que contém a chave estrangeira. [fetch = FetchType.LAZY] especifica o carregamento tardio: quando o [Hibernate] lê uma pessoa, ele não lê sua conta; em vez disso, o campo [user] recebe um proxy, um objeto que se faz passar pelo [User] e só lerá a linha da tabela [users] na primeira chamada a um de seus métodos, e apenas se a transação ainda estiver aberta. Para recuperar a pessoa junto com sua conta, a consulta deve solicitá-lo explicitamente (veja “A camada DAO”);
  • Linha 43: [user] é uma palavra reservada no [MySQL]: se escrita como está em uma consulta SQL, causaria um erro de sintaxe. Os acentos graves que cercam o nome em [@JoinColumn] instruem o [Hibernate] a proteger esse nome: ele o envolverá em acentos graves em cada comando SQL, como faz o script SQL;
  • Linhas 49–50: a mesma coluna [user], desta vez lida como um simples número. Isso nos permite determinar o ID da conta sem carregar a própria conta: a camada de negócio o usa para excluir a conta de uma pessoa. Uma coluna só pode ser gravada por um campo: [insertable = false, updatable = false] indica que este campo apenas a lê, e que é o campo [user] que a grava (em [INSERT] e [UPDATE]);
  • linhas 52–64: os acessores. Uma classe cujos campos privados são lidos por métodos chamados [getXxx] e gravados por métodos chamados [setXxx] segue a convenção JavaBean; as views do [Thymeleaf] se baseiam nessa convenção ([${doctor.lastName}] chama [getLastName()]). Não há [setUserId]: o campo [userId] é somente leitura.

Eis a consulta SQL, capturada no console da aplicação, que o [Hibernate] envia para recuperar um médico e sua conta (veja [findWithUserById] na camada DAO). Vemos aqui a coluna [user] com seus acentos graves e o join com a tabela [users]:

Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,d1_0.`user`,d1_0.version from doctors d1_0 left join users u1_0 on u1_0.id=d1_0.`user` where d1_0.id=?

A coluna [user] da tabela [doctors] (também conhecida como [d1_0]) é lida uma única vez, embora dois campos correspondam a ela: o [Hibernate] a usa para preencher o campo [userId] e vincula o campo [user] ao registro recuperado pelo join. [?] é um parâmetro da consulta (o ID do médico) enviado separadamente ao banco de dados.

11.8.3. entities/Doctor.java

// =========================================================================
// entities/Doctor.java
// -------------------------------------------------------------------------
// Um médico do consultório (tabela [doctors]).
//
// Restrição SQL de unicidade: unq_doctors_first_name_last_name (dois médicos não podem
// ter o mesmo nome e sobrenome) - criada pelo script SQL,
// reconhecida pelo nome na camada de negócio.
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

// @Entity: uma classe cujos objetos são as linhas de uma tabela;
// @Table: o nome desta tabela
@Entity
@Table(name = "doctors")
public class Doctor extends Person {
}
  • linha 17: [@Entity] define a classe como uma entidade: seus objetos são linhas de uma tabela;
  • linha 18: [@Table] dá a esta tabela o nome [doctors]. Sem ela, o [Hibernate] procuraria uma tabela com o mesmo nome da classe;
  • Linha 19: a classe herda todos os seus campos de [Person], e o identificador e a versão de [AbstractEntity]. Ela não tem construtor explícito: o compilador [Java] fornece-lhe, portanto, um construtor padrão — público e sem parâmetros —, que é exatamente o que o [JPA] exige (veja [Appointment.java]) e o que a camada de negócio usará ([Doctor::new]). A restrição de unicidade [unq_doctors_first_name_last_name], mencionada no comentário, é criada pelo script SQL; a camada de negócio a reconhece pelo nome.

Diferentemente da versão [ASP.NET Core], [Doctor] não declara a relação inversa com seus horários (uma lista [@OneToMany]): a aplicação não a usaria; ela lê os horários de um médico por meio da camada DAO.

11.8.4. entities/Client.java

// =========================================================================
// entities/Client.java
// -------------------------------------------------------------------------
// Atenção: [Client] aqui designa um PACIENTE do consultório médico, não um
// cliente HTTP! É o vocabulário do domínio de negócio original, mantido
// como está (tabela [clients]).
//
// Restrição SQL de unicidade: unq_clients_first_name_last_name (veja Doctor.java).
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

@Entity
@Table(name = "clients")
public class Client extends Person {
}

Um cliente, isto é, um paciente do consultório (não um cliente HTTP): uma [Person] da tabela [clients] (linhas 15–17), sem campos adicionais.

11.8.5. entities/Slot.java

// =========================================================================
// entities/Slot.java
// -------------------------------------------------------------------------
// Um horário de um médico (tabela [slots]): 8:00 - 8:20, etc.
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;

@Entity
@Table(name = "slots")
public class Slot extends AbstractEntity {

    @Column(name = "start_hour")
    private int startHour; // hora de início do horário

    @Column(name = "start_minute")
    private int startMinute; // minuto de início do horário

    @Column(name = "end_hour")
    private int endHour; // hora de término do horário

    @Column(name = "end_minute")
    private int endMinute; // minuto de término do horário

    // vários horários para o mesmo médico: @ManyToOne ("muitos para um"),
    // chave estrangeira [doctor_id]. Mesma técnica de Person.user / userId.
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "doctor_id")
    private Doctor doctor;

    @Column(name = "doctor_id", insertable = false, updatable = false)
    private Integer doctorId;

    public int getStartHour() { return startHour; }
    public int getStartMinute() { return startMinute; }
    public int getEndHour() { return endHour; }
    public int getEndMinute() { return endMinute; }
    public Doctor getDoctor() { return doctor; }
    public Integer getDoctorId() { return doctorId; }
}
  • linhas 19–29: as horas e os minutos de início e de fim do horário, do tipo [int]: essas colunas são declaradas como [NOT NULL] no banco de dados; um tipo primitivo — que não pode ser [null] — é adequado para elas;
  • Linhas 33–35: a relação “muitos para um” com o médico ([@ManyToOne]): vários horários para um médico, chave estrangeira na coluna [doctor_id]; o médico é carregado de forma tardia ([LAZY]). Mesma técnica usada para a conta de uma pessoa;
  • linhas 37–38: a mesma coluna [doctor_id], somente leitura, na forma de um número. As consultas por “horários do médico nº 2” terão como alvo este campo, sem precisar carregar o médico;
  • linhas 40–45: acessores somente leitura: a aplicação nunca cria nem modifica horários (eles são criados pelo script SQL).

Por padrão, uma relação [@ManyToOne] é carregada imediatamente ([EAGER]): ler um horário também leria seu médico e, depois, a conta desse médico... Em vez disso, todas as relações da aplicação são declaradas como [LAZY], e cada consulta solicita explicitamente as relações de que precisa: assim, sabemos exatamente qual SQL é enviado.

11.8.6. entities/Appointment.java

// =========================================================================
// entities/Appointment.java
// -------------------------------------------------------------------------
// Uma consulta (tabela [appointments]): um cliente, em um horário, em um determinado dia.
//
// Restrição SQL de unicidade: unq1_appointments (day, slot_id) - um horário é
// reservado apenas uma vez por dia. Criada pelo script SQL, reconhecida pelo seu
// nome na camada de negócio.
// =========================================================================
package rdvmedecins.entities;

import java.time.LocalDate;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
import jakarta.persistence.Table;

@Entity
@Table(name = "appointments")
public class Appointment extends AbstractEntity {

    // LocalDate: uma data SEM hora, que corresponde exatamente ao tipo SQL
    // DATE da coluna [day]
    @Column(name = "day")
    private LocalDate day;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "client_id")
    private Client client;

    @Column(name = "client_id", insertable = false, updatable = false)
    private Integer clientId;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "slot_id")
    private Slot slot;

    @Column(name = "slot_id", insertable = false, updatable = false)
    private Integer slotId;

    // um construtor sem parâmetros é exigido pelo JPA (o Hibernate cria os
    // objetos lidos do banco de dados com ele)
    protected Appointment() {
    }

    // uma nova consulta
    public Appointment(LocalDate day, Slot slot, Client client) {
        this.day = day;
        this.slot = slot;
        this.client = client;
    }

    public LocalDate getDay() { return day; }
    public Client getClient() { return client; }
    public Integer getClientId() { return clientId; }
    public Slot getSlot() { return slot; }
    public Integer getSlotId() { return slotId; }
}
  • linha 22: a tabela de consultas. Sua restrição de unicidade [unq1_appointments (day, slot_id)] garante que um horário seja reservado apenas uma vez por dia;
  • linhas 27–28: o dia da consulta. O tipo [LocalDate] (pacote [java.time]) representa uma data sem hora: ele corresponde exatamente ao tipo SQL [DATE] da coluna [day], independentemente do fuso horário. O [Hibernate] faz a conversão nos dois sentidos;
  • linhas 30–42: o cliente e o horário da consulta: duas relações “muitos para um”, cada uma definida com um campo de objeto (que preenche a coluna) e um campo numérico somente leitura ([clientId], [slotId]);
  • Linhas 46–47: o [JPA] exige que toda entidade tenha um construtor sem parâmetros: [Hibernate] usa esse construtor para criar os objetos que lê do banco de dados antes de preencher seus campos. Assim que uma classe declara um construtor (linhas 50–54), o compilador deixa de fornecer um construtor padrão para ela: ele deve, portanto, ser escrito. Ele é declarado como [protected]: [Hibernate] pode usá-lo, mas o restante da aplicação, que não o enxerga, é forçado a usar o construtor completo. O [JPA] aceita um construtor [public] ou [protected], mas não [private]: o [Hibernate] cria seus delegados (proxies) definindo classes-filhas das entidades, e uma classe-filha precisa poder chamar o construtor de sua classe-mãe (é também por isso que uma classe de entidade não deve ser declarada como [final]);
  • linhas 50–54: o construtor de uma nova consulta: uma data, um horário e um cliente. Ele preenche os campos de objeto [slot] e [client], que definem as chaves estrangeiras; os campos somente leitura [clientId] e [slotId] só serão preenchidos quando uma consulta for lida do banco de dados;
  • Linhas 56–60: acessores somente leitura: uma consulta nunca é modificada, apenas criada ou excluída.

11.8.7. entities/Role.java

// =========================================================================
// entities/Role.java
// -------------------------------------------------------------------------
// Os três papéis de um usuário (coluna users.role):
//   - ADMIN  : o administrador - consultas + gerenciamento de médicos e clientes;
//   - DOCTOR : um médico - marca e cancela consultas;
//   - USER   : um cliente (paciente) - marca para si mesmo, gerencia sua conta.
//
// Uma enumeração (enum): o compilador recusa qualquer outro valor. O JPA
// a armazena no banco de dados como TEXTO ('ADMIN'...), como faz o script SQL
// (veja @Enumerated em User.java).
// =========================================================================
package rdvmedecins.entities;

public enum Role {
    ADMIN,
    DOCTOR,
    USER
}
  • linhas 15–19: os três papéis, na forma de uma enumeração ([enum]): uma variável do tipo [Role] só pode ter o valor [Role.ADMIN], [Role.DOCTOR], [Role.USER] (ou [null]), e o compilador rejeita qualquer outro valor. [Role] não é uma entidade: é o tipo de um campo de [User]. Cada valor tem um nome ([name()] retorna ["ADMIN"]) e um número de ordem ([ordinal()] retorna 0 para [ADMIN]): é a escolha entre os dois, para o banco de dados, que [@Enumerated] faz em [User.java].

11.8.8. entities/User.java

// =========================================================================
// entities/User.java
// -------------------------------------------------------------------------
// Um usuário autorizado a entrar na aplicação (tabela [users]).
// Cada médico e cada cliente tem SUA conta de usuário (coluna [user]
// das tabelas [doctors] e [clients], veja Person.java).
//
// Restrição SQL de unicidade: unq_users_login (um login pertence a uma única
// conta). Ela é criada pelo script database/dbrdvmedecins2.sql;
// a camada de negócio a reconhece pelo seu NOME (veja business/BusinessService.java).
// =========================================================================
package rdvmedecins.entities;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.EnumType;
import jakarta.persistence.Enumerated;
import jakarta.persistence.Table;

@Entity
@Table(name = "users")
public class User extends AbstractEntity {

    @Column(name = "login", length = 30)
    private String login;

    // a senha com HASH (bcrypt) - nunca em texto claro
    @Column(name = "password", length = 100)
    private String password;

    // o nome exibido após o login - para um médico ou um cliente:
    // "firstName LASTNAME" (p. ex., "Marie PELISSIER")
    @Column(name = "name", length = 40)
    private String name;

    // ADMIN, DOCTOR ou USER, armazenado no banco de dados como texto (STRING) e não
    // como número ordinal (ORDINAL: 0, 1, 2)
    @Enumerated(EnumType.STRING)
    @Column(name = "role", length = 10)
    private Role role;

    public String getLogin() { return login; }
    public void setLogin(String login) { this.login = login; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public Role getRole() { return role; }
    public void setRole(Role role) { this.role = role; }
}
  • Linhas 20–22: as contas dos usuários autorizados a fazer login: o administrador, cada médico e cada cliente. A restrição [unq_users_login] proíbe duas contas com o mesmo login;
  • linhas 24–25: o nome de usuário;
  • linhas 28–29: o hash [bcrypt] da senha, nunca a senha em si (veja o exemplo 25);
  • linhas 33–34: o nome exibido na barra de navegação após o login (“Marie PELISSIER”);
  • linhas 38–40: o papel. Por padrão, o [JPA] gravaria uma enumeração no banco de dados pelo seu número de ordem ([EnumType.ORDINAL]: 0, 1, 2), o que teria dois inconvenientes: a coluna [role] do script SQL contém texto, e adicionar um valor no meio da enumeração, em algum momento, alteraria a ordem dos números já gravados. [@Enumerated(EnumType.STRING)] armazena o nome do valor (['ADMIN']...) e o converte de volta em [Role] na leitura;
  • Linhas 42–52: os getters. A classe [User] não declara uma relação com o médico ou o cliente a quem pertence: a relação é conhecida apenas do lado de [Person], que carrega a chave estrangeira.

11.9. JPA, Hibernate e Spring Data

A versão [ASP.NET Core] da aplicação continha uma classe chamada [DbContext], que era o componente central do [Entity Framework Core]: ela mantinha a conexão, dava acesso às tabelas, rastreava as entidades carregadas e enviava as alterações ao banco de dados. A versão [Spring] não tem equivalente codificado à mão: esses papéis são distribuídos entre objetos que o [Spring Boot] cria por conta própria na inicialização, com base na configuração. Esta seção explica quem faz o quê; ela não corresponde a nenhum arquivo [Java] do projeto.

11.9.1. Três camadas

O acesso a dados se baseia em três camadas, que o starter [spring-boot-starter-data-jpa] fornece em conjunto (veja a seção “Configuração do projeto”):

  • [JPA] (Jakarta Persistence) é um padrão: um conjunto de interfaces e anotações ([@Entity], [EntityManager]...), sem nenhum código que as faça funcionar;
  • [Hibernate] é uma implementação desse padrão: ele lê as anotações das entidades, escreve os comandos SQL, os envia ao banco de dados via JDBC ([mysql-connector-j]) e converte as linhas resultantes em objetos [Java];
  • [Spring Data JPA] adiciona os repositórios sobre isso: basta descrever um DAO por meio de uma interface, e o [Spring] escreverá a implementação (veja “A camada DAO”).

11.9.2. O EntityManager e o contexto de persistência

O objeto central do [JPA] é o [EntityManager] (o “gerenciador de entidades”): ele é responsável por ler ([find]), gravar ([persist]) e excluir ([remove]) entidades, além de executar consultas. Ele gerencia um contexto de persistência: o conjunto de entidades que leu ou gravou, chamadas entidades “gerenciadas”. Para cada entidade gerenciada, ele mantém uma cópia do estado lido do banco de dados. No momento da sincronização com o banco de dados (o *flush*), que ocorre o mais tardar imediatamente antes do [COMMIT] da transação, ele compara cada entidade com sua cópia e envia por conta própria um [UPDATE] para cada uma que tenha mudado (*dirty checking*). Portanto, não há nenhum método “salvar alterações” a chamar: basta modificar uma entidade gerenciada. Um contexto de persistência também garante que uma única linha seja representada por um único objeto: ler o médico nº 1 duas vezes dentro da mesma transação retorna duas vezes o mesmo objeto [Java].

Esse é exatamente o “rastreamento de alterações” do [DbContext] do [Entity Framework Core], com uma diferença importante: com o [Spring], o contexto de persistência está vinculado à transação. Ele é criado no início da transação e fechado ao seu final ([COMMIT] ou [ROLLBACK]). As entidades que ele gerenciava tornam-se então desanexadas: são objetos [Java] comuns, que ninguém mais rastreia. Modificá-los não tem mais nenhum efeito sobre o banco de dados, e suas relações [LAZY] que não foram carregadas não podem mais ser carregadas.

A aplicação nunca manipula diretamente o [EntityManager]: os repositórios do [Spring Data JPA] cuidam disso em seu nome. Quando um método de repositório é chamado enquanto uma transação está em andamento (aberta pela camada de negócio), ele usa o [EntityManager] dessa transação: todos os repositórios chamados durante a transação compartilham, portanto, o mesmo contexto de persistência, a mesma conexão e a mesma transação. Quando nenhuma transação está em andamento, os métodos herdados de [JpaRepository] ([findById], [save]...) abrem uma transação de curta duração pelo tempo da chamada (somente leitura para operações de leitura); as consultas declaradas em nossas interfaces ([findAllByOrderByLastNameAscFirstNameAsc], os métodos [@Query] etc.) são executadas sem transação: o [Spring] cria um [EntityManager] pelo tempo da chamada e depois o fecha. Nos dois casos, as entidades retornadas ficam imediatamente desanexadas.

11.9.3. A configuração

Tudo de que o [Hibernate] precisa é produzido pelo [Spring Boot] (esta é a autoconfiguração) com base nas chaves [spring.datasource.*] e [spring.jpa.*] do arquivo [application.properties] (veja a seção “Configuração do projeto”):

1
2
3
4
5
6
7
8
# ——— o banco de dados MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# o Hibernate não cria nem modifica as tabelas: esse é o papel do script SQL
spring.jpa.hibernate.ddl-auto=none
# a conexão com o banco de dados não é mantida aberta enquanto a view é construída
spring.jpa.open-in-view=false
  • Linhas 2–4: as chaves [spring.datasource.*] descrevem a conexão: a URL do banco de dados e JDBC (o protocolo [jdbc:mysql:], a máquina, a porta e o nome do banco de dados), o nome de usuário e a senha. [Spring Boot] cria, na verdade, um [DataSource], um pool de conexões. Abrir uma conexão com um banco de dados consome muitos recursos: este [DataSource] é um pool de conexões (a biblioteca [HikariCP]), que mantém algumas conexões abertas e as empresta por turnos;
  • Linha 6: [ddl-auto=none]: o [Hibernate] não cria nem modifica tabelas (ele poderia criá-las a partir das entidades, com o valor [create], ou ajustá-las com [update]): o banco de dados é descrito pelo script SQL, e somente por ele;
  • Linha 8: [open-in-view=false] fecha o [EntityManager] assim que a transação termina, sem mantê-lo aberto até o final da requisição HTTP (veja abaixo).

Com base no [DataSource] e nas entidades, o [Spring Boot] também cria o [EntityManagerFactory] (que cria os [EntityManager]), um gerenciador de transações ([JpaTransactionManager]) e um [TransactionTemplate], que a camada de negócio usa para abrir suas transações. O dialeto SQL (recursos específicos do [MySQL]: [limit], acentos graves etc.) é derivado automaticamente do banco de dados ao qual você se conecta.

O arquivo [application-dev.properties], que também é lido quando o perfil [dev] está ativo (como acontece com [./mvnw spring-boot:run]), adiciona a chave [spring.jpa.show-sql=true]: o [Hibernate] passa então a exibir no console cada comando SQL que envia. Todas as consultas mostradas neste capítulo foram capturadas dessa forma.

Em comparação com o [DbContext] da versão [ASP.NET Core], faltam dois itens porque não são mais necessários: a lista de tabelas (as entidades são encontradas automaticamente porque estão no pacote da aplicação ou em um de seus subpacotes) e os detalhes de [OnModelCreating] (a relação “um para um” é especificada por [@OneToOne], a conversão do papel em texto por [@Enumerated] e o incremento da versão por [@Version]).

11.9.4. open-in-view=false: carregar explicitamente as relações

Por padrão ([spring.jpa.open-in-view=true]), o [Spring Boot] abre um [EntityManager] no início de cada requisição HTTP e só o fecha depois que a view foi gerada: uma view pode então ler uma relação [LAZY] não carregada ([${appointment.client.lastName}]), e o [Hibernate] envia a consulta necessária no momento da exibição. Isso é conveniente, mas consultas SQL passam a poder ser enviadas de qualquer lugar, inclusive de uma view [Thymeleaf], a conexão permanece ocupada durante toda a renderização da página, e um laço com 20 eventos pode disparar 20 pequenas consultas em vez de uma (o chamado problema “N+1”). [Spring Boot] também exibe um aviso na inicialização quando a chave não é especificada.

A aplicação opta por [open-in-view=false]: o [EntityManager] é fechado ao final de cada transação (ou de cada chamada a um repositório feita fora de uma transação), e as entidades que saem da camada de negócio ficam desanexadas. O resultado é uma regra que deve ser seguida em toda parte: cada leitura carrega explicitamente as relações de que a página precisará, usando [@EntityGraph] ou [join fetch] (veja “A camada DAO”). Ler uma relação [LAZY] que não foi carregada — por exemplo, a conta de um médico lida por uma consulta que não a solicitou — dispararia uma [LazyInitializationException]: o agente não pode mais ler nada; o [EntityManager] está fechado. Em contrapartida, sabemos exatamente quais consultas são enviadas e quando: todas estão na camada DAO.

11.10. O domínio: a agenda

A pasta [domain] contém duas classes que não correspondem a nenhuma tabela: elas descrevem a agenda de um médico para um único dia, calculada pela camada de negócio ([BusinessService.getDoctorDaySchedule]) e exibida pelo controller da agenda.

11.10.1. domain/DoctorDaySlot.java

// =========================================================================
// domain/DoctorDaySlot.java
// -------------------------------------------------------------------------
// Um objeto "de negócio" (sem tabela) que associa um horário à
// consulta eventualmente marcada nesse horário, em um determinado dia.
//
// Um record Java é uma classe cujos campos são definidos de uma vez por
// todas pelo construtor (objeto imutável): exatamente o que é necessário
// para um objeto calculado, que ninguém modifica depois.
// =========================================================================
package rdvmedecins.domain;

import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Appointment;

// appointment: null se o horário estiver livre nesse dia
public record DoctorDaySlot(Slot slot, Appointment appointment) {
}
  • Linha 17: um horário e a consulta marcada para esse horário nesse dia, ou [null] se o horário estiver livre. Um record (a partir do [Java] 16) declara uma classe em uma única linha, cujos campos são definidos de uma vez por todas pelo construtor: o próprio compilador escreve os campos privados e [final] (não modificáveis), o construtor de dois parâmetros, os acessores [slot()] e [appointment()] (sem o prefixo [get]) e os métodos [equals], [hashCode] e [toString]. O corpo do record, entre chaves, está vazio aqui. Já encontramos records para os dados transmitidos à camada de negócio (veja o Exemplo 28).

11.10.2. domain/DoctorDaySchedule.java

// =========================================================================
// domain/DoctorDaySchedule.java
// -------------------------------------------------------------------------
// A agenda completa de um médico para um determinado dia: a lista de seus
// horários, cada um livre ou ocupado por uma consulta. Calculada por
// BusinessService.getDoctorDaySchedule, transformada em uma tabela HTML por
// ScheduleController.
// =========================================================================
package rdvmedecins.domain;

import java.time.LocalDate;
import java.util.List;

import rdvmedecins.entities.Doctor;

public record DoctorDaySchedule(Doctor doctor, LocalDate day, List<DoctorDaySlot> doctorDaySlots) {
}

A agenda (linha 16): um médico, um dia e a lista de seus horários — livres ou ocupados — em ordem cronológica. As views do [Thymeleaf] podem ler os acessores de um record: [${schedule.day}] chama [day()].

11.11. A camada DAO

Um DAO por tabela, como no Exemplo 28: métodos sem lógica de negócio, que simplesmente consultam ou modificam o banco de dados. Aqui são chamados de repositórios. Com o [Spring Data JPA], um repositório é uma simples interface: quando a aplicação inicia, o [Spring] gera uma classe que a implementa, a transforma em um bean e a injeta onde for necessária. A interface herda de [JpaRepository<T, ID>] ([T]: o tipo da entidade; [ID]: o tipo de sua chave primária), que fornece os métodos padrão: [findById], [findAll], [save], [deleteById], [getReferenceById]... Consultas específicas da aplicação são adicionadas de três maneiras:

  • pelo nome do método: o [Spring Data JPA] analisa o nome ([find] ... [By] *critérios* [OrderBy] *ordenação*) e deriva a consulta a partir dele. Um erro no nome de um campo é detectado na inicialização, fazendo o processo falhar;
  • em JPQL, com a anotação [@Query]. [JPQL] (Jakarta Persistence Query Language) é a linguagem de consulta do [JPA]: ela se assemelha ao SQL, mas se refere a entidades e seus campos ([Appointment], [a.client]), em vez de tabelas e suas colunas. O [Hibernate] a traduz em SQL;
  • em SQL, com [@Query(nativeQuery = true)], quando o [JPQL] não é suficiente.

Os métodos que podem não retornar nada devolvem um [Optional<T>] (pacote [java.util]): uma caixa que contém um objeto ou está vazia. O chamador não pode usar o resultado sem antes verificar se ele existe ([isPresent()], [orElseThrow(...)]...): não há [null] esquecido.

Assim como as entidades, os repositórios não gerenciam transações: é a camada de negócio que as abre.

11.11.1. repositories/PersonRepository.java

Os repositórios de médicos e de clientes seriam idênticos: uma interface genérica permite escrevê-los uma única vez.

// =========================================================================
// repositories/PersonRepository.java
// -------------------------------------------------------------------------
// A camada DAO comum aos médicos e aos clientes.
//
// Com o Spring Data JPA, um DAO é uma simples INTERFACE: o Spring escreve
// sua implementação na inicialização. JpaRepository<T, Integer> já
// traz findById, findAll, save, delete...; acrescentamos a ele nossas consultas:
//   - seja pelo NOME do método, que o Spring Data traduz em uma consulta
//     (findFirstByFirstNameAndLastName -> ... WHERE first_name = ? AND last_name = ? LIMIT 1);
//   - seja por uma consulta JPQL escrita em uma anotação @Query. O JPQL
//     se parece com SQL, mas trata das classes e de seus campos, não das
//     tabelas e de suas colunas.
//
// Os DAOs dos médicos e dos clientes seriam idênticos: esta interface
// GENÉRICA os escreve uma única vez, sendo T Doctor ou Client.
// @NoRepositoryBean: o Spring não cria um DAO para esta interface
// em si, apenas para suas subinterfaces DoctorRepository e
// ClientRepository. Nas consultas, #{#entityName} designa a entidade da
// subinterface (Doctor ou Client).
//
// Transações: todos os métodos DAO de uma mesma requisição HTTP
// usam a transação atual, se houver uma (veja BusinessService).
// =========================================================================
package rdvmedecins.repositories;

import java.util.List;
import java.util.Optional;

import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.NoRepositoryBean;

import rdvmedecins.entities.Person;

@NoRepositoryBean
public interface PersonRepository<T extends Person> extends JpaRepository<T, Integer> {

    // lista ordenada por sobrenome e depois por nome, conta de usuário incluída.
    // @EntityGraph(attributePaths = "user"): traz TAMBÉM a conta, por meio de um
    // join (SELECT ... FROM doctors LEFT JOIN users ...). Sem isso, a
    // conta só seria lida no primeiro acesso - impossível fora de uma
    // transação: essas listas são mantidas em memória pelo cache
    // (web/ApplicationModel.java), muito depois do fim da requisição.
    @EntityGraph(attributePaths = "user")
    List<T> findAllByOrderByLastNameAscFirstNameAsc();

    // uma pessoa e sua conta
    @EntityGraph(attributePaths = "user")
    Optional<T> findWithUserById(int id);

    // a pessoa cuja conta de usuário é [userId]
    @EntityGraph(attributePaths = "user")
    Optional<T> findByUserId(int userId);

    // a pessoa que tem esses nome e sobrenome, se houver. A comparação
    // é feita pelo MySQL, portanto com a collation do banco de dados
    // (utf8mb4_unicode_ci: sem distinção de maiúsculas e acentos) -
    // exatamente a mesma regra da restrição SQL de unicidade.
    Optional<T> findFirstByFirstNameAndLastName(String firstName, String lastName);

    // um DELETE enviado diretamente ao banco de dados, sem ler a pessoa antes.
    // @Modifying: a consulta modifica dados (não é um SELECT)
    @Modifying
    @Query("delete from #{#entityName} p where p.id = :id")
    void remove(int id);
}

Vamos comentar este código:

  • linha 39: [PersonRepository<T extends Person>] é uma interface genérica: [T] é um parâmetro de tipo, substituído por um tipo real ([Doctor] ou [Client]) nas subinterfaces, como [T] em [List<T>]. [extends Person] aceita apenas [Person] ou suas classes-filhas para [T]: nas consultas, [T] inclui, portanto, necessariamente os campos [lastName], [firstName], [user], [userId]... A interface herda de [JpaRepository<T, Integer>]: entidade [T], chave primária do tipo [Integer];
  • linha 38: [@NoRepositoryBean] instrui o [Spring Data JPA] a não criar um repositório para esta interface em si, que não se refere a nenhuma entidade específica ([T] é desconhecido), mas apenas para suas subinterfaces [DoctorRepository] e [ClientRepository];
  • linhas 47–48: todas as pessoas, ordenadas por sobrenome e depois por nome. O nome do método é a consulta: [findAll] (a palavra [All] é incluída apenas para facilitar a leitura), [By] sem critérios (todas as linhas), [OrderByLastNameAscFirstNameAsc] (em ordem crescente de sobrenome e depois de nome). [@EntityGraph(attributePaths = "user")] exige que a relação [user] também seja carregada na mesma consulta por meio de um join; sem isso, o campo [user] de cada pessoa seria um proxy não carregado. Isso é essencial aqui: essas listas são mantidas em memória pelo cache ([web/ApplicationModel.java]) muito depois do fim da transação, e as views exibem o login de cada pessoa;
  • Linhas 51–52: uma pessoa e sua conta, ou um [Optional] vazio. [JpaRepository] já fornece [findById], mas sem a conta; não é possível adicionar [@EntityGraph] a ele sem alterar todos os seus usos. Por isso, declaramos outro método: em um nome de método, o [Spring Data JPA] ignora o texto entre [find] e [By] (aqui, [WithUser]), que serve apenas para dizer ao leitor o que o método retorna. A consulta é a de [findById] ([where id = ?]), e [@EntityGraph] lhe acrescenta o join;
  • linhas 55–56: a pessoa cuja conta é [userId]: o critério se aplica ao campo [userId] (somente leitura) e, portanto, diretamente à coluna [user]. É assim que um paciente logado, cujo token contém o ID da conta, recupera seu registro de cliente;
  • linha 62: um possível homônimo. [First] limita o resultado a uma única linha ([limit ?] em SQL), [ByFirstNameAndLastName] atende aos dois critérios, ligados por [and]. Os parâmetros do método são associados aos critérios na ordem. A comparação é feita pelo [MySQL], de acordo com a collation do banco de dados, sem distinção entre maiúsculas e minúsculas nem acentos, exatamente como a restrição de unicidade;
  • linhas 66–68: a exclusão de uma pessoa por meio de uma consulta [JPQL] [delete], enviada diretamente ao banco de dados sem ler antes a pessoa (o equivalente a [ExecuteDeleteAsync] do [Entity Framework Core]). [@Modifying] indica que a consulta modifica dados: sem ela, o [Spring Data JPA] a trataria como um [select]. Uma consulta assim deve ser executada dentro de uma transação que permita gravações: a camada de negócio abre essa transação. Ela não passa pelo contexto de persistência e, portanto, não passa pelo bloqueio otimista;
  • Linha 67: a interface é genérica, mas uma consulta [JPQL] deve especificar uma entidade em particular: [delete from Doctor] ou [delete from Client]. [#{...}] introduz uma expressão SpEL (Spring Expression Language, a linguagem de expressões do [Spring]), avaliada na inicialização; a variável [#entityName] denota o nome da entidade no repositório específico. Para [DoctorRepository], a consulta se torna [delete from Doctor p where p.id = :id];
  • linhas 67–68: [:id] é um parâmetro nomeado da consulta, associado ao parâmetro [id] do método (pelo nome). Seu valor é enviado ao banco de dados separadamente do texto da consulta: não há concatenação de strings, portanto uma injeção de SQL não é possível.

Eis as consultas realmente enviadas pelo [Hibernate] para a lista de clientes (linha 48) e para a busca de um homônimo entre os médicos (linha 62):

Hibernate: select c1_0.id,c1_0.first_name,c1_0.last_name,c1_0.title,u1_0.id,u1_0.login,u1_0.name,u1_0.password,u1_0.role,u1_0.version,c1_0.`user`,c1_0.version from clients c1_0 left join users u1_0 on u1_0.id=c1_0.`user` order by c1_0.last_name,c1_0.first_name
Hibernate: select d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version from doctors d1_0 where d1_0.first_name=? and d1_0.last_name=? limit ?

A primeira recupera os clientes e suas contas em uma única consulta ([left join users]); a segunda, sem [@EntityGraph], recupera apenas a tabela [doctors].

11.11.2. repositories/DoctorRepository.java

// =========================================================================
// repositories/DoctorRepository.java
// -------------------------------------------------------------------------
// O DAO dos médicos: tudo é herdado de PersonRepository.
// O Spring Data constrói sua implementação na inicialização.
// =========================================================================
package rdvmedecins.repositories;

import rdvmedecins.entities.Doctor;

public interface DoctorRepository extends PersonRepository<Doctor> {
}

O repositório dos médicos (linha 11): [PersonRepository<Doctor>], sem mais nada. É esta interface — e não a [@NoRepositoryBean] — que o [Spring Data JPA] implementa: todos os métodos herdados nela dizem respeito à entidade [Doctor].

11.11.3. repositories/ClientRepository.java

// =========================================================================
// repositories/ClientRepository.java
// -------------------------------------------------------------------------
// O DAO dos clientes: o das pessoas, mais um método de bloqueio.
// =========================================================================
package rdvmedecins.repositories;

import java.util.Optional;

import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.Client;

public interface ClientRepository extends PersonRepository<Client> {

    // -----------------------------------------------------------------------
    // coloca um LOCK na linha de um cliente até o fim da transação
    // atual (SELECT ... FOR UPDATE) e retorna seu id
    // (Optional vazio se o cliente não existir). Uma segunda transação que
    // solicitar o mesmo lock ESPERA até que a primeira termine.
    // Usado para marcar uma consulta (veja BusinessService.addAppointment):
    // duas marcações simultâneas para o mesmo paciente são assim processadas
    // uma DEPOIS da outra, e a segunda vê a consulta criada pela primeira.
    //
    // nativeQuery = true: a consulta é SQL, enviada como está ao banco de dados,
    // e não JPQL traduzida pelo Hibernate. O JPA também pode colocar este lock
    // (@Lock(LockModeType.PESSIMISTIC_WRITE) em uma consulta JPQL), mas o
    // Hibernate escreve então "FOR UPDATE OF c1_0", uma sintaxe do MySQL 8 que
    // o MariaDB (o "MySQL" de algumas distribuições) recusa. Este SQL
    // funciona com ambos.
    // :id é um PARÂMETRO da consulta (sem concatenação de strings,
    // portanto sem possibilidade de injeção de SQL).
    // -----------------------------------------------------------------------
    @Query(value = "select id from clients where id = :id for update", nativeQuery = true)
    Optional<Integer> lock(int id);
}
  • Linha 14: o repositório dos clientes — o das pessoas, contendo [T = Client], mais um método;
  • Linhas 34–35: leitura de um cliente com um bloqueio. [SELECT ... FOR UPDATE] coloca um bloqueio na linha até o fim da transação atual: outra transação que solicite o mesmo bloqueio espera até que a primeira termine. A função de marcação de consultas ([BusinessService.addAppointment]) usa isso para processar, uma após a outra, duas reservas simultâneas para o mesmo paciente: a segunda reserva enxerga a consulta criada pela primeira e, assim, respeita a regra “apenas uma consulta futura”. O método retorna somente o ID do cliente ([select id]) em um [Optional] vazio se o cliente não existir: ele serve unicamente para adquirir o bloqueio e verificar a existência do cliente;
  • linha 34: [nativeQuery = true]: a consulta é em SQL, enviada como está ao banco de dados, e não em [JPQL]. No entanto, o [JPA] pode definir esse bloqueio por conta própria: a anotação [@Lock(LockModeType.PESSIMISTIC_WRITE)], adicionada a uma consulta em [JPQL], instrui o [Hibernate] a acrescentar a cláusula de bloqueio a ela. Mas, para o [MySQL] 8, o [Hibernate] escreve então [for update of c1_0] (o bloqueio se aplica apenas à tabela especificada), uma sintaxe específica do [MySQL] 8 que o [MariaDB] — frequentemente instalado no lugar do [MySQL] — rejeita. O SQL escrito manualmente, [for update] sem [of], funciona com ambos. [:id] é, mais uma vez, um parâmetro da consulta.

A consulta, como aparece no console durante uma reserva:

Hibernate: select id from clients where id = ? for update

11.11.4. repositories/SlotRepository.java

// =========================================================================
// repositories/SlotRepository.java
// -------------------------------------------------------------------------
// Camada DAO da entidade [Slot].
// =========================================================================
package rdvmedecins.repositories;

import java.util.List;
import java.util.Optional;

import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.Slot;

public interface SlotRepository extends JpaRepository<Slot, Integer> {

    // um horário e seu médico
    @EntityGraph(attributePaths = "doctor")
    Optional<Slot> findWithDoctorById(int id);

    // os horários de um médico, em ordem cronológica
    List<Slot> findByDoctorIdOrderByStartHourAscStartMinuteAsc(int doctorId);

    // exclui todos os horários de um médico (exclusão de um médico):
    //   DELETE FROM slots WHERE doctor_id = ?
    @Modifying
    @Query("delete from Slot s where s.doctorId = :doctorId")
    void deleteByDoctor(int doctorId);
}
  • linha 18: um repositório comum: entidade [Slot], chave primária [Integer];
  • linhas 21–22: um horário e seu médico ([@EntityGraph(attributePaths = "doctor")]), seguindo o modelo de [findWithUserById];
  • linha 25: os horários de um médico, em ordem cronológica: [ByDoctorId] filtra pelo campo [doctorId] (isto é, a coluna [doctor_id]), [OrderByStartHourAscStartMinuteAsc] ordena por hora e depois por minuto de início. [Hibernate] envia [select ... from slots s1_0 where s1_0.doctor_id=? order by s1_0.start_hour,s1_0.start_minute];
  • Linhas 29–31: exclusão dos horários de um médico com um único [DELETE]. A camada de negócio chama este método antes de excluir o médico; caso contrário, a chave estrangeira [slots.doctor_id] impediria a exclusão. O método não se chama [deleteByDoctorId]: um nome assim também seria interpretado pelo [Spring Data JPA], mas a consulta inferida iria primeiro ler os horários e depois os excluiria um a um; a consulta [@Query] envia um único comando, [DELETE].

11.11.5. repositories/AppointmentRepository.java

// =========================================================================
// repositories/AppointmentRepository.java
// -------------------------------------------------------------------------
// Camada DAO da entidade [Appointment].
//
// As consultas JPQL navegam de uma entidade para outra pelos campos
// de relação (a.slot.doctorId): o Hibernate escreve ele mesmo os joins SQL
// necessários. "join fetch" também traz a entidade associada (o equivalente
// de um @EntityGraph).
// =========================================================================
package rdvmedecins.repositories;

import java.time.LocalDate;
import java.util.List;
import java.util.Optional;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.Appointment;

public interface AppointmentRepository extends JpaRepository<Appointment, Integer> {

    // uma consulta, seu cliente e seu horário
    @Query("select a from Appointment a join fetch a.client join fetch a.slot where a.id = :id")
    Optional<Appointment> read(int id);

    // as consultas de um médico em um determinado dia, cliente e horário incluídos.
    // A tabela [appointments] não referencia o médico diretamente: passamos pelo horário.
    @Query("""
            select a from Appointment a join fetch a.client join fetch a.slot s
            where s.doctorId = :doctorId and a.day = :day""")
    List<Appointment> doctorDayAppointments(int doctorId, LocalDate day);

    // as consultas de um cliente a partir do dia [fromDay] (inclusive), em
    // ordem cronológica, com o horário E o médico desse horário
    @Query("""
            select a from Appointment a join fetch a.slot s join fetch s.doctor
            where a.clientId = :clientId and a.day >= :fromDay
            order by a.day, s.startHour, s.startMinute""")
    List<Appointment> clientUpcomingAppointments(int clientId, LocalDate fromDay);

    // número de consultas de um cliente a partir do dia [fromDay] (inclusive)
    long countByClientIdAndDayGreaterThanEqual(int clientId, LocalDate fromDay);

    // número de consultas (passadas ou futuras) de um médico
    @Query("select count(a) from Appointment a where a.slot.doctorId = :doctorId")
    long countByDoctor(int doctorId);

    // exclui uma consulta: DELETE FROM appointments WHERE id = ?
    @Modifying
    @Query("delete from Appointment a where a.id = :id")
    void remove(int id);

    // exclui TODAS as consultas (passadas e futuras) de um cliente
    @Modifying
    @Query("delete from Appointment a where a.clientId = :clientId")
    void deleteByClient(int clientId);
}

Vamos comentar este código:

  • Linhas 26–27: uma consulta com seu cliente e seu horário. Em [JPQL], [join fetch a.client] realiza um join e carrega a entidade associada no resultado: é o equivalente, escrito na consulta, de [@EntityGraph]. Um join é feito seguindo um campo de relação ([a.client]): o [Hibernate] conhece a chave estrangeira ([@JoinColumn]) e escreve a condição [on] por conta própria. Com [@Query], o nome do método é arbitrário: a consulta escrita é a que é executada. O nome [findById] já está ocupado pelo método herdado de [JpaRepository], que não carrega nem o cliente nem o horário;
  • Linhas 31–34: as consultas de um médico em um dia determinado, cada uma com seu cliente e seu horário. A consulta é escrita em um bloco de texto [Java] (desde o [Java] 15): uma string delimitada por três aspas ["""], que pode ocupar várias linhas. A tabela [appointments] não faz referência direta aos médicos: passamos pelo horário, ao qual o join atribui o alias [s], e depois filtramos por [s.doctorId]. [a.day = :day] compara duas datas: o [Hibernate] passa [LocalDate] como um valor SQL [DATE];
  • Linhas 38–42: as consultas de um paciente a partir do dia [fromDay], junto com seu horário e o médico atribuído a esse horário: [join fetch s.doctor] segue a relação do horário até seu médico (dois joins em cascata). A ordenação é feita pelo dia e depois pela hora do horário. É isso que “Minha conta” exibe. O médico atribuído não tem seu próprio registro ([user]): a página não precisa dele;
  • Linha 45: o número de consultas de um cliente a partir do dia [fromDay], para a regra “apenas uma consulta futura”: [count] gera um [select count(...)], [GreaterThanEqual] gera a comparação [>=]. O resultado é do tipo [long];
  • Linhas 48–49: o número de consultas de um médico, para impedir a exclusão de um médico que tenha alguma. [a.slot.doctorId] segue a relação [slot] sem [join fetch]: o [Hibernate] adiciona o join com [slots] para filtrar, sem carregar nada;
  • linhas 52–54: cancelamento de uma consulta por meio de uma chamada direta a [DELETE] . [JpaRepository] de fato fornece [deleteById], mas esse método primeiro lê a consulta e só depois a exclui;
  • linhas 57–59: exclusão de todas as consultas de um cliente, passadas e futuras: a camada de negócio chama isto antes de excluir o cliente, o que a chave estrangeira [appointments.client_id] impediria de outra forma.

Eis a consulta da linha 42, como o [Hibernate] a traduz em SQL: os dois [join fetch]s tornaram-se dois joins, e as colunas do horário e do médico são lidas ao mesmo tempo que as da consulta:

Hibernate: select a1_0.id,a1_0.client_id,a1_0.day,s1_0.id,d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version,s1_0.doctor_id,s1_0.end_hour,s1_0.end_minute,s1_0.start_hour,s1_0.start_minute,s1_0.version,a1_0.slot_id,a1_0.version from appointments a1_0 join slots s1_0 on s1_0.id=a1_0.slot_id join doctors d1_0 on d1_0.id=s1_0.doctor_id where a1_0.client_id=? and a1_0.day>=? order by a1_0.day,s1_0.start_hour,s1_0.start_minute

Observe que um [join fetch] produz um inner join ([join]), enquanto o [@EntityGraph] de [PersonRepository] produziu um outer join ([left join]): aqui, toda consulta deve ter um horário, e todo horário deve ter um médico.

11.11.6. repositories/UserRepository.java

// =========================================================================
// repositories/UserRepository.java
// -------------------------------------------------------------------------
// Camada DAO da entidade [User]. Criar (ou excluir) um médico ou um
// cliente também cria (ou exclui) sua conta - veja business/BusinessService.java.
// =========================================================================
package rdvmedecins.repositories;

import java.util.Optional;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;

import rdvmedecins.entities.User;

public interface UserRepository extends JpaRepository<User, Integer> {

    // Optional.empty() se nenhum usuário tiver este login
    Optional<User> findByLogin(String login);

    @Modifying
    @Query("delete from User u where u.id = :id")
    void remove(int id);
}
  • Linha 20: a conta associada a este login, ou um [Optional] vazio. Ela é usada para fazer login ([AuthService]) e para verificar se um login está disponível antes de atribuí-lo;
  • Linhas 22–24: exclusão de uma conta por meio de uma chamada direta a [DELETE]. A ordem é o inverso da criação: a camada de negócio primeiro exclui a pessoa, que referencia a conta, e depois exclui a conta.

A criação e a modificação de contas usam o método [save], herdado de [JpaRepository]: para uma nova entidade (ID [null]), ele chama [persist] de [EntityManager] (um [INSERT]); para uma entidade que já foi registrada, chama [merge]. Veremos que a camada de negócio, na verdade, só precisa de [save] para as criações.

11.12. A camada de negócio

A camada de negócio contém as regras de negócio da aplicação: nenhuma consulta no passado, apenas uma consulta futura por paciente, logins e pessoas únicos, e a possibilidade de excluir um médico ou um cliente. Ela se apoia na camada DAO (pasta [repositories]) para leitura e gravação, abre transações e nada sabe sobre HTML nem sobre o idioma da interface. Mais especificamente, esta é a camada [PersonsBusiness] do Exemplo 28.

11.12.1. business/Dates.java

// =========================================================================
// business/Dates.java
// -------------------------------------------------------------------------
// A data de hoje. Ela é usada por REGRAS DE NEGÓCIO (nenhuma marcação
// no passado, uma única consulta FUTURA por paciente): ela vive, portanto,
// na camada de negócio. A camada web a reutiliza.
// =========================================================================
package rdvmedecins.business;

import java.time.LocalDate;

public final class Dates {

    private Dates() {
    }

    // a data de hoje, no fuso horário do servidor
    public static LocalDate today() {
        return LocalDate.now();
    }
}
  • Linha 12: uma classe utilitária que simplesmente contém um método [static], chamado pelo nome da classe ([Dates.today()]). [final] impede a herança a partir dela;
  • linhas 14–15: um construtor [private] impede a criação de objetos [Dates], o que não faria sentido;
  • linhas 18–20: a data de hoje, no fuso horário do servidor, na forma de um [LocalDate] (uma data sem hora, o tipo de [Appointment.day]). Dois objetos [LocalDate] são comparados por meio dos seguintes métodos: [day.isBefore(today)], [isAfter], [equals]. A data atual é usada pelas regras de negócio, por isso fica na camada de negócio; a camada web a reutiliza (por exemplo, em [ScheduleController], para determinar se um dia ainda pode receber reservas).

11.12.2. business/BusinessException.java

// =========================================================================
// business/BusinessException.java
// -------------------------------------------------------------------------
// A exceção lançada pela camada de negócio quando uma REGRA DE NEGÓCIO é
// violada (login já utilizado, médico que ainda tem consultas, horário
// já reservado...). Ela não carrega um texto, mas uma
// CHAVE de tradução (p. ex., "ERRORS.LOGIN_TAKEN"): é a camada web que a
// traduzirá para francês ou inglês ao exibir a página
// (veja i18n/fr.json, i18n/en.json).
//
// Uma BusinessException não é uma anomalia: é uma resposta normal
// ("este login já está em uso"), exibida ao usuário. Qualquer outra
// exceção é uma anomalia real, que leva à página de erro 500.
//
// RuntimeException: uma exceção "não verificada" (unchecked); os métodos que
// a lançam não precisam declará-la (throws), e o Spring cancela (ROLLBACK) a
// transação que ela interrompe.
// =========================================================================
package rdvmedecins.business;

import java.util.Map;

public class BusinessException extends RuntimeException {

    // chave de tradução da mensagem
    private final String key;

    // possíveis parâmetros da mensagem ({minutes}...)
    private final Map<String, String> params;

    public BusinessException(String key) {
        this(key, Map.of());
    }

    public BusinessException(String key, Map<String, String> params) {
        super(key);
        this.key = key;
        this.params = params;
    }

    public String getKey() {
        return key;
    }

    public Map<String, String> getParams() {
        return params;
    }
}
  • Linha 23: a exceção lançada quando uma regra de negócio rejeita uma operação (veja o Exemplo 28). Ela herda de [RuntimeException]: é uma exceção não verificada. Em [Java], um método que pode lançar uma exceção verificada deve declará-la ([throws ...]), e o chamador deve tratá-la; uma exceção não verificada está isenta dessa exigência. Outra consequência importante: o [Spring] faz o rollback ([ROLLBACK]) de uma transação interrompida por uma exceção não verificada (ao passo que, com [@Transactional], uma exceção verificada, por padrão, permitiria o commit da transação);
  • Linhas 26 e 29: a chave de tradução da mensagem ([ERRORS.LOGIN_TAKEN]) e os eventuais parâmetros associados. Diferença em relação ao Exemplo 28: a exceção não carrega texto em francês, mas sim uma chave. A camada de negócio ignora, assim, o idioma da interface: é a camada web que traduzirá a chave por meio dos dicionários [i18n/fr.json] e [i18n/en.json] (veja a seção “Dicionários”). Os campos são [final]: definidos pelo construtor, eles não mudam;
  • linhas 31–33: o construtor sem parâmetros de mensagem. [this(key, Map.of())] chama o outro construtor da classe com um dicionário vazio: [Map.of()] cria um dicionário somente leitura. A camada web nunca precisa, portanto, testar [null]. As exceções lançadas por [BusinessService] usam, na verdade, apenas este construtor;
  • linha 36: [super(key)] passa a chave ao construtor da classe-mãe, que a usa como mensagem da exceção ([getMessage()]), útil nos logs de erro;
  • linhas 41–47: os acessores.

Uma [BusinessException] não é um erro: é uma resposta normal (“este login já está em uso”), que os controllers interceptam para exibir ao usuário, seja na página, seja em uma mensagem pop-up. Qualquer outra exceção é um erro verdadeiro, que resulta em uma página de erro 500.

11.12.3. business/Business.java

// =========================================================================
// business/Business.java
// -------------------------------------------------------------------------
// O contrato da camada de negócio: leituras, agenda, consultas, gerenciamento
// dos médicos e dos clientes.
//
// Optional<T>: um resultado que pode estar ausente (um médico que não existe
// ...). O chamador é obrigado a tratar esse caso: nenhum null esquecido.
// =========================================================================
package rdvmedecins.business;

import java.time.LocalDate;
import java.util.List;
import java.util.Optional;

import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Appointment;

public interface Business {

    // ——— leituras
    List<Client> getAllClients();

    List<Doctor> getAllDoctors();

    List<Slot> getAllSlots(int doctorId);

    List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day);

    Optional<Client> getClientById(int id);

    Optional<Doctor> getDoctorById(int id);

    Optional<Appointment> getAppointmentById(int id);

    Optional<Slot> getSlotById(int id);

    Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day);

    // o cliente (paciente) cuja conta de usuário é [userId]
    Optional<Client> getClientByUserId(int userId);

    // as consultas de um cliente, de hoje ou futuras, com horário e médico
    List<Appointment> getClientUpcomingAppointments(int clientId);

    // ——— consultas (ADMIN, DOCTOR, USER)
    // lança uma BusinessException se:
    //  - o dia já passou ("ERRORS.PAST_DATE");
    //  - o paciente já tem uma consulta futura ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    //  - o horário já está reservado nesse dia ("ERRORS.SLOT_ALREADY_BOOKED").
    Appointment addAppointment(LocalDate day, Slot slot, Client client);

    void deleteAppointment(Appointment appointment);

    // ——— médicos (ADMIN)
    // cria o médico E sua conta de usuário (papel DOCTOR)
    Doctor addDoctor(PersonData data);

    // edita o médico E sua conta de usuário
    Doctor editDoctor(int id, PersonData data);

    // exclui o médico, seus horários E sua conta - recusado se ele tiver consultas
    void deleteDoctor(int id);

    // ——— clientes
    // (o ADMIN; addClient também é usado para o cadastro de um paciente,
    // editClient e deleteClient pelo paciente para a própria conta)
    // cria o cliente E sua conta de usuário (papel USER)
    Client addClient(PersonData data);

    Client editClient(int id, PersonData data);

    // exclui o cliente, sua conta E todas as suas consultas (passadas e futuras)
    void deleteClient(int id);
}
  • linha 22: o contrato da camada de negócio: o que as outras camadas podem solicitar a ela, sem especificar como é feito (as interfaces foram discutidas no Exemplo 06);
  • linhas 25–47: as leituras. As que podem não encontrar nada (linhas 33–44) retornam um [Optional]: um médico desconhecido retorna um [Optional] vazio, nunca um [null]. As listas, por outro lado, ficam vazias quando não há nada a retornar;
  • linhas 50–56: as consultas. O comentário de [addAppointment] lista os códigos de erro possíveis: isso faz parte do contrato que os controllers devem conhecer;
  • linhas 60–66: gerenciamento de médicos (reservado ao ADMIN). Cada médico é criado, modificado e excluído junto com sua conta de usuário;
  • linhas 72–77: gerenciamento de clientes, com a mesma lógica. [addClient] também é usado para cadastrar um paciente, enquanto [editClient] e [deleteClient] são usados pelos pacientes que gerenciam suas próprias contas.

Os métodos de uma interface são implicitamente [public] e [abstract]: eles não são definidos explicitamente. Dois beans implementam esse contrato: [BusinessService], apresentado a seguir, e [ApplicationModel] (pasta [web]), que o estende com um cache das listas de médicos e clientes e delega o restante ao [BusinessService] (veja a seção “A camada web: serviços comuns”). Os controllers usam [ApplicationModel].

11.12.4. business/PersonData.java

// =========================================================================
// business/PersonData.java
// -------------------------------------------------------------------------
// Os dados digitados no formulário de "médico" ou de "cliente", como
// a camada web os repassa à camada de negócio.
// =========================================================================
package rdvmedecins.business;

public record PersonData(
        String title, // Mr, Mme, Melle
        String lastName,
        String firstName,
        // criação: opcional (null), assume por padrão o sobrenome em minúsculas
        // edição: opcional, o login permanece inalterado se estiver ausente
        String login,
        // criação: opcional, assume por padrão o login
        // edição: opcional, a senha permanece inalterada se estiver ausente
        String password,
        // edição: a versão do registro no momento em que o formulário foi
        // exibido (bloqueio otimista, veja AbstractEntity.version)
        Integer version) {
}

Os dados de um médico ou cliente a ser criado ou modificado, conforme transmitidos pela camada web (veja o Exemplo 28): um record, cujos componentes são escritos aqui um por linha para dar espaço aos comentários (linhas 9–21). Título, sobrenome e nome são sempre informados. Login e senha (linhas 15 e 18) são opcionais e valem [null] quando não são digitados: na criação, assumem por padrão o sobrenome em minúsculas; na modificação, permanecem inalterados. [version] (linha 21) é a versão do registro lido quando o formulário de edição é exibido: ela é usada para o bloqueio otimista. Seu tipo é [Integer], e não [int], para que possa ser [null] (na criação, não há versão).

11.12.5. business/BusinessService.java

Este é o arquivo mais completo da aplicação. Vamos mostrá-lo em cinco trechos consecutivos.

11.12.5.1. Os descritores

// =========================================================================
// business/BusinessService.java
// -------------------------------------------------------------------------
// Implementação da camada de negócio.
//
// O gerenciamento dos médicos e clientes obedece a três regras de negócio:
//
//   1. uma pessoa (médico ou cliente) e sua conta de usuário vão SEMPRE
//      juntas: são criadas, editadas e excluídas juntas, na
//      mesma TRANSAÇÃO - ou tudo dá certo, ou nada é gravado;
//   2. o login é único em toda a aplicação, e dois médicos (ou
//      dois clientes) não podem ter os mesmos nome e sobrenome;
//   3. exclusão:
//      - um MÉDICO que tem consultas não pode ser excluído (seus
//        pacientes perderiam a consulta sem serem avisados): elas devem
//        antes ser canceladas. Seus horários desaparecem com ele;
//      - um CLIENTE, por outro lado, desaparece com TODAS as suas consultas (passadas e
//        futuras) - quer a exclusão venha do ADMIN
//        ou do próprio paciente.
//
// E duas regras para marcar uma consulta, qualquer que seja o papel de
// quem marca (ADMIN, DOCTOR ou o próprio paciente):
//   4. nenhuma consulta no passado;
//   5. um paciente tem apenas UMA consulta futura por vez.
//
// Médicos e clientes seguem exatamente as mesmas regras: o código comum
// é escrito UMA VEZ (métodos privados genéricos xxxPerson), e parametrizado
// por um pequeno "descritor" que indica com que tipo de pessoa estamos lidando.
//
// As TRANSAÇÕES são abertas explicitamente, por um TransactionTemplate
// (veja o método transaction, no final do arquivo), a fim de traduzir em
// BusinessException os erros que o banco de dados reporta no momento do COMMIT.
// =========================================================================
package rdvmedecins.business;

import java.time.LocalDate;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.IntToLongFunction;
import java.util.function.Supplier;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

import org.springframework.core.NestedExceptionUtils;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.dao.OptimisticLockingFailureException;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Service;
import org.springframework.transaction.support.TransactionTemplate;

import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.domain.DoctorDaySlot;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Person;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.Appointment;
import rdvmedecins.entities.User;
import rdvmedecins.repositories.ClientRepository;
import rdvmedecins.repositories.SlotRepository;
import rdvmedecins.repositories.DoctorRepository;
import rdvmedecins.repositories.PersonRepository;
import rdvmedecins.repositories.AppointmentRepository;
import rdvmedecins.repositories.UserRepository;

// @Service: um bean da camada de negócio; uma única instância (singleton)
// para toda a aplicação
@Service
public class BusinessService implements Business {

    // tudo o que distingue um médico de um cliente para as regras de negócio
    private record Descriptor<T extends Person>(
            PersonRepository<T> dao,
            Supplier<T> factory, // Doctor::new ou Client::new
            Role role, // DOCTOR ou USER
            String notFoundKey, // mensagem se a pessoa não existir
            String alreadyExistsKey, // mensagem se os mesmos nome e sobrenome já existirem
            // opcional (null): se presente, a exclusão é RECUSADA enquanto a pessoa
            // tiver consultas (countAppointments > 0), com a mensagem hasAppointmentsKey
            IntToLongFunction countAppointments,
            String hasAppointmentsKey,
            // opcional: o que deve ser excluído ANTES da pessoa (as linhas
            // que a referenciam por uma chave estrangeira)
            IntConsumer beforeDelete) {
    }

    private final DoctorRepository doctorRepository;
    private final ClientRepository clientRepository;
    private final SlotRepository slotRepository;
    private final AppointmentRepository appointmentRepository;
    private final UserRepository userRepository;
    private final PasswordEncoder hasher;
    private final TransactionTemplate transactions;
    private final Descriptor<Doctor> doctorDescriptor;
    private final Descriptor<Client> clientDescriptor;

    // todas as dependências são fornecidas pela injeção de dependência do
    // Spring. TransactionTemplate: um bean fornecido pelo Spring Boot, que executa
    // código em uma transação.
    public BusinessService(DoctorRepository doctorRepository, ClientRepository clientRepository,
            SlotRepository slotRepository, AppointmentRepository appointmentRepository, UserRepository userRepository,
            PasswordEncoder hasher, TransactionTemplate transactions) {
        this.doctorRepository = doctorRepository;
        this.clientRepository = clientRepository;
        this.slotRepository = slotRepository;
        this.appointmentRepository = appointmentRepository;
        this.userRepository = userRepository;
        this.hasher = hasher;
        this.transactions = transactions;

        doctorDescriptor = new Descriptor<>(
                doctorRepository,
                Doctor::new,
                Role.DOCTOR,
                "ERRORS.DOCTOR_NOT_FOUND",
                "ERRORS.DOCTOR_ALREADY_EXISTS",
                appointmentRepository::countByDoctor,
                "ERRORS.DOCTOR_HAS_APPOINTMENTS",
                // um médico sem consultas ainda pode ter horários:
                // eles não fazem mais sentido sem ele, e os excluímos junto (caso contrário
                // a chave estrangeira slots.doctor_id impediria a exclusão)
                slotRepository::deleteByDoctor);

        clientDescriptor = new Descriptor<>(
                clientRepository,
                Client::new,
                Role.USER,
                "ERRORS.PATIENT_NOT_FOUND",
                "ERRORS.PATIENT_ALREADY_EXISTS",
                // sem countAppointments: a exclusão de um cliente nunca é recusada;
                // suas consultas (passadas e futuras) são excluídas junto (caso contrário
                // a chave estrangeira appointments.client_id impediria a exclusão)
                null,
                null,
                appointmentRepository::deleteByClient);
    }
  • linhas 6–24: o comentário de cabeçalho resume as cinco regras de negócio aplicadas pela classe;
  • linhas 50–52: as exceções do [Spring] que indicam um erro de banco de dados e um utilitário para examiná-las (veja o último trecho);
  • linha 53: a interface [PasswordEncoder] do [Spring Security], que calcula os hashes [bcrypt] (veja o Exemplo 25). O bean correspondente, um [BCryptPasswordEncoder] com custo 10 (o mesmo das senhas do script SQL), é declarado em [config/SecurityConfig.java] (veja a seção “Autenticação”);
  • linha 55: [TransactionTemplate], que executa código dentro de uma transação (veja o último trecho);
  • linhas 75–76: [@Service] torna a classe um bean da camada de negócio. Como todos os beans padrão, ele é um singleton: uma única instância para toda a aplicação, compartilhada por todas as requisições. Isso não é um problema, pois o objeto não armazena nenhum dado específico de requisição: seus campos são dependências, definidas de uma vez por todas. O nome do bean é o da classe, com a primeira letra minúscula: [businessService], o nome referenciado por [ApplicationModel] em seu [@Qualifier]. A classe implementa a interface [Business]: ela deve fornecer todos os seus métodos;
  • linhas 79–92: tudo o que distingue um médico de um cliente em termos de regras de negócio: seu repositório, a forma de criar um objeto vazio, o papel de sua conta ([DOCTOR] ou [USER]), suas mensagens de erro e o que acontece quando ele é excluído. Como médicos e clientes seguem as mesmas regras, o código dessas regras é escrito uma única vez, em métodos genéricos que recebem um descritor. O descritor é um record genérico, declarado dentro da classe (e [private]: ninguém mais o usa);
  • Linhas 81, 87 e 91: três interfaces funcionais do pacote [java.util.function] — interfaces de método único que descrevem o tipo de uma função. [Supplier<T>] é uma função sem parâmetros que retorna um [T] (método [get()]); [IntToLongFunction], uma função que recebe um [int] e retorna um [long] (método [applyAsLong]); [IntConsumer], uma função que recebe um [int] e não retorna nada (método [accept]). Um valor desse tipo pode ser escrito como uma lambda ([x -> ...]) ou uma referência a método ([Class::method]);
  • linhas 94–102: os campos da classe: os cinco repositórios, o calculador de hashes, [TransactionTemplate] e os dois descritores. [final] impede que sejam modificados após o construtor;
  • linhas 107–109: todas as dependências são fornecidas por injeção de dependência pelo [Spring]: a classe tem apenas um construtor, que o [Spring] chama com os beans dos tipos solicitados. Os repositórios são as implementações escritas pelo [Spring Data JPA]; [TransactionTemplate] é criado pelo [Spring Boot];
  • Linhas 118–129: o descritor de médico. [new Descriptor<>(...)]: o símbolo diamante [<>] permite que o compilador infira o parâmetro de tipo ([Doctor]) da variável que recebe o objeto. Os valores são fornecidos na ordem dos componentes do record;
  • linha 120: [Doctor::new] é uma referência a construtor: uma função sem parâmetros que retorna um [new Doctor()]. Ela tem o tipo esperado [Supplier<Doctor>]. Não é chamada aqui; será chamada a cada vez que um médico for criado;
  • linha 124: [appointmentRepository::countByDoctor] é uma referência a método: o método [countByDoctor] do objeto [appointmentRepository], que recebe um [int] e retorna um [long], ou seja, um valor do tipo [IntToLongFunction]. A exclusão de um médico será recusada enquanto ele tiver consultas;
  • linha 129: da mesma forma, [slotRepository::deleteByDoctor] (um [int], sem resultado) é um [IntConsumer]: os horários de um médico serão excluídos antes da exclusão do médico;
  • Linhas 131–142: o descritor de cliente. [Java] não tem parâmetros nomeados nem opcionais: os dois componentes desnecessários ([countAppointments] e [hasAppointmentsKey]) recebem [null] (linhas 140–141). A exclusão de um cliente nunca é, portanto, recusada, e suas consultas (passadas e futuras) são excluídas antes do próprio cliente; caso contrário, a chave estrangeira [appointments.client_id] impediria a exclusão.

11.12.5.2. Operações de leitura e a agenda

    // =======================================================================
    // leituras, fora de qualquer transação (cada consulta DAO é executada isoladamente,
    // com um EntityManager aberto durante a chamada)
    // =======================================================================

    @Override
    public List<Client> getAllClients() {
        return clientRepository.findAllByOrderByLastNameAscFirstNameAsc();
    }

    @Override
    public List<Doctor> getAllDoctors() {
        return doctorRepository.findAllByOrderByLastNameAscFirstNameAsc();
    }

    @Override
    public List<Slot> getAllSlots(int doctorId) {
        return slotRepository.findByDoctorIdOrderByStartHourAscStartMinuteAsc(doctorId);
    }

    @Override
    public List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day) {
        return appointmentRepository.doctorDayAppointments(doctorId, day);
    }

    @Override
    public Optional<Client> getClientById(int id) {
        return clientRepository.findWithUserById(id);
    }

    @Override
    public Optional<Doctor> getDoctorById(int id) {
        return doctorRepository.findWithUserById(id);
    }

    @Override
    public Optional<Appointment> getAppointmentById(int id) {
        return appointmentRepository.read(id);
    }

    @Override
    public Optional<Slot> getSlotById(int id) {
        return slotRepository.findWithDoctorById(id);
    }

    @Override
    public Optional<Client> getClientByUserId(int userId) {
        return clientRepository.findByUserId(userId);
    }

    @Override
    public List<Appointment> getClientUpcomingAppointments(int clientId) {
        return appointmentRepository.clientUpcomingAppointments(clientId, Dates.today());
    }

    // mesmo algoritmo do servidor JSON (e do projeto Spring original)
    @Override
    public Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day) {
        Optional<Doctor> doctor = getDoctorById(doctorId);
        if (doctor.isEmpty()) {
            return Optional.empty();
        }
        List<Slot> timeSlots = getAllSlots(doctorId);
        // nº do horário -> consulta marcada nesse horário
        Map<Integer, Appointment> bookings = getDoctorDayAppointments(doctorId, day).stream()
                .collect(Collectors.toMap(Appointment::getSlotId, Function.identity()));
        List<DoctorDaySlot> doctorDaySlots = timeSlots.stream()
                .map(slot -> new DoctorDaySlot(slot, bookings.get(slot.getId())))
                .toList();
        return Optional.of(new DoctorDaySchedule(doctor.get(), day, doctorDaySlots));
    }
  • Linhas 6–54: as operações de leitura simplesmente delegam à camada DAO, traduzindo os nomes dos métodos dos repositórios (muitas vezes impostos pelo [Spring Data JPA]) em nomes de negócio. [@Override] indica um método que implementa um método da interface: o compilador verifica se ele realmente existe em [Business]. Esses métodos não iniciam uma transação: cada consulta é executada de forma independente, com um [EntityManager] criado durante a chamada (veja a seção “JPA, Hibernate e Spring Data”). Cada um carrega os relacionamentos exigidos pelas páginas (a conta de uma pessoa, o médico de um horário, o cliente e o horário de uma consulta): as entidades retornadas estão desanexadas, e os controllers e as views podem ler esses relacionamentos com segurança;
  • linha 53: as próximas consultas de um paciente: a camada de negócio fornece a data atual ao repositório;
  • linhas 58–71: cálculo da agenda de um médico para um determinado dia. Um médico desconhecido retorna um [Optional] vazio ([Optional.empty()]); caso contrário, são recuperados os horários do médico e as consultas do dia. A agenda realiza três leituras sucessivas, independentes entre si: isso é aceitável para uma página exibida, que o usuário recarregará se necessário;
  • linhas 65–66: as consultas do dia são armazenadas em um dicionário ([Map]) cuja chave é o identificador do horário. [stream()] converte a lista em um stream: uma sequência de elementos processados por meio de operações encadeadas. [collect(Collectors.toMap(...))] armazena os elementos do stream em um dicionário: a chave de cada consulta é calculada por [Appointment::getSlotId] (uma referência a método, aplicada a cada consulta), e o valor por [Function.identity()], a função que retorna seu argumento: a própria consulta. [toMap] falharia se duas chaves fossem iguais, mas isso não pode acontecer: a restrição [unq1_appointments] impede que duas consultas sejam marcadas no mesmo horário no mesmo dia. O dicionário evita ter de percorrer toda a lista de consultas para cada horário;
  • linhas 67–69: cada horário é associado à sua consulta, ou a [null]: [get] retorna [null] quando a chave está ausente, isto é, quando o horário está livre. [map] transforma cada elemento do stream por meio da lambda [slot -> new DoctorDaySlot(...)]: uma função anônima cujo parâmetro [slot] é escrito à esquerda da seta e o resultado à direita. [toList()] coleta o resultado em uma lista somente leitura. A ordem cronológica dos horários, conforme especificada pela consulta, é preservada;
  • linha 70: a agenda, em um [Optional] preenchido ([Optional.of]); [doctor.get()] extrai o médico de seu [Optional], que sabemos aqui não estar vazio. O resultado é um objeto [DoctorDaySchedule] do record [domain], que a view da agenda exibirá.

11.12.5.3. Marcação de uma consulta

    // =======================================================================
    // consultas
    // =======================================================================

    // -----------------------------------------------------------------------
    // marcação de uma consulta, em uma transação:
    //   1. nenhuma consulta no passado;
    //   2. BLOQUEAMOS a linha do paciente (SELECT ... FOR UPDATE): se o
    //      mesmo paciente marcar dois horários no mesmo instante (duas abas,
    //      clique duplo...), a segunda transação espera o fim da
    //      primeira - e então vê a consulta que ela acabou de criar;
    //   3. uma única consulta futura por paciente;
    //   4. por fim, a inserção. Se o horário acabou de ser tomado por OUTRO
    //      paciente, é a restrição SQL unq1_appointments (day, slot_id) que
    //      recusa a inserção - traduzida em BusinessException por [transaction].
    // -----------------------------------------------------------------------
    @Override
    public Appointment addAppointment(LocalDate day, Slot slot, Client client) {
        return transaction(() -> {
            LocalDate today = Dates.today();
            if (day.isBefore(today)) {
                throw new BusinessException("ERRORS.PAST_DATE");
            }
            int patientId = clientRepository.lock(client.getId())
                    .orElseThrow(() -> new BusinessException("ERRORS.PATIENT_NOT_FOUND"));
            if (appointmentRepository.countByClientIdAndDayGreaterThanEqual(patientId, today) > 0) {
                throw new BusinessException("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
            }
            // getReferenceById: uma "referência" ao horário e ao paciente,
            // sem lê-los novamente do banco de dados - conhecer seu id basta para
            // escrever as chaves estrangeiras
            Slot slotRef = slotRepository.getReferenceById(slot.getId());
            Client patientRef = clientRepository.getReferenceById(patientId);
            return appointmentRepository.save(new Appointment(day, slotRef, patientRef));
        });
    }

    @Override
    public void deleteAppointment(Appointment appointment) {
        transaction(() -> {
            appointmentRepository.remove(appointment.getId());
            return null;
        });
    }
  • linhas 19 e 35: toda a marcação ocorre dentro de uma transação: o método passa a [transaction] (veja o último trecho) uma lambda sem parâmetros, [() -> { ... }], que executa a tarefa e retorna a consulta criada. Uma lambda pode usar os parâmetros do método que a contém ([day], [slot], [client]), desde que nunca sejam modificados;
  • Linhas 21–23: nenhuma consulta no passado. Essa regra é aplicada aqui independentemente do papel da pessoa que faz a reserva (ADMIN, DOCTOR ou o paciente), mesmo que a camada web já tenha ocultado os botões “Book” para datas passadas: uma requisição pode ser criada manualmente;
  • linhas 24–25: a linha do paciente é bloqueada por [SELECT ... FOR UPDATE] (veja [ClientRepository]). Trata-se de um bloqueio pessimista: ele é adquirido antes de qualquer trabalho começar, supondo um conflito potencial, e permanece até o fim da transação. Sem ele, duas reservas para o mesmo paciente enviadas ao mesmo tempo (duas abas, um clique duplo) poderiam passar ambas no teste seguinte antes que qualquer uma tenha gravado sua consulta no disco. Com o bloqueio, a segunda transação espera a primeira terminar e então vê a consulta que ela criou. Um paciente que não é encontrado (excluído nesse meio-tempo) é rejeitado: [orElseThrow] retorna o conteúdo do [Optional] ou lança a exceção gerada pela lambda se ele estiver vazio;
  • linhas 26–28: apenas uma consulta futura por paciente;
  • Linhas 32–33: [getReferenceById] retorna uma referência a uma entidade — um proxy — que contém apenas o identificador, sem ler a linha do banco de dados. Para gravar as chaves estrangeiras da linha de [appointments], basta conhecer os identificadores do horário e do paciente; não é necessário lê-los novamente. Não usamos diretamente os objetos [slot] e [client] recebidos como parâmetros: eles vêm da camada web, estão desanexados e não fazem parte do contexto de persistência desta transação;
  • Linha 34: a inserção. [save] grava a nova consulta (chave [IDENTITY]: [INSERT] é emitido imediatamente) e a retorna. Se outro paciente acabou de reservar o mesmo horário, o bloqueio não o impediu (o bloqueio se aplica ao registro do paciente): é a restrição de unicidade do banco de dados [unq1_appointments (day, slot_id)] que rejeita a inserção, e [transaction] traduz o erro em [BusinessException] com a chave [ERRORS.SLOT_ALREADY_BOOKED];
  • Linhas 39–44: cancelamento de uma consulta, sem regras específicas. O método [remove] do repositório é uma consulta [@Modifying]: ela exige uma transação que aceite escritas, daí a chamada a [transaction]. A lambda deve retornar um valor: ela retorna [null], que ninguém usa.

Aqui estão os comandos SQL enviados durante uma reserva, conforme registrados no console. O primeiro lê o horário e seu médico ([getSlotById], chamado pelo controller antes de [addAppointment]); os três seguintes são os da transação: o bloqueio, a contagem e a inserção. Graças a [getReferenceById], nem o horário nem o cliente são lidos novamente:

1
2
3
4
Hibernate: select s1_0.id,d1_0.id,d1_0.first_name,d1_0.last_name,d1_0.title,d1_0.`user`,d1_0.version,s1_0.doctor_id,s1_0.end_hour,s1_0.end_minute,s1_0.start_hour,s1_0.start_minute,s1_0.version from slots s1_0 left join doctors d1_0 on d1_0.id=s1_0.doctor_id where s1_0.id=?
Hibernate: select id from clients where id = ? for update
Hibernate: select count(a1_0.id) from appointments a1_0 where a1_0.client_id=? and a1_0.day>=?
Hibernate: insert into appointments (client_id,day,slot_id,version) values (?,?,?,?)

[INSERT] também grava na coluna [version]: [Hibernate] atribui a versão 0 a qualquer nova entidade.

11.12.5.4. Gerenciamento de médicos e clientes

    // =======================================================================
    // médicos e clientes - os métodos públicos delegam aos métodos
    // privados comuns, com o descritor correto
    // =======================================================================

    @Override
    public Doctor addDoctor(PersonData data) {
        return addPerson(doctorDescriptor, data);
    }

    @Override
    public Doctor editDoctor(int id, PersonData data) {
        return editPerson(doctorDescriptor, id, data);
    }

    @Override
    public void deleteDoctor(int id) {
        deletePerson(doctorDescriptor, id);
    }

    @Override
    public Client addClient(PersonData data) {
        return addPerson(clientDescriptor, data);
    }

    @Override
    public Client editClient(int id, PersonData data) {
        return editPerson(clientDescriptor, id, data);
    }

    // o cliente, sua conta E todas as suas consultas (ADMIN, ou o próprio paciente
    // em "Gerenciar minha conta": mesmo método, mesma regra)
    @Override
    public void deleteClient(int id) {
        deletePerson(clientDescriptor, id);
    }

    // -----------------------------------------------------------------------
    // criação: primeiro a conta de usuário (a pessoa a referencia),
    // depois a pessoa - tudo em UMA transação.
    // -----------------------------------------------------------------------
    private <T extends Person> T addPerson(Descriptor<T> d, PersonData data) {
        String lastName = data.lastName().trim().toUpperCase(Locale.ROOT);
        String firstName = data.firstName().trim();
        // as regras do banco de dados dbrdvmedecins2: login = sobrenome em minúsculas,
        // senha = login - a menos que o ADMIN tenha digitado outros
        String login = (empty(data.login()) ? lastName : data.login()).toLowerCase(Locale.ROOT);
        String password = empty(data.password()) ? login : data.password();

        return transaction(() -> {
            checkPersonUnique(d, firstName, lastName, null);
            checkLoginFree(login);

            User user = new User();
            user.setLogin(login);
            user.setPassword(hasher.encode(password));
            user.setName(firstName + " " + lastName);
            user.setRole(d.role());
            userRepository.save(user);

            T person = d.factory().get();
            person.setTitle(data.title());
            person.setLastName(lastName);
            person.setFirstName(firstName);
            person.setUser(user);
            return d.dao().save(person);
        });
    }

    // -----------------------------------------------------------------------
    // edição: a pessoa E sua conta (o nome exibido "firstName LASTNAME"
    // deve acompanhar; o login e a senha mudam somente se tiverem sido
    // digitados).
    // -----------------------------------------------------------------------
    private <T extends Person> T editPerson(Descriptor<T> d, int id, PersonData data) {
        return transaction(() -> {
            T person = d.dao().findWithUserById(id).orElseThrow(() -> new BusinessException(d.notFoundKey()));

            // bloqueio otimista: se a versão no banco de dados não for mais a do
            // formulário, alguém editou este registro nesse meio-tempo - recusamos
            // em vez de sobrescrever silenciosamente suas alterações.
            // (Se a edição concorrente ocorrer DEPOIS desta leitura, é
            // a cláusula "WHERE version = ..." do UPDATE que a detecta.)
            if (data.version() != null && !data.version().equals(person.getVersion())) {
                throw new BusinessException("ERRORS.CONCURRENT_UPDATE");
            }

            String lastName = data.lastName().trim().toUpperCase(Locale.ROOT);
            String firstName = data.firstName().trim();
            checkPersonUnique(d, firstName, lastName, id);

            // apenas modificamos os objetos: a entidade lida na
            // transação é "gerenciada" pelo JPA, que enviará ele mesmo os UPDATEs
            // necessários no COMMIT (não é preciso chamar save)
            person.setTitle(data.title());
            person.setLastName(lastName);
            person.setFirstName(firstName);

            User user = person.getUser();
            user.setName(firstName + " " + lastName);
            if (!empty(data.login()) && !data.login().toLowerCase(Locale.ROOT).equals(user.getLogin())) {
                String login = data.login().toLowerCase(Locale.ROOT);
                checkLoginFree(login);
                user.setLogin(login);
            }
            if (!empty(data.password())) {
                user.setPassword(hasher.encode(data.password()));
            }
            return person;
        });
    }

    // -----------------------------------------------------------------------
    // exclusão, em UMA transação, na ordem imposta pelas chaves
    // estrangeiras:
    //   1. possível recusa se restarem consultas (médico);
    //   2. o que referencia a pessoa (horários de um médico, consultas
    //      de um cliente);
    //   3. a pessoa (ela referencia sua conta);
    //   4. sua conta.
    // -----------------------------------------------------------------------
    private <T extends Person> void deletePerson(Descriptor<T> d, int id) {
        transaction(() -> {
            T person = d.dao().findById(id).orElseThrow(() -> new BusinessException(d.notFoundKey()));
            if (d.countAppointments() != null && d.countAppointments().applyAsLong(id) > 0) {
                throw new BusinessException(d.hasAppointmentsKey());
            }
            if (d.beforeDelete() != null) {
                d.beforeDelete().accept(id);
            }
            d.dao().remove(id);
            userRepository.remove(person.getUserId());
            return null; // [transaction] espera um resultado: não precisamos de um aqui
        });
    }

    // recusa nome e sobrenome já utilizados por OUTRA pessoa do mesmo tipo
    // (currentId: a pessoa sendo editada, que obviamente tem o
    // direito de manter seu próprio nome e sobrenome; null para uma criação)
    private <T extends Person> void checkPersonUnique(Descriptor<T> d, String firstName, String lastName,
            Integer currentId) {
        Optional<T> namesake = d.dao().findFirstByFirstNameAndLastName(firstName, lastName);
        if (namesake.isPresent() && !Objects.equals(namesake.get().getId(), currentId)) {
            throw new BusinessException(d.alreadyExistsKey());
        }
    }

    private void checkLoginFree(String login) {
        if (userRepository.findByLogin(login).isPresent()) {
            throw new BusinessException("ERRORS.LOGIN_TAKEN");
        }
    }

    private static boolean empty(String text) {
        return text == null || text.isEmpty();
    }
  • linhas 6–36: os seis métodos públicos delegam aos três métodos genéricos privados, usando o descritor correto. O compilador infere [T] a partir do descritor: [Doctor] para [doctorDescriptor], [Client] para [clientDescriptor];
  • linha 42: [<T extends Person>], escrito antes do tipo de retorno, faz de [addPerson] um método genérico: ele tem seu próprio parâmetro do tipo [T], que deve ser [Person] ou uma subclasse;
  • Linhas 43–48: preparação dos dados, fora da transação. [trim()] remove os espaços iniciais e finais da string; o nome é capitalizado. [Locale.ROOT] exige uma conversão independente do idioma do servidor (em turco, por exemplo, a versão minúscula de [I] não é [i]). Por padrão, o nome de usuário é igual ao nome, e está sempre em minúsculas; por padrão, a senha é igual ao nome de usuário: essas são as regras de conta do script SQL. [a ? b : c] é o operador condicional: [b] se [a] for verdadeiro, [c] caso contrário;
  • linhas 51–52: na transação, as duas regras de unicidade: nenhum nome duplicado, login livre. Elas são verificadas antes da gravação no banco de dados para exibir uma mensagem clara (veja o Exemplo 28);
  • linhas 54–59: a conta de usuário é criada primeiro, pois a pessoa a referencia (chave estrangeira). A senha nunca é armazenada em texto simples: [hasher.encode] calcula seu hash, [bcrypt]. [save] envia imediatamente o [INSERT] (chave [IDENTITY]): após essa chamada, [user] tem um identificador e passa a ser uma entidade gerenciada;
  • Linhas 61–66: depois, a pessoa. [d.factory().get()] refere-se à referência de fábrica do descritor: [new Doctor()] ou [new Client()]. [setUser(user)] vincula a pessoa à sua conta: no [INSERT] da pessoa, [Hibernate] gravará o ID da conta na coluna [user]. Se essa segunda operação de escrita falhar, a transação desfaz também a primeira: uma conta nunca pode existir sem uma pessoa;
  • linhas 75–111: modificação da pessoa e de sua conta em uma única transação;
  • linha 77: a pessoa e sua conta ([findWithUserById]), ou uma [BusinessException] com a chave do descritor se ela não existir;
  • linhas 84–86: o bloqueio otimista (veja o Exemplo 28): o formulário carregou a versão do registro lido na sua exibição; se a versão no banco de dados for diferente, alguém modificou o registro nesse meio-tempo, e o sistema rejeita a atualização em vez de sobrescrever silenciosamente o trabalho dessa pessoa. Ao contrário do bloqueio pessimista usado nas reservas, nada é bloqueado: presumimos que os conflitos são raros e simplesmente os detectamos. As versões são [Integer], que são objetos: nós as comparamos com [equals], e não com [!=], que compararia as referências dos objetos. Se a modificação concorrente ocorrer após essa leitura, é a condição [WHERE version = ...] do [UPDATE] que a detectará (veja o último trecho);
  • linhas 88–90: o novo nome e sobrenome, e a verificação de homônimos. Ela transmite o identificador da pessoa: a pessoa evidentemente tem o direito de manter seu próprio nome e sobrenome;
  • linhas 95–97: o objeto lido é simplesmente modificado. Lido dentro da transação, ele é gerenciado pelo [EntityManager], que enviará por conta própria o [UPDATE] no momento do [COMMIT], comparando o objeto com o estado lido (veja a seção “JPA, Hibernate e Spring Data”): não há nenhum [save] a chamar. O [UPDATE] incrementará a versão e verificará a antiga;
  • linhas 99–108: a conta acompanha a pessoa. Ela foi carregada junto com a pessoa ([@EntityGraph]) e também é gerenciada: seu nome de exibição é recalculado; seu login só muda se tiver sido informado e for diferente do atual (caso em que deve estar disponível); sua senha só muda se tiver sido informada; e ela também é submetida a hash;
  • linha 109: a pessoa modificada é retornada; após o [COMMIT], ela fica desanexada, mas sua conta, que foi carregada, continua legível pelo controller;
  • linhas 122–135: exclusão, dentro de uma transação, na ordem ditada pelas chaves estrangeiras;
  • linha 124: [findById] é suficiente: a conta não é necessária, apenas seu identificador, fornecido pelo campo [userId] sem carregar a conta;
  • linhas 125–127: possível rejeição: um médico com consultas agendadas não pode ser excluído (seus pacientes perderiam as consultas sem serem avisados). [d.countAppointments().applyAsLong(id)] chama a função indicada no descritor, isto é, [appointmentRepository.countByDoctor(id)];
  • linhas 128–130: exclusão das referências à pessoa: os horários de um médico, as consultas de um cliente;
  • linhas 131–132: a pessoa, seguida de sua conta, que a pessoa referenciava;
  • linha 133: [transaction] espera uma função que retorne um resultado: [null] é retornado, e ninguém o usará;
  • linhas 140–146: um homônimo é rejeitado, a menos que se refira à pessoa que está sendo editada ([currentId], [null] em uma nova criação). [Objects.equals(a, b)] compara dois objetos e aceita [null]: [namesake.get().getId().equals(null)] também funcionaria, mas [Objects.equals] evita ter de determinar qual dos dois poderia ser [null];
  • linhas 148–152: um nome de usuário já utilizado — por um médico, um cliente ou o administrador — é rejeitado;
  • linhas 154–156: uma string ausente ([null]) ou vazia: é assim que se trata um campo opcional que não foi preenchido.

Observe que somente as operações de criação chamam [save]. Uma atualização simplesmente modifica entidades existentes, e uma exclusão é feita por meio de consultas [delete]: essa é a maneira padrão de trabalhar com [JPA].

11.12.5.5. Transações e restrições de unicidade

    // -----------------------------------------------------------------------
    // executa [work] em uma transação:
    //   transactions.execute(...) -> START TRANSACTION, depois o trabalho, depois
    //   COMMIT se tudo correu bem; se uma exceção for lançada
    //   (BusinessException inclusive), ROLLBACK: nada é gravado.
    //
    // As verificações de "login livre" e de "nome + sobrenome únicos" são feitas ANTES
    // da gravação, para dar uma mensagem clara. Mas dois ADMINs poderiam
    // salvar o mesmo login (ou o mesmo médico) no mesmo instante: neste
    // caso raro, é uma restrição SQL de unicidade que recusa a segunda
    // gravação - no momento em que o Hibernate envia as instruções SQL, muitas vezes no
    // COMMIT, portanto DEPOIS do fim do trabalho. É por isso que interceptamos as
    // exceções aqui, EM VOLTA da transação, para traduzi-las na mesma
    // BusinessException.
    // -----------------------------------------------------------------------
    private <R> R transaction(Supplier<R> work) {
        try {
            return transactions.execute(status -> work.get());
        } catch (BusinessException e) {
            throw e;
        } catch (RuntimeException e) {
            BusinessException businessError = translateDatabaseError(e);
            if (businessError != null) {
                throw businessError;
            }
            throw e; // uma anomalia real: deixamos que ela se propague
        }
    }

    // -----------------------------------------------------------------------
    // Erros do banco de dados -> BusinessException
    //
    // O Spring traduz as exceções do Hibernate e do driver JDBC em uma
    // hierarquia de exceções independente do banco de dados (DataAccessException):
    // - OptimisticLockingFailureException: o UPDATE "WHERE id = ... AND
    //   version = ..." não modificou nenhuma linha (bloqueio otimista);
    // - DataIntegrityViolationException: uma restrição do banco de dados recusou
    //   a escrita. Para uma restrição UNIQUE, a mensagem de erro do MySQL
    //   (a causa "mais específica" da exceção) cita o NOME da restrição:
    //     Duplicate entry 'marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
    //   (o MySQL 8 prefixa o nome com o da tabela, o MariaDB não). É por isso
    //   que o script SQL dá NOME a todas as suas restrições.
    // Qualquer outro erro é uma anomalia real: retornamos null (não traduzido).
    // -----------------------------------------------------------------------
    private static final Map<String, String> CONSTRAINT_MESSAGES = Map.of(
            "unq_users_login", "ERRORS.LOGIN_TAKEN",
            "unq_doctors_first_name_last_name", "ERRORS.DOCTOR_ALREADY_EXISTS",
            "unq_clients_first_name_last_name", "ERRORS.PATIENT_ALREADY_EXISTS",
            "unq1_appointments", "ERRORS.SLOT_ALREADY_BOOKED");

    private static final Pattern CONSTRAINT = Pattern.compile("for key '(?:[^'.]*\\.)?([^']+)'");

    private static BusinessException translateDatabaseError(RuntimeException e) {
        if (e instanceof OptimisticLockingFailureException) {
            return new BusinessException("ERRORS.CONCURRENT_UPDATE");
        }
        if (e instanceof DataIntegrityViolationException) {
            String message = String.valueOf(NestedExceptionUtils.getMostSpecificCause(e).getMessage());
            Matcher match = CONSTRAINT.matcher(message);
            if (match.find() && CONSTRAINT_MESSAGES.containsKey(match.group(1))) {
                return new BusinessException(CONSTRAINT_MESSAGES.get(match.group(1)));
            }
        }
        return null;
    }
}
  • Linha 16: todas as entradas passam por este método genérico: [R] é o tipo do resultado do processamento ([Appointment], [Doctor], [Client] ou [Object] quando a lambda retorna [null]), e [Supplier<R>] é o tipo de uma função sem parâmetros que retorna um [R];
  • Linha 18: [transactions.execute(...)] abre uma transação ([START TRANSACTION]), executa a lambda que recebe, depois confirma a transação ([COMMIT]) e retorna o resultado da lambda. Se a lambda lançar uma exceção não verificada — incluindo [BusinessException] — a transação é desfeita ([ROLLBACK]) e a exceção é relançada. A função lambda recebe o status da transação como parâmetro ([status]), o que lhe permitiria solicitar um rollback sem lançar uma exceção; no entanto, ela não usa isso — apenas chama [work.get()];
  • linhas 19–20: uma [BusinessException] (uma regra de negócio rejeitada) é repassada sem alteração ao controller. Este bloco deve preceder o seguinte: [BusinessException] é, ela própria, uma [RuntimeException], e o [Java] tenta os blocos [catch] em ordem;
  • linhas 21–26: qualquer outra exceção é tratada por [translateDatabaseError]: se for um erro conhecido do banco de dados, a [BusinessException] correspondente é lançada em seu lugar; caso contrário, trata-se de uma anomalia real, relançada como está, o que gerará uma página de erro 500;
  • Linhas 45–49: para cada restrição de unicidade nomeada no script SQL, sua chave de tradução. É por isso que o script SQL nomeia todas as suas restrições. [Map.of(k1, v1, k2, v2...)] cria um dicionário somente leitura; [static final] faz dele uma constante de classe, criada uma única vez;
  • linha 51: uma expressão regular, compilada uma única vez por [Pattern.compile]. Ela extrai o nome da restrição da mensagem de erro do banco de dados (veja abaixo);
  • linhas 53–65: a tradução de um erro do banco de dados em [BusinessException], ou em [null] se o erro não for reconhecido;
  • linhas 54–56: [UPDATE ... WHERE id = ... AND version = ...] não modificou nenhuma linha: alguém modificou o registro entre a leitura e a gravação (bloqueio otimista). [instanceof] verifica o tipo real de um objeto. A exceção recebida é uma [ObjectOptimisticLockingFailureException], filha de [OptimisticLockingFailureException];
  • linhas 57–63: uma restrição do banco de dados rejeitou a escrita;
  • linha 58: a exceção do [Spring] encapsula a exceção do [Hibernate], que por sua vez encapsula a exceção do driver [MySQL]: cada exceção mantém a anterior como sua causa ([getCause()]). [NestedExceptionUtils.getMostSpecificCause(e)] remonta à causa raiz, a do driver, cuja mensagem é a do [MySQL]. [String.valueOf] trata uma mensagem [null] (ele então retorna a string ["null"]);
  • linhas 59–61: o nome da restrição é procurado nessa mensagem e é traduzido se constar do dicionário. [find()] procura a expressão regular na mensagem; [group(1)] retorna o que o primeiro grupo entre parênteses capturou. Qualquer outro erro, incluindo a violação de uma restrição que não consta do dicionário, é retornado sem tradução: trata-se de uma anomalia real.

A mensagem de erro de uma restrição de unicidade violada especifica o nome da restrição. Eis a produzida pelo [MariaDB] quando o mesmo nome e sobrenome são informados duas vezes (a collation não distingue maiúsculas de minúsculas: [marie pelissier] é duplicata de [Marie PELISSIER]):

ERROR 1062 (23000) at line 1: Duplicate entry 'marie-pelissier' for key 'unq_doctors_first_name_last_name'

[MySQL] 8 escreve [for key 'doctors.unq_doctors_first_name_last_name'], com o nome da tabela como prefixo. A expressão regular [for key '(?:[^'.]*\.)?([^']+)'] aceita ambas as formas: [(?:[^'.]*\.)?] ignora um prefixo opcional terminado por ponto (um grupo [(?:...)] que não captura nada), e o grupo [([^']+)] captura o nome até o apóstrofo. Na string [Java], o ponto é escrito como [\\.]: a barra invertida é duplicada porque ela própria é um caractere de escape dentro de uma string [Java].

Resta explicar por que a aplicação usa [TransactionTemplate] em vez da anotação [@Transactional] do Exemplo 28. Há duas razões:

  • um erro no banco de dados nem sempre aparece no próprio trabalho. O [INSERT] de uma nova entidade é enviado imediatamente (chave [IDENTITY]): uma restrição de unicidade violada por uma criação lança uma exceção durante [save], dentro da lambda. Já o [UPDATE] de uma entidade modificada só é enviado no [COMMIT] (veja [editPerson]): só então o banco de dados informa um login já utilizado ou uma versão desatualizada. Com [@Transactional], o [COMMIT] ocorre depois que o método retorna, dentro do código do [Spring] que o envolve: o método não pode interceptar os erros que causa. O Exemplo 28 contornou esse problema chamando [saveAndFlush], que força o envio imediato dos comandos SQL. Com [transactions.execute(...)], [COMMIT] é executado dentro do método [transaction]: seu [try] trata todos os erros, quer ocorram durante o processamento ou durante o [COMMIT];
  • [@Transactional] funciona por meio de um proxy: o [Spring] envolve o bean em um objeto que abre a transação antes de chamar o método. Uma chamada de um método a outro dentro do mesmo objeto não passa por esse proxy: se colocada no método privado [addPerson], chamado por [addDoctor], a anotação não teria nenhum efeito. [TransactionTemplate] não tem essa limitação: trata-se de uma chamada de método comum.

Por fim, em caso de falha, não há nada a limpar: o contexto de persistência está vinculado à transação e desaparece com ela no [ROLLBACK]. Já a versão [ASP.NET Core] precisava limpar o rastreamento de alterações de seu [DbContext], que durava toda a requisição.

11.13. Autenticação

A pasta [auth] reúne, de forma mais completa, os exemplos 25 a 27: o token JWT em um cookie, os papéis, o CAPTCHA e os limites de tentativas. Ela inclui também um “passe” para a criação de uma conta de cliente. A configuração do [Spring Security] propriamente dita, que reúne esses componentes, fica junto com as outras classes de configuração no arquivo [config/SecurityConfig.java]: é por ela que começaremos. O controller [AuthController], tratado no fim desta seção, serve a página de login.

11.13.1. config/SecurityConfig.java

O arquivo é apresentado em dois trechos. O primeiro declara os beans de criptografia: a chave, a geração e a verificação de tokens e o hash de senhas.

// =========================================================================
// config/SecurityConfig.java
// -------------------------------------------------------------------------
// A configuração do Spring Security (veja o capítulo 8): quem pode acessar
// o quê, e como o usuário é reconhecido em cada requisição.
//
// O Spring Security é uma CADEIA DE FILTROS de servlet, colocada na frente do Spring
// MVC. Para cada requisição:
//   1. o filtro OAuth2 "resource server" procura um token JWT (aqui, no
//      cookie rdvmedecins_jwt), verifica sua assinatura e sua data de
//      expiração, e deduz dele o usuário (Authentication);
//   2. o filtro de autorização aplica as regras de acesso às URLs;
//   3. só então o Spring MVC chama a action, cujas anotações
//      @PreAuthorize (habilitada por @EnableMethodSecurity) verificam o papel.
// Dois casos de falha, duas respostas adequadas a uma aplicação HTML:
//   - nenhum usuário autenticado (sem token, token expirado ou falsificado)
//     -> redirecionamento para a página de login;
//   - papel insuficiente -> resposta 403, que o ErrorController transforma em página.
// =========================================================================
package rdvmedecins.config;

import java.nio.charset.StandardCharsets;

import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder.BCryptVersion;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher;

import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.web.Flash;
import rdvmedecins.web.FlashMessage;

@Configuration
@EnableMethodSecurity
public class SecurityConfig {

    // a chave que assina e verifica os tokens (algoritmo simétrico HMAC-SHA256)
    @Bean
    public SecretKey jwtKey(AuthProperties auth) {
        byte[] bytes = auth.jwtSecret().getBytes(StandardCharsets.UTF_8);
        if (bytes.length < 32) {
            // O HMAC-SHA256 exige uma chave de pelo menos 256 bits: dizemos isso
            // claramente na inicialização, e não no primeiro login
            throw new IllegalStateException(
                    "rdvmedecins.auth.jwt-secret must be at least 32 characters long (see application.properties).");
        }
        return new SecretKeySpec(bytes, "HmacSHA256");
    }

    // a construção dos tokens (veja auth/AuthService.java)
    @Bean
    public JwtEncoder jwtEncoder(SecretKey key) {
        return NimbusJwtEncoder.withSecretKey(key).algorithm(MacAlgorithm.HS256).build();
    }

    // a verificação dos tokens: assinatura e data de expiração
    @Bean
    public JwtDecoder jwtDecoder(SecretKey key) {
        return NimbusJwtDecoder.withSecretKey(key).macAlgorithm(MacAlgorithm.HS256).build();
    }

    // o hash das senhas: bcrypt, 10 rodadas, versão $2b$ - como
    // os hashes do script SQL
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(BCryptVersion.$2B, 10);
    }

Vamos comentar este código:

  • Linhas 4–18: o comentário de cabeçalho lembra o princípio visto no Capítulo 8: o [Spring Security] é uma cadeia de filtros servlet, executados antes que a requisição chegue ao [Spring MVC]. Um filtro identifica o usuário a partir do token, outro aplica as regras de acesso por URL, e depois a anotação [@PreAuthorize] em cada ação verifica o papel;
  • Linha 54: [@Configuration] transforma a classe em uma fonte de beans: cada um de seus métodos anotados com [@Bean] é chamado uma vez na inicialização, e o objeto que ele retorna se torna um bean singleton, que o [Spring] injeta onde for solicitado;
  • Linha 55: [@EnableMethodSecurity] ativa a validação das anotações [@PreAuthorize("hasRole('ADMIN')")] colocadas nos controllers (veja o Exemplo 26). Sem ela, essas anotações seriam ignoradas sem nenhuma mensagem de erro;
  • linhas 59–69: a chave secreta que assina e verifica os tokens (veja o Exemplo 25). O parâmetro [AuthProperties auth] é o record que fornece uma estrutura tipada para as propriedades [rdvmedecins.auth.*] de [application.properties] (veja “Configuração do projeto”): o [Spring] o fornece como qualquer outro bean. Uma novidade em relação ao Exemplo 25: uma chave curta demais é rejeitada. O algoritmo HMAC-SHA256 exige uma chave de 256 bits, ou 32 bytes; a biblioteca [Nimbus], que gera os tokens, só verificaria isso na geração do primeiro token, ou seja, na primeira conexão. A exceção lançada aqui, durante a criação do bean, impede, em vez disso, que a aplicação inicie, com uma mensagem que especifica exatamente o que precisa ser corrigido;
  • Linhas 72–81: geração de tokens ([JwtEncoder]) e verificação ([JwtDecoder]) com a mesma chave; o algoritmo é simétrico. O decodificador verifica a assinatura e a data de expiração (claim [exp]). Por padrão, ele permite uma tolerância de sessenta segundos para discrepâncias de relógio entre servidores: um token continua válido por um minuto após expirar;
  • linhas 85–88: hash de senhas com o algoritmo [bcrypt] (veja o Exemplo 25). Desta vez há dois parâmetros: o custo (10: o algoritmo realiza 2^10 ciclos de cálculo, o que torna muito custoso um ataque de força bruta com milhões de tentativas de senha) e a versão do algoritmo. As senhas do script SQL foram submetidas a hash por uma biblioteca que escreve hashes começando por [$2b$10$], enquanto [BCryptPasswordEncoder] escreve [$2a$] por padrão. Ambas as versões são verificadas sem dificuldade; impor a versão [$2B] (uma constante da enumeração [BCryptVersion]: o caractere [$] é permitido em um identificador [Java]) apenas faz com que as contas criadas pela aplicação tenham hashes da mesma forma que os do script.

O segundo trecho é a própria cadeia de filtros, com suas duas respostas de contingência.

    @Bean
    public SecurityFilterChain securityFilters(HttpSecurity http, Flash flash) throws Exception {
        AuthenticationEntryPoint toLogin = toLogin(flash);
        AccessDeniedHandler accessDenied = (request, response, exception) ->
                response.sendError(HttpServletResponse.SC_FORBIDDEN);
        http
                // 1. as regras de acesso às URLs, examinadas em ordem. As páginas
                // públicas: login, criação de conta, escolha do idioma,
                // arquivos estáticos, página de erro. Todas as outras exigem um
                // usuário autenticado; os papéis são verificados pelos
                // @PreAuthorize dos controllers.
                .authorizeHttpRequests(access -> access
                        .requestMatchers("/", "/login", "/register", "/register/**", "/language/**",
                                "/css/**", "/js/**", "/lib/**", "/error")
                        .permitAll()
                        .anyRequest().authenticated())
                // 2. autenticação por token JWT, lido do cookie
                .oauth2ResourceServer(jwt -> jwt
                        .bearerTokenResolver(AuthService::tokenOf)
                        .authenticationEntryPoint(toLogin)
                        .accessDeniedHandler(accessDenied)
                        .jwt(config -> config.jwtAuthenticationConverter(converter())))
                // 3. os dois casos de falha
                .exceptionHandling(errors -> errors
                        .authenticationEntryPoint(toLogin)
                        .accessDeniedHandler(accessDenied))
                // 4. logout (POST /logout): apaga o cookie do token,
                // depois vai para a página de login. Somente POST: um simples
                // link (GET), colocado em outro site, não pode desconectar
                // o usuário sem que ele saiba
                .logout(out -> out
                        .logoutRequestMatcher(PathPatternRequestMatcher.withDefaults().matcher(HttpMethod.POST, "/logout"))
                        .deleteCookies(AuthService.JWT_COOKIE)
                        .logoutSuccessUrl("/login"))
                // 5. o servidor é stateless: nunca há sessão HTTP
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                // 6. sem token anti-CSRF: os cookies SameSite=Lax já protegem
                // as requisições POST vindas de outros sites (veja AuthService)
                .csrf(csrf -> csrf.disable());
        return http.build();
    }

    // -----------------------------------------------------------------------
    // nenhum usuário autenticado -> página de login. Se havia um cookie
    // presente, seu token não é mais válido: a sessão expirou.
    // Então apagamos o cookie e avisamos o usuário com uma mensagem
    // flash (colocada fora do Spring MVC, daí o bean Flash).
    // -----------------------------------------------------------------------
    private static AuthenticationEntryPoint toLogin(Flash flash) {
        return (request, response, exception) -> {
            if (AuthService.tokenOf(request) != null) {
                AuthService.clearToken(response);
                flash.put(request, response, FlashMessage.error("ERRORS.SESSION_EXPIRED"), "/login");
            }
            response.sendRedirect("/login");
        };
    }

    // -----------------------------------------------------------------------
    // do token ao usuário autenticado: a claim [name] é o nome do usuário
    // (Authentication.getName()), a claim [role] é o seu papel. O Spring Security
    // escreve os papéis com o prefixo ROLE_: a claim role=ADMIN se torna
    // a autoridade ROLE_ADMIN, que hasRole('ADMIN') verifica.
    // -----------------------------------------------------------------------
    private static JwtAuthenticationConverter converter() {
        JwtGrantedAuthoritiesConverter roles = new JwtGrantedAuthoritiesConverter();
        roles.setAuthoritiesClaimName(ConnectedUser.ROLE);
        roles.setAuthorityPrefix("ROLE_");
        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(roles);
        converter.setPrincipalClaimName(ConnectedUser.NAME);
        return converter;
    }
}

Vamos analisar este código:

  • linha 2: o bean [SecurityFilterChain] descreve a cadeia de filtros. [HttpSecurity] é um objeto construtor fornecido pelo [Spring Security]: cada método chamado nele ([authorizeHttpRequests], [oauth2ResourceServer], [logout]...) configura um aspecto da segurança, e [build()] (linha 40) constrói a cadeia. Cada um recebe uma lambda (veja o Exemplo 25) que configura o aspecto em questão. O parâmetro [Flash flash] é um bean da aplicação (pasta [web]), usado para registrar uma mensagem flash a partir do [Spring MVC];
  • Linhas 4–5: a resposta a um papel insuficiente: [sendError(403)]. A lambda implementa a interface [AccessDeniedHandler], que tem apenas um método (uma interface funcional). [sendError] não gera uma página por si só: o servidor [Tomcat] encaminha a requisição para [/error], onde o [ErrorController] (veja “A camada web: os controllers”) gera a página de erro 403, como no Exemplo 26;
  • Linhas 12–16: as regras de acesso por URL, examinadas em ordem: a primeira que corresponde à URL é aplicada. A raiz, o login, a criação de conta, a seleção de idioma, os arquivos estáticos e a página de erro são públicos ([/**] refere-se a tudo o que estiver sob um dado caminho). Qualquer outra URL exige um usuário autenticado. Os papéis não são verificados aqui, mas em cada ação, por meio de [@PreAuthorize]: a regra fica, assim, escrita ao lado do código que protege. [/error] deve ser pública: caso contrário, a página de erro para um visitante que não fez login seria, ela própria, negada;
  • linhas 18–22: autenticação por token JWT, tratada pelo módulo “resource server” ([OAuth2] “resource server”) do [Spring Security], como no Exemplo 25. Por padrão, esse módulo procura o token no cabeçalho [Authorization: Bearer ...]; a linha 19 fornece a ele outro [BearerTokenResolver], que o lê do cookie [rdvmedecins_jwt]. [AuthService::tokenOf] é uma referência a método: a notação abreviada para a lambda [request -> AuthService.tokenOf(request)]. O método estático [tokenOf] (arquivo [auth/AuthService.java]) tem de fato exatamente a forma exigida pela interface funcional [BearerTokenResolver]: recebe a requisição e retorna o token, ou [null]. Linha 22: o conversor que cria o usuário autenticado a partir do token verificado (linhas 65–73);
  • Linhas 20 e 25: o mesmo ponto de entrada, [toLogin], é especificado duas vezes, porque há duas maneiras de não estar autenticado. Um token presente, mas inválido (expirado, forjado) é rejeitado pelo filtro do resource server, que chama seu próprio ponto de entrada (linha 20). Nenhum token: o filtro deixa a requisição anônima passar, e o filtro de autorização a rejeita chamando o ponto de entrada de [exceptionHandling] (linha 25). Da mesma forma, o tratador de papel insuficiente é especificado nos dois lugares (linhas 21 e 26). O tratador de [exceptionHandling] (linha 26) trata as rejeições de [@PreAuthorize]; a linha 21 é uma precaução para que as duas configurações permaneçam simétricas. Sem nenhum tratador, o resource server responderia com um erro 403 à sua maneira, com um cabeçalho [WWW-Authenticate] destinado a um cliente [JavaScript], e sem página de erro;
  • Linhas 31–34: o logout é tratado pelo próprio [Spring Security] ; nenhum controller tem uma ação chamada [/logout]. [deleteCookies] apaga o cookie do token, e depois o navegador é redirecionado para [/login]. A linha 32 aceita apenas o método POST: quando a proteção CSRF está desativada (linha 39), o [Spring Security] aceita [/logout] com qualquer método — inclusive GET — e uma simples imagem ([<img src="http://.../logout">]) colocada em outro site bastaria para desconectar o usuário. [PathPatternRequestMatcher] descreve uma requisição por seu método e caminho;
  • linha 36: [STATELESS]: o [Spring Security] nunca cria uma sessão HTTP (o cookie [JSESSIONID] dos exemplos 20 e 23) e não a usa para rastrear o usuário: o usuário é reconhecido a cada requisição com base em seu token. O servidor não armazena nada em memória entre as requisições;
  • linha 39: por padrão, o [Spring Security] protege os formulários POST contra o ataque CSRF (uma página armadilha em outro site que envia um formulário ao nosso site) exigindo que cada formulário inclua um campo oculto contendo um token aleatório. Não precisamos disso aqui, assim como no Exemplo 25: os cookies da aplicação são [SameSite=Lax], e o navegador não os anexa a um POST vindo de outro site; a requisição maliciosa chegaria, portanto, sem o token JWT — anônima — e seria rejeitada;
  • Linhas 49–57: o ponto de entrada, isto é, a resposta a uma requisição não autenticada: um redirecionamento para a página de login (veja o Exemplo 25). Novidade (linhas 51–54): se a requisição continha um cookie de token, significa que o usuário estava conectado, mas seu token não é mais válido (expirado ou forjado). Apagamos esse cookie agora inútil e registramos uma mensagem flash dizendo “sessão expirada”, que a página de login exibirá em vez de deixar o usuário sem saber por que foi parar ali. A mensagem é uma chave de tradução (veja o Exemplo 22). Estamos, neste momento, em um filtro do [Spring Security], anterior ao [Spring MVC]: o objeto [RedirectAttributes] do Exemplo 20 ainda não existe, daí o bean [Flash] (comentado com a pasta [web]);
  • Linhas 65–73: o conversor do Exemplo 26 recebe o token verificado e cria o objeto [Authentication], que representa o usuário que faz a requisição. A claim [role] fornece as autorizações, prefixadas por [ROLE_]: a claim [role=ADMIN] torna-se a autorização [ROLE_ADMIN], que é verificada por [hasRole('ADMIN')]. A claim [name] torna-se o nome do usuário ([Authentication.getName()]). Os nomes das claims são as constantes do record [ConnectedUser] (próximo arquivo).

Este é o equivalente, no [Spring], da configuração do tratador [JwtBearer] do [ASP.NET Core] e de seus “eventos”: [BearerTokenResolver] faz o papel do evento [OnMessageReceived], e [AuthenticationEntryPoint] faz o papel de [OnChallenge].

Vamos examinar essas respostas com o [curl], em requisições que não exigem login. Uma página protegida, solicitada sem cookie, redireciona para a página de login:

curl -i http://localhost:8081/schedule
1
2
3
HTTP/1.1 302
Location: http://localhost:8081/login
Content-Length: 0

Para prosseguir, precisamos de um token. Este é o token do paciente [martin]; ele foi gerado para esta finalidade usando a chave secreta de [application.properties], por um pequeno programa que realiza o cálculo HMAC-SHA256. Isso destaca a importância de manter essa chave secreta em segurança: quem a conhece pode gerar um token para qualquer pessoa. O leitor, porém, não precisa desse cálculo: basta fazer login pelo navegador e copiar o valor do cookie [rdvmedecins_jwt] nas ferramentas do desenvolvedor (F12). Em produção, ela é substituída por uma string aleatória longa (veja “Configuração do projeto”). Um token é composto por três partes codificadas em Base64, separadas por pontos: o cabeçalho, o conteúdo e a assinatura.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwibG9naW4iOiJtYXJ0aW4iLCJuYW1lIjoiSmVhbiBNQVJUSU4iLCJyb2xlIjoiVVNFUiIsImV4cCI6MTc5MDM2MjAzNiwiaWF0IjoxNzkwMzU0ODM2fQ.hA1rLedxez9s4xqNcNNjyni_kDI9h496EBk8Oj2apdQ

Depois de decodificadas, as duas primeiras partes são texto simples: o token é assinado, não criptografado.

{"alg":"HS256"}
{"sub":"5","login":"martin","name":"Jean MARTIN","role":"USER","exp":1790362036,"iat":1790354836}

Com este token, a raiz do site redireciona o paciente para sua página inicial, “Minha conta”:

curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1Ii...apdQ" http://localhost:8081/
1
2
3
HTTP/1.1 302
Location: http://localhost:8081/my-area
Content-Length: 0

(o token está truncado no comando). O acesso à seção de gerenciamento de médicos, restrita ao ADMIN, é negado: [@PreAuthorize] nega o acesso, o tratador [accessDenied] responde com [sendError(403)], e a página de erro é gerada pelo [ErrorController]:

curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1Ii...apdQ" http://localhost:8081/doctors
1
2
3
4
5
6
7
8
HTTP/1.1 403
Content-Type: text/html;charset=UTF-8

<!doctype html>
...
      <h1 class="display-4 text-danger">403</h1>
      <p class="lead">Your role does not allow you to access this page.</p>
...

O atacante tenta agora se passar por ADMIN: ele substitui ["role":"USER"] por ["role":"ADMIN"] no conteúdo do token, mantendo a assinatura. O conteúdo modificado não corresponde mais à assinatura: o token é rejeitado e tratado como uma sessão expirada:

curl -i -H "Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwibG9naW4iOiJtYXJ0aW4iLCJuYW1lIjoiSmVhbiBNQVJUSU4iLCJyb2xlIjoiQURNSU4iLCJleHAiOjE3OTAzNjIwMzYsImlhdCI6MTc5MDM1NDgzNn0.hA1rLedxez9s4xqNcNNjyni_kDI9h496EBk8Oj2apdQ" http://localhost:8081/doctors
1
2
3
4
5
HTTP/1.1 302
Set-Cookie: rdvmedecins_jwt=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: rdvmedecins_flash=eyJwYXRoIjoiL2xvZ2luIiwiZXhwaXJlcyI6MTc5MDM1NTA1OTIwNywiZmxhc2giOnsidHlwZSI6IkRBTkdFUiIsImtleSI6IkVSUk9SUy5TRVNTSU9OX0VYUElSRUQiLCJwYXJhbXMiOnt9fX0; Path=/; HttpOnly; SameSite=Lax
Location: http://localhost:8081/login
Content-Length: 0

O ponto de entrada [toLogin] executou as três ações esperadas: o cookie do token é apagado (o primeiro cabeçalho, [Set-Cookie], o redefine como vazio com tempo de vida zero), uma mensagem flash é armazenada no cookie [rdvmedecins_flash] (segundo cabeçalho, documentado no arquivo [web/CookieFlashMapManager.java]), e o navegador é redirecionado para [/login], onde a mensagem aparece na parte inferior da página:

Image

O mesmo processo se aplica a um token expirado, e até em uma página pública como [/login]: o filtro do resource server verifica qualquer token apresentado antes que as regras de acesso sejam examinadas.

Resta o logout. Em POST, ele apaga o cookie do token e redireciona para a página de login:

curl -i -X POST http://localhost:8081/logout
1
2
3
4
HTTP/1.1 302
Set-Cookie: rdvmedecins_jwt=; Expires=Thu, 01 Jan 1970 00:00:10 GMT; Path=/
Location: http://localhost:8081/login
Content-Length: 0

Em GET, a URL [/logout] é apenas uma página protegida como outra qualquer — e desconhecida, ainda por cima: sem token, a requisição é redirecionada para a página de login pelo ponto de entrada; com um token válido, retornaria uma página 404. Em nenhuma circunstância ela desconecta o usuário:

curl -i http://localhost:8081/logout
1
2
3
HTTP/1.1 302
Location: http://localhost:8081/login
Content-Length: 0

11.13.2. auth/ConnectedUser.java

// =========================================================================
// auth/ConnectedUser.java
// -------------------------------------------------------------------------
// O que o token JWT contém e como lê-lo de volta.
//
// No Spring Security, o usuário da requisição é um objeto
// Authentication, armazenado no SecurityContext da requisição. Com
// a autenticação por token JWT (veja config/SecurityConfig.java), é um
// JwtAuthenticationToken, que contém o token verificado: um objeto Jwt, cujas
// "claims" são os campos do token. Um controller
// o obtém por meio de um parâmetro @AuthenticationPrincipal Jwt token.
//
// As claims dos nossos tokens (veja AuthService.setToken):
//   sub   : o id da conta do usuário (convenção JWT: "subject")
//   login : o login
//   name  : o nome de exibição ("Marie PELISSIER"), para a barra de navegação
//   role  : ADMIN, DOCTOR ou USER
// =========================================================================
package rdvmedecins.auth;

import org.springframework.security.oauth2.jwt.Jwt;

import rdvmedecins.entities.Role;

// o usuário conectado, em forma tipada
public record ConnectedUser(int userId, String login, String name, Role role) {

    // os nomes das claims
    public static final String SUB = "sub";
    public static final String LOGIN = "login";
    public static final String NAME = "name";
    public static final String ROLE = "role";

    // o usuário descrito por um token já verificado; null se o token
    // estiver ausente (requisição não autenticada) ou malformado
    public static ConnectedUser of(Jwt token) {
        if (token == null) {
            return null;
        }
        try {
            return new ConnectedUser(
                    Integer.parseInt(token.getSubject()),
                    token.getClaimAsString(LOGIN),
                    token.getClaimAsString(NAME),
                    Role.valueOf(token.getClaimAsString(ROLE)));
        } catch (RuntimeException e) {
            // NumberFormatException, IllegalArgumentException, NullPointerException
            return null;
        }
    }

    public boolean isAdmin() {
        return role == Role.ADMIN;
    }

    public boolean isPatient() {
        return role == Role.USER;
    }
}

Vamos analisar este código:

  • Linhas 6–11: no [Spring Security], o usuário da requisição é um objeto [Authentication], armazenado no [SecurityContext] da requisição. Com os tokens JWT, ele é um [JwtAuthenticationToken], que contém o token verificado, um objeto [Jwt]. Uma ação o recebe por meio de um parâmetro anotado como [@AuthenticationPrincipal Jwt token] (veja o Exemplo 25);
  • linha 26: o usuário conectado em forma tipada: um identificador inteiro, um papel do tipo [Role] (a enumeração [ADMIN], [DOCTOR], [USER] da pasta [entities]), em vez de um token cujas claims são identificadas pelo nome. É um record (veja “O domínio: a agenda”): o [Java] gera para nós o construtor e os acessores [userId()], [login()], [name()] e [role()] ;
  • Linhas 29–32: os nomes das claims do token, agrupados em constantes: um erro de digitação em [ConnectedUser.NAME] é sinalizado pelo compilador, ao passo que um erro na string ["name"] só seria descoberto em tempo de execução. Um record pode conter campos static: eles pertencem à classe, não a cada objeto;
  • linhas 36–50: o método estático [of] cria o usuário a partir de um token já verificado (sua assinatura é válida), ou retorna [null]. [getSubject()] retorna a claim [sub], o ID da conta, escrito como texto; [Integer.parseInt] o converte em um inteiro. [Role.valueOf] retorna a constante da enumeração com o nome dado. Esses dois métodos lançam uma exceção se o texto for inválido (ou se for [null]): um token corretamente assinado, mas incompleto, retorna portanto [null], em vez de um erro 500;
  • linhas 52–58: dois métodos para views e controllers que evitam a comparação de papéis: [isAdmin()] e [isPatient()]. Uma view [Thymeleaf] escreve simplesmente [${user.isAdmin()}].

11.13.3. auth/AuthService.java

O arquivo é apresentado em dois trechos.

// =========================================================================
// auth/AuthService.java
// -------------------------------------------------------------------------
// A lógica de autenticação:
//   - validateUser() : verifica um par login / senha;
//   - setToken()     : constrói o token JWT de um usuário validado
//                      e o armazena em um cookie;
//   - clearToken()   : apaga esse cookie;
//   - currentUser()  : o usuário conectado da requisição atual.
//
// Por onde viaja o token JWT?
// Com um cliente JavaScript, era o código do cliente que guardava o token
// e o adicionava ele mesmo a cada requisição (cabeçalho "Authorization: Bearer
// ..."). Um navegador que exibe páginas HTML comuns não consegue
// fazer isso: para que ele apresente o token sozinho a cada requisição, ele
// deve armazená-lo em um COOKIE. As opções desse cookie importam para a
// segurança:
//   - HttpOnly : o JavaScript da página não consegue ler o cookie (um
//     script injetado não poderia, portanto, roubar o token);
//   - SameSite=Lax : o navegador NÃO envia o cookie com um POST vindo
//     de outro site. Como todas as ações que modificam dados são
//     POSTs, uma página armadilha em outro site não pode reservar nem
//     excluir nada se passando pelo usuário
//     (o chamado ataque CSRF);
//   - Secure : em produção (HTTPS), o cookie nunca trafega em texto claro;
//   - Max-Age : o cookie desaparece ao mesmo tempo em que o token expira.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Optional;

import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.JwsHeader;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.security.oauth2.jwt.JwtException;
import org.springframework.stereotype.Service;
import org.springframework.web.util.WebUtils;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.config.AuthProperties;
import rdvmedecins.entities.User;
import rdvmedecins.repositories.UserRepository;

@Service
public class AuthService {

    // o nome do cookie que carrega o token
    public static final String JWT_COOKIE = "rdvmedecins_jwt";

    private final UserRepository userRepository;
    private final PasswordEncoder hasher;
    private final JwtEncoder encoder;
    private final JwtDecoder decoder;
    private final AuthProperties auth;

    public AuthService(UserRepository userRepository, PasswordEncoder hasher, JwtEncoder encoder,
            JwtDecoder decoder, AuthProperties auth) {
        this.userRepository = userRepository;
        this.hasher = hasher;
        this.encoder = encoder;
        this.decoder = decoder;
        this.auth = auth;
    }

    // Optional.empty() se o login não existir ou se a senha estiver errada.
    // matches calcula o hash da senha digitada com o "salt" contido no hash
    // armazenado e depois compara os dois resultados.
    public Optional<User> validateUser(String login, String password) {
        return userRepository.findByLogin(login).filter(user -> hasher.matches(password, user.getPassword()));
    }

Vamos comentar este código:

  • linhas 11–26: o comentário explica por que o token é enviado em um cookie e o papel de cada uma de suas opções (veja o Exemplo 25). Um navegador que segue links e envia formulários não sabe adicionar um cabeçalho [Authorization] às suas requisições; em compensação, ele reenvia automaticamente os cookies que recebeu;
  • linha 57: [@Service] faz da classe um bean singleton (veja o Exemplo 06), assim como [@Component]: as duas anotações são equivalentes, com [@Service] indicando apenas que se trata de um serviço;
  • linha 61: o nome do cookie que carrega o token;
  • linhas 63–76: o serviço recebe o DAO contendo as contas de usuário ([UserRepository], veja “A camada DAO”), o codificador [bcrypt], o codificador e o decodificador de tokens (os beans de [SecurityConfig]) e as propriedades de autenticação. Os campos são [final]: não mudam após a construção;
  • linhas 81–83: a conta, se o nome de usuário e a senha estiverem corretos (veja o Exemplo 25). [findByLogin] retorna um [Optional<User>], uma caixa que contém uma conta ou está vazia (veja “A camada DAO”); [filter] mantém a conta somente se a condição for verdadeira; caso contrário, retorna uma caixa vazia. A condição, [hasher.matches(...)], calcula o hash da senha digitada com o “sal” contido no hash armazenado e compara os dois resultados: a senha em si nunca é armazenada.
    // -----------------------------------------------------------------------
    // constrói o token JWT de [user] e o coloca em um cookie.
    // O token é ASSINADO (HMAC-SHA256) com a chave secreta: o navegador
    // pode lê-lo (ele não é criptografado), mas não modificá-lo - qualquer
    // modificação invalidaria a assinatura.
    // -----------------------------------------------------------------------
    public void setToken(HttpServletResponse response, User user) {
        Instant now = Instant.now();
        JwtClaimsSet claims = JwtClaimsSet.builder()
                .subject(String.valueOf(user.getId()))
                .claim(ConnectedUser.LOGIN, user.getLogin())
                .claim(ConnectedUser.NAME, user.getName())
                .claim(ConnectedUser.ROLE, user.getRole().name())
                .issuedAt(now)
                .expiresAt(now.plusSeconds(auth.jwtExpiresInSeconds()))
                .build();
        String token = encoder.encode(JwtEncoderParameters.from(JwsHeader.with(MacAlgorithm.HS256).build(), claims))
                .getTokenValue();
        ResponseCookie cookie = ResponseCookie.from(JWT_COOKIE, token)
                .httpOnly(true)
                .sameSite("Lax")
                .secure(auth.cookieSecure())
                .maxAge(Duration.ofSeconds(auth.jwtExpiresInSeconds()))
                .path("/")
                .build();
        response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
    }

    // apaga o cookie: nós o definimos de novo, vazio, com tempo de vida zero
    public static void clearToken(HttpServletResponse response) {
        response.addHeader(HttpHeaders.SET_COOKIE, ResponseCookie.from(JWT_COOKIE, "").path("/").maxAge(0).build().toString());
    }

    // o token presente na requisição, válido ou não
    public static String tokenOf(HttpServletRequest request) {
        Cookie cookie = WebUtils.getCookie(request, JWT_COOKIE);
        return cookie == null ? null : cookie.getValue();
    }

    // -----------------------------------------------------------------------
    // o usuário conectado, ou null.
    // Normalmente, o Spring Security já o estabeleceu (SecurityContextHolder).
    // Mas uma página de erro é construída por uma SEGUNDA requisição interna,
    // enviada pelo servidor ao endereço /error, que não passa novamente
    // pela autenticação: então lemos nós mesmos o token do cookie, para
    // que a barra de navegação da página de erro mostre o usuário.
    // -----------------------------------------------------------------------
    public ConnectedUser currentUser(HttpServletRequest request) {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication != null && authentication.getPrincipal() instanceof Jwt token) {
            return ConnectedUser.of(token);
        }
        String token = tokenOf(request);
        if (token == null) {
            return null;
        }
        try {
            return ConnectedUser.of(decoder.decode(token));
        } catch (JwtException e) {
            return null; // token expirado ou falsificado
        }
    }
}

Vamos comentar este código:

  • Linhas 8–19: o token, gerado como no Exemplo 25. Ele contém o ID da conta (claim [sub]), o login, o nome exibido na barra de navegação, o papel, a data de emissão ([iat], “issued at”) e a data de expiração ([exp]), que é duas horas depois por padrão. [JwtClaimsSet.builder()] retorna um objeto construtor: um método é chamado por claim, seguido de [build()]. Linha 18: o cabeçalho do token especifica o algoritmo HS256 (HMAC-SHA256), e o codificador assina todo o token com a chave secreta;
  • Linhas 20–27: o cookie, com as opções do Exemplo 25 ([HttpOnly], [SameSite=Lax]) e mais duas: [Secure], ativada em produção (site servido em [HTTPS]), impede que o navegador envie o cookie por uma conexão não criptografada; [Path=/] garante que ele seja incluído em todas as requisições ao site. [Max-Age] apaga o cookie quando o token expira. [ResponseCookie] gera o texto do cabeçalho [Set-Cookie], que é adicionado à resposta pela linha 27;
  • linhas 31–33: apagar um cookie consiste em defini-lo novamente, vazio, com tempo de vida zero; o navegador o exclui imediatamente. Para que o navegador reconheça o cookie a ser apagado, o caminho ([Path]) deve ser o mesmo usado quando ele foi definido. O método é estático: ele não depende de nenhum campo do objeto. É usado pelo ponto de entrada de [SecurityConfig] e pelo tratador de exceções [HtmlExceptionHandler] (pasta [web]), que não dispõem de uma instância de [AuthService];
  • linhas 36–39: o token presente na requisição, sem verificá-lo. [WebUtils.getCookie] procura um cookie pelo nome entre os da requisição. Este é o método que [SecurityConfig] fornece como [BearerTokenResolver];
  • linhas 49–63: o usuário conectado, ou [null]. No caso típico (linhas 50–53), o [Spring Security] já o estabeleceu: [SecurityContextHolder.getContext().getAuthentication()] retorna o objeto [Authentication] da requisição atual, cujo “principal” é o token verificado. [instanceof Jwt token] verifica o tipo do objeto e, se a verificação for bem-sucedida, o armazena na variável [token], já convertida para [Jwt]. O segundo caso (linhas 54–62) diz respeito à página de erro: quando uma requisição termina com um erro 403 ou 404, o servidor gera a página por meio de uma segunda requisição interna para [/error]. O filtro do resource server não processa essa requisição interna: o usuário não está autenticado para ela. Para que a barra de navegação da página de erro continue exibindo o usuário, verificamos nós mesmos o token do cookie, usando o decodificador de [SecurityConfig]; um token expirado ou forjado provoca uma [JwtException], e retornamos [null].

O método [currentUser] é chamado a cada página por [web/CommonModel.java], que define o usuário no modelo para todas as views.

11.13.4. auth/InvalidSessionException.java

// =========================================================================
// auth/InvalidSessionException.java
// -------------------------------------------------------------------------
// O token é válido, mas a conta que ele designa não existe mais: ela foi
// excluída desde o login (pelo próprio paciente em outra
// aba, ou pelo ADMIN). Tratamos esse caso como uma sessão expirada:
// web/HtmlExceptionHandler apaga o cookie e redireciona para a
// página de login.
// =========================================================================
package rdvmedecins.auth;

public class InvalidSessionException extends RuntimeException {

    public InvalidSessionException() {
        super("the account of the connected user no longer exists");
    }
}
  • Linhas 12–16: um token pode ser válido (corretamente assinado, não expirado) mesmo que a conta à qual se refere tenha sido excluída depois que o usuário fez login. As páginas do paciente detectam isso procurando o cliente associado à conta (método [connectedPatient] no arquivo [web/Utils.java]) e então lançam esta exceção; o tratador de exceções [HtmlExceptionHandler] (veja o Exemplo 24) a intercepta, apaga o cookie e redireciona para a página de login com a mensagem “sessão expirada”. A exceção deriva de [RuntimeException]: é uma exceção não verificada, que os métodos não precisam declarar com uma cláusula [throws]. O construtor repassa sua mensagem ao construtor da classe pai por meio de [super(...)].

11.13.5. auth/Captcha.java

// =========================================================================
// auth/Captcha.java
// -------------------------------------------------------------------------
// Um CAPTCHA: id, a colocar no campo oculto "captchaId" do formulário;
// svg, a imagem, a inserir tal qual na página.
// =========================================================================
package rdvmedecins.auth;

public record Captcha(String id, String svg) {
}
  • Linha 9: um CAPTCHA, tal como recebido pela página: o identificador, a ser colocado em um campo oculto do formulário, e a imagem [SVG], a ser inserida tal como está na página. Um único record é suficiente: o objeto é somente leitura. A resposta esperada não aparece aqui: ela nunca sai do servidor.

11.13.6. auth/CaptchaService.java

// =========================================================================
// auth/CaptchaService.java
// -------------------------------------------------------------------------
// Um CAPTCHA ("teste para distinguir um humano de um robô") feito pelo
// próprio servidor, sem nenhum serviço externo: alguns caracteres distorcidos,
// embaralhados por traços, em uma imagem SVG (veja CaptchaDrawing.java). Um
// humano os lê sem dificuldade; um robô que apenas envia
// formulários em loop não consegue.
//
// Como funciona:
//   1. generate() sorteia um texto aleatório, o transforma em imagem e armazena a
//      resposta correta NA MEMÓRIA DO SERVIDOR, sob um identificador aleatório;
//   2. a página exibe a imagem e coloca o identificador em um campo oculto do
//      formulário (a resposta em si nunca sai do servidor);
//   3. verify(id, input) compara a entrada com a resposta esperada e depois
//      ESQUECE esse CAPTCHA: cada imagem é usada uma única vez, um robô não pode
//      reutilizar uma resposta já encontrada.
//
// Bean SINGLETON (uma única instância para todo o servidor), usado por
// várias requisições EM PARALELO: daí o ConcurrentHashMap, um
// dicionário que várias threads podem ler e modificar ao mesmo tempo
// sem corrompê-lo.
//
// Limite aceito: a memória de um único processo. Com vários servidores
// atrás de um balanceador de carga, seria necessário um armazenamento compartilhado.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

import org.springframework.stereotype.Service;

@Service
public class CaptchaService {

    // tempo de validade de uma imagem: você tem 10 minutos para preencher o formulário
    private static final Duration LIFETIME = Duration.ofMinutes(10);

    // proteção de memória: acima disso, esquecemos todos os CAPTCHAs pendentes
    private static final int MAX_CAPTCHAS = 10_000;

    // a resposta esperada e sua data de expiração
    private record Expected(String text, Instant expires) {
    }

    // id -> resposta esperada
    private final Map<String, Expected> pending = new ConcurrentHashMap<>();

    public Captcha generate() {
        purge();
        String text = CaptchaDrawing.randomText(5); // 5 caracteres
        String id = UUID.randomUUID().toString(); // um identificador aleatório, impossível de adivinhar
        pending.put(id, new Expected(text, Instant.now().plus(LIFETIME)));
        return new Captcha(id, CaptchaDrawing.svg(text));
    }

    // true se [input] for a resposta certa para o CAPTCHA [id] (sem distinção
    // de maiúsculas e minúsculas). O CAPTCHA é consumido em todos os casos.
    // remove é ATÔMICO: se duas requisições apresentarem o mesmo CAPTCHA no mesmo
    // instante, só uma o remove - a outra falha.
    public boolean verify(String id, String input) {
        Expected expected = id == null ? null : pending.remove(id);
        return expected != null && input != null
                && expected.expires().isAfter(Instant.now())
                && expected.text().equalsIgnoreCase(input.trim());
    }

    private void purge() {
        Instant now = Instant.now();
        pending.entrySet().removeIf(e -> !e.getValue().expires().isAfter(now));
        if (pending.size() >= MAX_CAPTCHAS) {
            pending.clear();
        }
    }
}

O serviço é o mesmo do Exemplo 27, com dois acréscimos: um prazo de expiração e um limite. Vamos percorrer este código:

  • linha 37: um bean singleton — um único serviço para todo o servidor, ou seja, uma única lista de CAPTCHAs pendentes compartilhada por todas as requisições;
  • linhas 41–44: uma imagem é válida por dez minutos, e o número de CAPTCHAs pendentes é limitado. Cada vez que a página de login é exibida, um CAPTCHA é adicionado à memória; sem um limite, um bot que solicitasse essa página milhões de vezes sem nunca responder acabaria esgotando a memória do servidor. [10_000]: o caractere [_] separa os dígitos em grupos para facilitar a leitura;
  • linhas 47–48: a resposta esperada e sua data de expiração. O record é aninhado e privado: existe apenas para este serviço. [Instant] representa um instante específico no tempo, independente do fuso horário;
  • linha 51: identificador → resposta esperada. O serviço é um singleton, usado por requisições concorrentes, cada uma em sua própria thread de execução ([thread]): daí o [ConcurrentHashMap] (veja o Exemplo 27), um dicionário que várias [threads] podem ler e modificar ao mesmo tempo sem corrompê-lo. O campo é declarado com o tipo definido pela interface [Map]: o restante do código não depende da implementação escolhida;
  • linhas 53–59: limpeza, seguida de uma cadeia de texto de cinco caracteres gerada aleatoriamente, armazenada sob um identificador aleatório ([UUID.randomUUID()], 122 bits aleatórios, impossível de adivinhar) e desenhada por [CaptchaDrawing];
  • linhas 65–70: a verificação, idêntica à do Exemplo 27: o CAPTCHA é removido do dicionário em todos os casos ([remove] retorna o valor removido, ou [null]), depois verificamos que ele existia, que não expirou e que a entrada — sem espaços — está correta, independentemente de maiúsculas e minúsculas ([equalsIgnoreCase]). [remove] é atômico: se duas requisições apresentarem o mesmo CAPTCHA ao mesmo tempo, apenas uma o remove; a outra recebe [null]. Cada imagem é, portanto, usada uma única vez: um bot não pode reutilizar uma resposta encontrada anteriormente;
  • Linhas 72–78: limpeza. [removeIf] remove do dicionário as entradas para as quais a função lambda retorna [true] — neste caso, os CAPTCHAs expirados. Se o limite ainda for atingido (um ataque está em andamento), todos os CAPTCHAs pendentes são descartados: os usuários de boa-fé que estavam preenchendo o formulário naquele momento terão de digitar novamente uma nova imagem. Essa situação só ocorre em caso de ataque: esta solução simples é suficiente.

11.13.7. auth/CaptchaDrawing.java

A classe que desenha a imagem é a do Exemplo 27. Ela é apresentada em duas partes: a “fonte” dos caracteres, seguida do desenho.

// =========================================================================
// auth/CaptchaDrawing.java
// -------------------------------------------------------------------------
// O desenho da imagem SVG (150 x 50 pixels) de um CAPTCHA, tomado tal qual
// do exemplo 27. Um ponto importante: cada caractere é desenhado com
// TRAÇOS (<path>), nunca escrito como texto (<text>) - senão um robô
// só precisaria ler o código-fonte da imagem.
// =========================================================================
package rdvmedecins.auth;

import java.security.SecureRandom;
import java.util.LinkedHashMap;
import java.util.Locale;
import java.util.Map;

final class CaptchaDrawing {

    private static final int WIDTH = 150;
    private static final int HEIGHT = 50;

    // SecureRandom: um gerador de números aleatórios "criptográfico",
    // imprevisível (ao contrário de Random, cuja sequência poderia ser adivinhada)
    private static final SecureRandom RANDOM = new SecureRandom();

    // A "fonte": cada caractere é uma lista de traços, cada traço uma
    // sequência de pontos (x, y) em uma grade 4 x 6 (y para baixo).
    // Caracteres fáceis demais de confundir entre si: excluídos (0 O, 1 I L).
    private static final Map<Character, double[][]> FONT = new LinkedHashMap<>();

    static {
        FONT.put('A', new double[][] { { 0, 6, 2, 0, 4, 6 }, { 0.8, 3.8, 3.2, 3.8 } });
        FONT.put('B', new double[][] { { 0, 0, 0, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3 }, { 0, 0, 3, 0, 4, 1, 4, 2, 3, 3 } });
        FONT.put('C', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5 } });
        FONT.put('D', new double[][] { { 0, 0, 0, 6, 2.5, 6, 4, 4.5, 4, 1.5, 2.5, 0, 0, 0 } });
        FONT.put('E', new double[][] { { 4, 0, 0, 0, 0, 6, 4, 6 }, { 0, 3, 3, 3 } });
        FONT.put('F', new double[][] { { 4, 0, 0, 0, 0, 6 }, { 0, 3, 3, 3 } });
        FONT.put('G', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 3.5, 2.5, 3.5 } });
        FONT.put('H', new double[][] { { 0, 0, 0, 6 }, { 4, 0, 4, 6 }, { 0, 3, 4, 3 } });
        FONT.put('J', new double[][] { { 4, 0, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('K', new double[][] { { 0, 0, 0, 6 }, { 4, 0, 0, 3.5 }, { 1.3, 2.6, 4, 6 } });
        FONT.put('M', new double[][] { { 0, 6, 0, 0, 2, 3.5, 4, 0, 4, 6 } });
        FONT.put('N', new double[][] { { 0, 6, 0, 0, 4, 6, 4, 0 } });
        FONT.put('P', new double[][] { { 0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3 } });
        FONT.put('Q', new double[][] { { 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5, 0, 1, 1, 0 }, { 2.5, 4.5, 4, 6.3 } });
        FONT.put('R', new double[][] { { 0, 6, 0, 0, 3, 0, 4, 1, 4, 2, 3, 3, 0, 3 }, { 2, 3, 4, 6 } });
        FONT.put('S', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 2, 1, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('T', new double[][] { { 0, 0, 4, 0 }, { 2, 0, 2, 6 } });
        FONT.put('U', new double[][] { { 0, 0, 0, 5, 1, 6, 3, 6, 4, 5, 4, 0 } });
        FONT.put('V', new double[][] { { 0, 0, 2, 6, 4, 0 } });
        FONT.put('W', new double[][] { { 0, 0, 1, 6, 2, 2.5, 3, 6, 4, 0 } });
        FONT.put('X', new double[][] { { 0, 0, 4, 6 }, { 4, 0, 0, 6 } });
        FONT.put('Y', new double[][] { { 0, 0, 2, 3, 4, 0 }, { 2, 3, 2, 6 } });
        FONT.put('Z', new double[][] { { 0, 0, 4, 0, 0, 6, 4, 6 } });
        FONT.put('2', new double[][] { { 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 0, 6, 4, 6 } });
        FONT.put('3', new double[][] { { 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1.5, 3 }, { 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('4', new double[][] { { 3, 6, 3, 0, 0, 4, 4, 4 } });
        FONT.put('5', new double[][] { { 4, 0, 0, 0, 0, 3, 3, 3, 4, 4, 4, 5, 3, 6, 1, 6, 0, 5 } });
        FONT.put('6', new double[][] { { 4, 1, 3, 0, 1, 0, 0, 1, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3, 0, 3 } });
        FONT.put('7', new double[][] { { 0, 0, 4, 0, 1.5, 6 } });
        FONT.put('8', new double[][] { { 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 2, 3, 3, 1, 3, 0, 4, 0, 5, 1, 6, 3, 6, 4, 5, 4, 4, 3, 3 } });
        FONT.put('9', new double[][] { { 4, 3, 1, 3, 0, 2, 0, 1, 1, 0, 3, 0, 4, 1, 4, 5, 3, 6, 1, 6, 0, 5 } });
    }

    private static final char[] ALPHABET = FONT.keySet().stream()
            .map(String::valueOf).reduce("", String::concat).toCharArray();

    // algumas cores escuras, fáceis de ler sobre o fundo claro
    private static final String[] COLORS = { "#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b" };

Vamos comentar este código:

  • linha 16: a classe não é [public]; sem modificador, ela é visível apenas dentro de seu pacote ([rdvmedecins.auth]), onde somente [CaptchaService] a utiliza. [final] proíbe derivar outra classe a partir dela;
  • linha 23: [SecureRandom] é um gerador de números aleatórios “criptográfico”: suas saídas são imprevisíveis, ao passo que as de [Random] poderiam ser adivinhadas a partir de saídas anteriores. Um único gerador é usado para todos os sorteios; ele pode ser usado por várias [threads] ao mesmo tempo;
  • linhas 28–62: a “fonte”: para cada caractere, uma lista de traços, sendo cada traço uma sequência de coordenadas (x, y) em uma grade de 4 × 6. [double[][]] é um array de arrays, escrito aqui em forma expandida com chaves. O dicionário é preenchido por um bloco [static { ... }] (linhas 30–62), executado uma vez quando a classe é carregada. Os caracteres facilmente confundidos (0 e O, 1, I e L) são omitidos. Um [LinkedHashMap] preserva a ordem de inserção das chaves;
  • linhas 64–65: os caracteres utilizáveis — isto é, as chaves da fonte — são reunidos em um array de [char]. O stream (veja “A camada de negócio”) das chaves é convertido em strings de um único caractere ([String::valueOf]), que são concatenadas ([reduce("", String::concat)]), e então a string resultante é dividida em um array ([toCharArray()]).
    private CaptchaDrawing() {
    }

    static String randomText(int length) {
        StringBuilder text = new StringBuilder();
        for (int i = 0; i < length; i++) {
            text.append(ALPHABET[RANDOM.nextInt(ALPHABET.length)]);
        }
        return text.toString();
    }

    private static double randomBetween(double min, double max) {
        return min + (max - min) * RANDOM.nextDouble();
    }

    private static String color() {
        return COLORS[RANDOM.nextInt(COLORS.length)];
    }

    static String svg(String text) {
        StringBuilder svg = new StringBuilder();
        svg.append("<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"%d\" height=\"%d\" viewBox=\"0 0 %d %d\">"
                .formatted(WIDTH, HEIGHT, WIDTH, HEIGHT));
        svg.append("<rect width=\"100%\" height=\"100%\" fill=\"#f5f7fa\"/>");

        // os caracteres: cada um ampliado, inclinado, deslocado, e cada ponto
        // ligeiramente movido ao acaso
        double step = (WIDTH - 20) / (double) text.length();
        for (int i = 0; i < text.length(); i++) {
            double scale = randomBetween(4.6, 5.6); // tamanho de uma unidade da grade, em pixels
            double angle = randomBetween(-0.35, 0.35); // rotação, em radianos (cerca de ±20°)
            double cx = 10 + step * (i + 0.5) + randomBetween(-3, 3); // centro do caractere
            double cy = HEIGHT / 2.0 + randomBetween(-4, 4);
            StringBuilder d = new StringBuilder();
            for (double[] stroke : FONT.get(text.charAt(i))) {
                for (int k = 0; k < stroke.length; k += 2) {
                    // ponto da grade, centralizado em (2, 3), distorcido, girado, posicionado
                    double x = (stroke[k] - 2 + randomBetween(-0.2, 0.2)) * scale;
                    double y = (stroke[k + 1] - 3 + randomBetween(-0.2, 0.2)) * scale;
                    double px = cx + x * Math.cos(angle) - y * Math.sin(angle);
                    double py = cy + x * Math.sin(angle) + y * Math.cos(angle);
                    d.append(k == 0 ? 'M' : 'L').append(number(px)).append(' ').append(number(py)).append(' ');
                }
            }
            svg.append("<path d=\"%s\" fill=\"none\" stroke=\"%s\" stroke-width=\"%s\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>"
                    .formatted(d.toString().trim(), color(), number(randomBetween(2.2, 3))));
        }

        // 3 traços de embaralhamento: curvas que cruzam a imagem
        for (int n = 0; n < 3; n++) {
            svg.append("<path d=\"M%s %s C%s %s %s %s %s %s\" fill=\"none\" stroke=\"%s\" stroke-width=\"1.3\"/>"
                    .formatted(number(randomBetween(0, 20)), number(randomBetween(5, 45)),
                            number(randomBetween(30, 60)), number(randomBetween(0, 50)), number(randomBetween(90, 120)), number(randomBetween(0, 50)),
                            number(randomBetween(130, 150)), number(randomBetween(5, 45)), color()));
        }
        svg.append("</svg>");
        return svg.toString();
    }

    // um número com ponto decimal, seja qual for o idioma do servidor
    // (em francês, "%.1f" escreveria "12,5" - ilegível para o SVG)
    private static String number(double value) {
        return String.format(Locale.ROOT, "%.1f", value);
    }
}

Vamos comentar este código:

  • linhas 1–2: um construtor privado — a classe contém apenas métodos estáticos, portanto nenhum objeto é jamais criado;
  • linhas 4–18: sorteios aleatórios: um texto do comprimento solicitado, um número real entre dois limites, uma cor. [nextInt(n)] retorna um inteiro entre 0 e n – 1, [nextDouble()] retorna um número real entre 0 e 1;
  • Linhas 20–58: a imagem é um texto [SVG], montado dentro de um [StringBuilder] (uma string que é estendida sem ter de ser reescrita a cada vez que um elemento é adicionado). O método [formatted] substitui o [%d] (um inteiro) e o [%s] (uma string) por seus argumentos, em ordem. Cada caractere (linhas 29–47) torna-se um caminho [<path>]: cada ponto da grade é ligeiramente deslocado, ampliado, girado e colocado em sua posição na imagem, com uma cor e uma espessura de linha sorteadas aleatoriamente. Os caracteres são linhas, nunca texto: um robô não consegue lê-los no código da imagem. Três curvas de embaralhamento cruzam então a imagem (linhas 50–55);
  • linhas 62–64: os números em [SVG] são escritos com ponto decimal. [Locale.ROOT] impõe essa notação independentemente do idioma do servidor: com o francês como idioma, [%.1f] usaria uma vírgula (veja o Capítulo 5).

11.13.8. auth/AttemptLimiterService.java

O arquivo é apresentado em dois trechos.

// =========================================================================
// auth/AttemptLimiterService.java
// -------------------------------------------------------------------------
// Segunda barreira contra robôs (a primeira é o CAPTCHA): CONTAMOS as
// tentativas e, acima de um limite, BLOQUEAMOS por um tempo.
//
//   - login: após loginMaxFailures falhas (CAPTCHA errado ou senha
//     errada) para o mesmo login a partir do mesmo endereço IP, esse par
//     é bloqueado por loginBlockMinutes minutos. O mesmo endereço IP também é
//     bloqueado se acumular 5 vezes mais falhas, todos os logins juntos (um
//     robô que tenta milhares de logins diferentes);
//   - criação de conta: no máximo registrationMaxPerHour contas criadas por
//     hora a partir do mesmo endereço IP.
//
// Atenção em sala de aula: todos os computadores costumam sair para a Internet
// pelo MESMO endereço IP. É por isso que o bloqueio de login se aplica
// primeiro ao par (IP, login) - um aluno que digita uma senha errada
// não bloqueia os colegas - e por que os limites podem ser definidos
// em application.properties (rdvmedecins.protection.*).
//
// Bean singleton, chamado por requisições paralelas: todos os métodos públicos
// são "synchronized" - uma única thread por vez lê E modifica
// os contadores.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;

import org.springframework.stereotype.Service;

import rdvmedecins.config.ProtectionProperties;

@Service
public class AttemptLimiterService {

    private static class Counter {
        int count; // tentativas contadas na janela atual
        Instant start; // início da janela de contagem
        Instant blockedUntil = Instant.MIN; // Instant.MIN se não estiver bloqueado
    }

    private static final Duration ONE_HOUR = Duration.ofHours(1);

    private final Map<String, Counter> counters = new HashMap<>();

    private final int maxLoginFailures;
    private final Duration loginBlockDuration;
    private final int maxRegistrations;

    public AttemptLimiterService(ProtectionProperties protection) {
        this.maxLoginFailures = protection.loginMaxFailures();
        this.loginBlockDuration = Duration.ofMinutes(protection.loginBlockMinutes());
        this.maxRegistrations = protection.registrationMaxPerHour();
    }

    // - login

    // número de minutos de bloqueio restantes (0 = a tentativa é permitida)
    public synchronized long loginBlockMinutes(String ip, String login) {
        return Math.max(remainingMinutes(loginKey(ip, login)), remainingMinutes(ipKey(ip)));
    }

    public synchronized void loginFailure(String ip, String login) {
        count(loginKey(ip, login), maxLoginFailures, loginBlockDuration, loginBlockDuration);
        count(ipKey(ip), maxLoginFailures * 5, loginBlockDuration, loginBlockDuration);
    }

    // um login bem-sucedido zera o contador DESTE login
    public synchronized void loginSuccess(String ip, String login) {
        counters.remove(loginKey(ip, login));
    }

    // - criação de conta

    public synchronized long registrationBlockMinutes(String ip) {
        return remainingMinutes("registration|" + ip);
    }

    // janela de uma hora; atingida a cota, bloqueado até o fim da hora
    public synchronized void registrationSuccess(String ip) {
        count("registration|" + ip, maxRegistrations, ONE_HOUR, ONE_HOUR);
    }

Em comparação com o [LimiterService] do Exemplo 27, o limitador protege duas operações (a conexão e a criação de conta), o bloqueio de conexão se aplica ao par (endereço IP, login), e os limites são configuráveis em [application.properties]. Vamos comentar este código:

  • linhas 40–44: um contador: o número de tentativas, o início da janela de contagem e o fim do bloqueio ([Instant.MIN], o instante mais antigo possível, se não houver bloqueio). Esta é uma classe privada, estática e aninhada: ela existe apenas para este serviço. É uma classe comum, não um record: um contador lido do dicionário é modificado no próprio lugar, o que não é permitido com um record;
  • linha 48: um [HashMap]comum, e não um [ConcurrentHashMap]: contar uma tentativa envolve ler um contador, modificá-lo e possivelmente substituí-lo, e toda essa sequência de operações deve ser executada sem que outra requisição a interrompa. Esse é o papel da palavra-chave [synchronized] (veja o Exemplo 27), colocada em cada método público: apenas uma [thread] por vez pode executar um dos métodos [synchronized] do objeto; as demais esperam sua vez;
  • linhas 54–58: os limites, lidos uma única vez do record [ProtectionProperties], que fornece uma forma tipada para as propriedades [rdvmedecins.protection.*]: o número de falhas de conexão permitidas (5 por padrão), a duração do bloqueio (15 minutos) e o número de contas criadas por hora (10);
  • linhas 63–65: o tempo de bloqueio restante para uma tentativa de login: o maior dos dois períodos de bloqueio possíveis, o do par (endereço IP, login) e o do endereço IP isolado;
  • linhas 67–70: uma tentativa fracassada é contada duas vezes. Para o par (endereço IP, login): cinco tentativas fracassadas com o mesmo login bloqueiam esse login, somente a partir desse endereço. Para o endereço IP isolado, com um limite cinco vezes maior: um bot que tente um grande número de logins diferentes também é bloqueado. Em uma sala de aula, todos os computadores costumam se conectar à Internet pelo mesmo endereço IP: um aluno que digita a senha errada não deve bloquear seus vizinhos, daí o bloqueio por par;
  • linhas 73–75: um login bem-sucedido zera o contador desse login específico (e não o do endereço IP);
  • linhas 79–86: para a criação de contas, apenas as tentativas bem-sucedidas são contadas: no máximo dez contas por hora a partir do mesmo endereço IP. Uma vez atingida a cota, o endereço é bloqueado por uma hora.
    // - mecânica compartilhada
    // (os métodos privados são sempre chamados por um método synchronized)

    private long remainingMinutes(String key) {
        Counter c = counters.get(key);
        if (c == null) {
            return 0;
        }
        Duration remaining = Duration.between(Instant.now(), c.blockedUntil);
        // arredondado PARA CIMA ao minuto: 30 s de bloqueio restante -> "1 minuto"
        return remaining.isNegative() || remaining.isZero() ? 0 : (remaining.toSeconds() + 59) / 60;
    }

    // conta uma tentativa; se o limite for atingido dentro da janela, bloqueia
    private void count(String key, int max, Duration window, Duration block) {
        Instant now = Instant.now();
        purge(now);
        Counter c = counters.get(key);
        if (c == null || Duration.between(c.start, now).compareTo(window) > 0) {
            c = new Counter();
            c.start = now;
            counters.put(key, c);
        }
        c.count++;
        if (c.count >= max) {
            c.blockedUntil = now.plus(block);
            c.count = 0; // após o bloqueio, recomeçamos do zero
            c.start = c.blockedUntil;
        }
    }

    // esquecemos os contadores que não são mais úteis (nem bloqueados, nem recentes)
    private void purge(Instant now) {
        if (counters.size() < 1000) {
            return;
        }
        counters.values().removeIf(c -> c.blockedUntil.isBefore(now)
                && Duration.between(c.start, now).compareTo(ONE_HOUR) > 0);
    }

    private static String loginKey(String ip, String login) {
        return "login|" + ip + "|" + login.trim().toLowerCase(Locale.ROOT);
    }

    private static String ipKey(String ip) {
        return "ip|" + ip;
    }
}

Vamos analisar este código:

  • linhas 4–12: o tempo de bloqueio restante, arredondado para cima até o próximo número inteiro: restam “1 minuto”, e não “0 minuto”, quando faltam 20 segundos. [Duration.between] mede a diferença de tempo entre dois instantes. Esses métodos privados não são [synchronized]: eles são sempre chamados por um método público que já detém o bloqueio do objeto;
  • linhas 15–30: a contagem. Uma chave desconhecida, ou cuja janela de contagem expirou, começa com um novo contador. Quando o limite é atingido, a chave é bloqueada, e a contagem recomeçará do zero quando o bloqueio for liberado;
  • linhas 33–39: limpeza dos contadores que não são mais necessários (nem bloqueados nem recentes), realizada apenas quando o dicionário ultrapassa 1.000 entradas. [values()] é uma view dos valores do dicionário: [removeIf] remove os contadores dela, e as entradas correspondentes desaparecem do dicionário;
  • linhas 41–47: geração das chaves do dicionário. O login é despido de espaços e convertido em minúsculas: [Admin] e [admin] compartilham o mesmo contador; um bot não pode contornar o bloqueio mudando a caixa das letras. [Locale.ROOT] torna a conversão independente do idioma do servidor.

Vamos examinar o bloqueio. Um bot que tenta o login [robot] sem conseguir ler a imagem falha no CAPTCHA; cada falha é contada. Na sexta tentativa, o par (endereço IP, [robot]) é bloqueado, e o CAPTCHA nem chega a ser verificado. Eis a mensagem exibida na parte inferior da página em cada uma das seis tentativas:

curl -X POST -d "login=robot&password=x&captchaId=unknown&captcha=ABCDE" http://localhost:8081/login
1
2
3
4
5
6
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>The characters you typed do not match the image. A new image is shown.</div>
    <div>Too many failed attempts. Try again in 15 minute(s).</div>

Os demais logins continuam utilizáveis a partir do mesmo endereço.

11.13.9. auth/RegistrationPassService.java

// =========================================================================
// auth/RegistrationPassService.java
// -------------------------------------------------------------------------
// O "passe" para a criação de conta.
//
// Para abrir a página "Create a client account", é preciso antes ter
// copiado o CAPTCHA da página de autenticação (veja
// RegistrationController, POST /register/access). O servidor então emite
// um passe:
//   - um identificador aleatório, armazenado em um cookie HttpOnly;
//   - válido por 15 minutos (o tempo de preencher o formulário, mesmo
//     tentando várias vezes após erros de entrada);
//   - consumido assim que uma conta é criada: UM CAPTCHA resolvido = no máximo UMA
//     conta. Um robô não pode criar contas em série.
//
// Sem um passe válido, GET e POST /register redirecionam para a
// página de autenticação: digitar a URL /register diretamente não permite
// contornar o CAPTCHA.
//
// Como o CAPTCHA, os passes vivem na memória do processo.
// =========================================================================
package rdvmedecins.auth;

import java.time.Duration;
import java.time.Instant;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

import org.springframework.http.ResponseCookie;
import org.springframework.stereotype.Service;

@Service
public class RegistrationPassService {

    public static final String COOKIE = "rdvmedecins_registration";

    private static final Duration LIFETIME = Duration.ofMinutes(15);
    private static final int MAX_PASSES = 10_000;

    // id -> data de expiração
    private final Map<String, Instant> passes = new ConcurrentHashMap<>();

    // emite um novo passe; retorna seu identificador
    public String issue() {
        purge();
        String id = UUID.randomUUID().toString();
        passes.put(id, Instant.now().plus(LIFETIME));
        return id;
    }

    // true se [id] for um passe existente e não expirado
    public boolean isValid(String id) {
        Instant expires = id == null ? null : passes.get(id);
        return expires != null && expires.isAfter(Instant.now());
    }

    // o passe foi usado: nós o esquecemos
    public void consume(String id) {
        if (id != null) {
            passes.remove(id);
        }
    }

    // o cookie só é enviado pelo navegador aos endereços /register...
    public static ResponseCookie cookie(String id) {
        return ResponseCookie.from(COOKIE, id).httpOnly(true).sameSite("Lax").maxAge(LIFETIME)
                .path("/register").build();
    }

    // ... e é apagado definindo-o de novo, vazio, com tempo de vida zero
    public static ResponseCookie clearedCookie() {
        return ResponseCookie.from(COOKIE, "").maxAge(0).path("/register").build();
    }

    private void purge() {
        Instant now = Instant.now();
        passes.values().removeIf(expires -> !expires.isAfter(now));
        if (passes.size() >= MAX_PASSES) {
            passes.clear();
        }
    }
}

É possível criar uma conta de cliente a partir da página de login, desde que o CAPTCHA tenha sido resolvido. O formulário de cadastro é exibido e enviado por requisições subsequentes: essas requisições precisam saber que uma requisição anterior resolveu o CAPTCHA com sucesso. Esse é o papel do token, emitido e verificado por [RegistrationController] (veja “A camada web: os controllers”):

  • linha 36: o nome do cookie que carrega o token;
  • linhas 38–42: um token é válido por quinze minutos; os tokens pendentes são mantidos em memória, como os CAPTCHAs, com o mesmo limite de tempo;
  • linhas 45–50: um passe é um identificador aleatório, armazenado junto com sua data de expiração; o controller o coloca em um cookie;
  • linhas 53–56: o formulário de cadastro é exibido — e aceito — somente com um token válido. A verificação não consome o token ([get], e não [remove]): o usuário pode reenviar o formulário várias vezes se cometeu erros de digitação;
  • linhas 59–63: criar uma conta consome o passe: resolver um CAPTCHA dá direito a uma conta, e não mais;
  • linhas 66–74: o cookie e sua exclusão. [path("/register")] restringe a transmissão do cookie às requisições cuja URL começa com [/register]: as demais requisições não o carregam desnecessariamente. O cookie excluído deve ter o mesmo caminho;
  • linhas 76–82: limpeza, idêntica à do CAPTCHA.

11.13.10. controllers/AuthController.java

O controller da página de login é mostrado em dois trechos.

// =========================================================================
// controllers/AuthController.java
// -------------------------------------------------------------------------
// As rotas NÃO protegidas do login:
//   GET  /        redireciona para a página inicial do papel (ou para /login)
//   GET  /login   exibe o formulário de login (com seu CAPTCHA)
//   POST /login   verifica limite de tentativas, CAPTCHA, login / senha
// (POST /logout, o logout, é tratado pelo próprio Spring Security,
// veja config/SecurityConfig.java)
//
// Proteção contra robôs, nesta ordem:
//   1. falhas recentes demais para esse login a partir desse endereço IP?
//      -> recusa imediata, sem sequer olhar a senha;
//   2. resposta errada ao CAPTCHA? -> recusa (contada como falha);
//   3. só então, verificação da senha.
// NUNCA verificamos a senha de uma tentativa recusada nas etapas
// 1 ou 2: um robô, portanto, não pode aprender nada insistindo.
// =========================================================================
package rdvmedecins.controllers;

import java.util.Map;
import java.util.Optional;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.CaptchaService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.User;
import rdvmedecins.models.ViewModels.LoginModel;
import rdvmedecins.models.ViewModels.Message;

@Controller
public class AuthController {

    private final AuthService authService;
    private final CaptchaService captchaService;
    private final AttemptLimiterService limiter;

    public AuthController(AuthService authService, CaptchaService captchaService, AttemptLimiterService limiter) {
        this.authService = authService;
        this.captchaService = captchaService;
        this.limiter = limiter;
    }

    // a página inicial de cada papel, logo após o login
    public static String homePage(Role role) {
        return role == Role.USER ? "/my-area" : "/schedule";
    }

    // -----------------------------------------------------------------------
    // GET /
    // A rota é pública (veja SecurityConfig): o Spring Security pode ter
    // estabelecido o usuário se o cookie contiver um token válido, mas
    // não exige nada. AuthService.currentUser() diz se há um (ou null).
    // -----------------------------------------------------------------------
    @GetMapping("/")
    public String home(HttpServletRequest request) {
        ConnectedUser user = authService.currentUser(request);
        return "redirect:" + (user != null ? homePage(user.role()) : "/login");
    }

    // -----------------------------------------------------------------------
    // GET /login[?login=xxx]: o parâmetro opcional pré-preenche o
    // campo de login (usado logo após a criação de uma conta, veja RegistrationController)
    // -----------------------------------------------------------------------
    @GetMapping("/login")
    public String showLogin(@RequestParam(required = false) String login, HttpServletRequest request,
            Model model) {
        // já conectado (token ainda válido): direto para a página inicial
        ConnectedUser user = authService.currentUser(request);
        if (user != null) {
            return "redirect:" + homePage(user.role());
        }
        String input = login == null ? "" : login.substring(0, Math.min(login.length(), 30));
        return form(model, input, null);
    }

    // -----------------------------------------------------------------------
    // POST /login
    // Os parâmetros da action são preenchidos com os campos do formulário
    // de mesmo nome. required = false: um campo ausente resulta em null (e não em um
    // erro 400) - é o código que decide o que fazer com ele.
    // -----------------------------------------------------------------------

Vamos comentar este código:

  • linhas 11–17: a ordem em que as verificações de login são feitas é importante. A senha de uma tentativa rejeitada por bloqueio ou por um CAPTCHA incorreto nunca é verificada: um bot persistente não aprende nada;
  • linhas 41–52: [@Controller] transforma a classe em um controller cujas ações retornam nomes de views (veja o Exemplo 13). Ele recebe os três serviços de que precisa por meio de seu construtor. Nenhuma anotação [@PreAuthorize]: suas páginas são públicas (veja [SecurityConfig]);
  • linhas 55–57: a página inicial depende do papel: “Minha área” para um paciente, a agenda para os demais. O método é estático: não depende de nenhum campo do objeto;
  • linhas 65–69: a raiz do site redireciona (prefixo [redirect:], veja o Exemplo 04) para a página inicial do papel ou para a página de login. A rota é pública, mas o filtro do resource server é executado em todas as requisições: se o cookie contém um token válido, o usuário é autenticado, mesmo aqui; [authService.currentUser] retorna o usuário, ou retorna [null];
  • linhas 75–85: um usuário que já está conectado é redirecionado para sua página inicial. O parâmetro opcional [login], derivado da URL ([@RequestParam(required = false)], veja o Exemplo 07), preenche previamente o campo após a criação de uma conta. [substring] mantém no máximo os trinta primeiros caracteres: dados da requisição nunca são usados sem tomar precauções.
    @PostMapping("/login")
    public String logIn(
            @RequestParam(required = false) String login,
            @RequestParam(required = false) String password,
            @RequestParam(required = false) String captchaId,
            @RequestParam(required = false) String captcha,
            HttpServletRequest request, HttpServletResponse response, Model model) {
        login = login == null ? "" : login.trim();
        password = password == null ? "" : password;
        String ip = ipAddress(request);

        // 1. falhas recentes demais?
        long minutes = limiter.loginBlockMinutes(ip, login);
        if (minutes > 0) {
            return form(model, login,
                    new Message("ERRORS.TOO_MANY_ATTEMPTS", Map.of("minutes", String.valueOf(minutes))));
        }

        // 2. o CAPTCHA
        if (!captchaService.verify(captchaId, captcha)) {
            limiter.loginFailure(ip, login);
            return form(model, login, Message.of("ERRORS.WRONG_CAPTCHA"));
        }

        // 3. a senha
        Optional<User> user = login.isEmpty() || password.isEmpty()
                ? Optional.empty()
                : authService.validateUser(login, password);
        if (user.isEmpty()) {
            limiter.loginFailure(ip, login);
            return form(model, login, Message.of("LOGIN.ERROR"));
        }

        limiter.loginSuccess(ip, login);
        authService.setToken(response, user.get());
        return "redirect:" + homePage(user.get().getRole());
    }

    // o endereço IP do visitante. Atrás de um proxy reverso (nginx...),
    // seria preciso habilitar server.forward-headers-strategy=native para obter
    // o do visitante e não o do proxy.
    public static String ipAddress(HttpServletRequest request) {
        return request.getRemoteAddr();
    }

    // o formulário, sempre com um NOVO CAPTCHA (cada imagem é usada
    // uma única vez); exibimos de novo o login digitado, nunca a senha
    private String form(Model model, String login, Message error) {
        model.addAttribute("model", new LoginModel("LOGIN.TITLE", error, login, captchaService.generate()));
        return "login";
    }
}

Vamos analisar este código:

  • linhas 2–7: os campos do formulário de login (veja o Exemplo 11), incluindo o ID do CAPTCHA, passado por um campo oculto, e a resposta digitada pelo usuário. Todos são opcionais ([required = false]): um campo ausente resulta em [null] em vez de um erro 400, e cabe à ação decidir o que fazer com ele. A ação recebe também a requisição (para o endereço IP e o CAPTCHA), a resposta (para armazenar nela o cookie do token) e o modelo da view;
  • linhas 8–9: um nome de usuário ausente torna-se uma string vazia, sem espaços; uma senha ausente torna-se uma string vazia;
  • linhas 13–17: 1. Um par bloqueado nem chega a ser processado: nem o CAPTCHA nem a senha são verificados. O erro é uma mensagem a ser traduzida (record [Message], pasta [models]): uma chave de tradução e um parâmetro — o número de minutos a esperar. [Map.of] cria um dicionário somente leitura;
  • linhas 20–23: 2. o CAPTCHA. Um CAPTCHA incorreto conta como uma falha (veja o Exemplo 27);
  • linhas 26–32: 3. Só então, a senha. Um nome de usuário ou uma senha vazios não são submetidos ao cálculo [bcrypt], computacionalmente caro: uma caixa vazia é usada diretamente ([Optional.empty()]). Nome de usuário desconhecido ou senha incorreta: a mesma mensagem, propositalmente vaga (veja o Exemplo 25), e mais uma falha;
  • linhas 34–36: sucesso: contador zerado, token armazenado no cookie, redirecionamento para a página inicial do papel. [user.get()] recupera a conta de sua caixa, que sabemos não estar vazia;
  • linhas 42–44: o endereço IP do cliente, fornecido pela conexão de rede. O método é público e estático: [RegistrationController] e [PatientAreaController] também o usam para o limitador de taxa. Atrás de um servidor intermediário (um proxy reverso como o [nginx]), esse endereço seria o do proxy: o comentário indica que a propriedade do [Spring Boot] deve ser ativada nesse caso;
  • Linhas 48–51: a página de login, que sempre exibe um novo CAPTCHA: cada imagem é usada uma única vez. Seu modelo, o record [LoginModel] (pasta [models]), contém a chave de tradução do título da página, as eventuais mensagens de erro, o nome de usuário digitado (nunca a senha) e o CAPTCHA. Ele é armazenado no modelo sob o nome [model], o nome usado por todas as views da aplicação. A view é [login] (arquivo [templates/login.html]).

O tratamento de uma tentativa com um CAPTCHA incorreto pode ser visto com o [curl]: a página de login é retornada (código de status 200), com o nome de usuário digitado, uma nova imagem e a mensagem de erro na parte inferior da página:

curl -i -X POST -d "login=admin&password=admin&captchaId=unknown&captcha=ABCDE" http://localhost:8081/login
1
2
3
4
5
6
7
8
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
...
                 value="admin" required>
...
  <div class="error-zone" role="alert">
    <div>The characters you typed do not match the image. A new image is shown.</div>
...

A resposta não menciona a senha, que não foi verificada. Um login bem-sucedido, por outro lado, não pode ser mostrado com o [curl], já que a imagem precisa ser lida; ele é visível no navegador (veja “Uso da aplicação”): a resposta ao POST é um redirecionamento (302) para a página inicial do papel, com o cabeçalho [Set-Cookie] que define o token.

11.14. A camada web: serviços compartilhados

Antes de chegarmos aos controllers e às views, eis o que eles têm em comum: tradução, atributos compartilhados por todas as views, mensagens flash, tratamento de exceções, cache das listas de médicos e clientes, preparação de formulários a serem reexibidos e algumas funções utilitárias. Todos esses arquivos estão na pasta [web]. Ela reúne a maior parte das técnicas dos Exemplos 15 a 24.

11.14.1. web/Translator.java

O arquivo é apresentado em dois trechos.

// =========================================================================
// web/Translator.java
// -------------------------------------------------------------------------
// Tradução francês / inglês da interface (veja o exemplo 22).
//
// Os dicionários são os MESMOS arquivos das versões NestJS e
// ASP.NET Core da aplicação (i18n/fr.json, i18n/en.json), lidos uma
// única vez na inicialização.
//
// O bean se chama [messageSource] e implementa a interface MessageSource
// do Spring: é, portanto, o que o Thymeleaf usa para as expressões
// #{KEY} das views. Os parâmetros de um texto ({name}, {minutes}...) são
// passados de duas maneiras:
//   #{AREA.HELLO('name', ${patient})}           por pares (nome, valor);
//   #{${message.key}(${message.params})}        por um dicionário (Map).
//
// O IDIOMA ATUAL: é o LocaleResolver (veja config/WebConfig.java)
// que o determina a cada requisição, a partir de um cookie. O Spring o armazena
// em LocaleContextHolder e o repassa ao Thymeleaf.
// =========================================================================
package rdvmedecins.web;

import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.springframework.context.MessageSource;
import org.springframework.context.MessageSourceResolvable;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Component;

import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;

@Component("messageSource")
public class Translator implements MessageSource {

    public static final List<String> LANGUAGES = List.of("fr", "en");
    public static final String DEFAULT_LANGUAGE = "en";

    // {name}: um parâmetro em um texto
    private static final Pattern PARAMETER = Pattern.compile("\\{(\\w+)\\}");

    // idioma -> (chave completa "LOGIN.TITLE" -> texto)
    private final Map<String, Map<String, String>> dictionaries = new HashMap<>();

    public Translator() throws IOException {
        ObjectMapper json = new ObjectMapper();
        for (String language : LANGUAGES) {
            try (InputStream stream = new ClassPathResource("i18n/" + language + ".json").getInputStream()) {
                Map<String, String> dictionary = new HashMap<>();
                flatten(json.readTree(stream), "", dictionary);
                dictionaries.put(language, dictionary);
            }
        }
    }

    // o idioma suportado que corresponde a [locale]: "fr_FR" -> "fr" ; "de" -> "en"
    public static String language(Locale locale) {
        String language = locale == null ? "" : locale.getLanguage();
        return LANGUAGES.contains(language) ? language : DEFAULT_LANGUAGE;
    }

    // -----------------------------------------------------------------------
    // translate("DOCTORS.ADDED", { name: "Marie PELISSIER" }, en)
    //   -> procura "DOCTORS.ADDED" no dicionário do idioma e
    //      substitui {name} pelo seu valor. Uma chave ausente do idioma solicitado
    //      é procurada em inglês; ausente em todos, exibimos a própria
    //      chave (uma omissão é assim detectada imediatamente).
    // -----------------------------------------------------------------------
    public String translate(String key, Map<String, String> params, Locale locale) {
        if (key == null || key.isEmpty()) {
            return "";
        }
        String text = dictionaries.get(language(locale)).get(key);
        if (text == null) {
            text = dictionaries.get(DEFAULT_LANGUAGE).getOrDefault(key, key);
        }
        if (params == null || params.isEmpty()) {
            return text;
        }
        Matcher m = PARAMETER.matcher(text);
        return m.replaceAll(r -> Matcher.quoteReplacement(params.getOrDefault(r.group(1), r.group())));
    }

Este é o serviço de tradução do Exemplo 22. Os dicionários [i18n/fr.json] e [i18n/en.json] são os mesmos arquivos da versão [ASP.NET Core], lidos uma única vez na inicialização (veja “Dicionários”). Vamos comentar este código:

  • linhas 40–41: a classe implementa a interface [MessageSource] do [Spring], que é a interface dos serviços que fornecem texto, e o bean se chama [messageSource] (o argumento de [@Component]). É com esse nome que o [Spring] procura o [MessageSource] da aplicação: nosso bean substitui, portanto, o que o [Spring Boot] teria configurado, e é a esse bean que o [Thymeleaf] consulta a cada expressão [#{KEY}] nas views (veja o Exemplo 22);
  • linhas 43–44: os idiomas suportados e o idioma padrão. [List.of] cria uma lista somente leitura;
  • linha 47: uma expressão regular que reconhece um parâmetro no texto: [{], um ou mais caracteres de palavra ([\w+], capturados por parênteses), [}]. Em uma string [Java], a barra invertida é escrita como [\\]. O padrão é compilado uma única vez ([Pattern.compile]) e depois reutilizado;
  • linha 50: para cada idioma, um dicionário “chave completa → texto”. O bean é um singleton usado por requisições concorrentes; no entanto, um simples [HashMap] é suficiente, já que os dicionários, preenchidos pelo construtor, são depois apenas lidos;
  • Linhas 52–61: o construtor lê os dois arquivos JSON. [ClassPathResource] refere-se a um arquivo no “classpath” — o conjunto de pastas e arquivos compactados onde a máquina virtual procura classes: a pasta [src/main/resources] é copiada para lá durante a compilação. [ObjectMapper] é a ferramenta de leitura e escrita de JSON da biblioteca [Jackson] (versão 3, daí o pacote [tools.jackson]). [readTree] retorna a árvore do documento a partir do JSON, que o método [flatten] converte em um dicionário. A construção [try (...)] fecha o stream no fim do bloco, mesmo que ocorra uma exceção. Se um arquivo estiver ausente, a exceção [IOException], declarada por [throws], impede que a aplicação inicie;
  • Linhas 64–67: o idioma suportado correspondente ao [Locale], o objeto [Java] que descreve um idioma e, opcionalmente, um país: [en_US] resulta em [en]; um idioma não tratado resulta em [en];
  • linhas 76–89: a tradução. Se uma chave estiver ausente do dicionário do idioma solicitado, ela é procurada no dicionário inglês; se estiver ausente em todos, a própria chave é retornada ([getOrDefault(key, key)]): uma omissão fica imediatamente visível na tela. Os parâmetros do texto [{name}] são então substituídos por seus valores (linha 88): [replaceAll] chama a função lambda para cada parâmetro encontrado; [r.group(1)] é o nome capturado entre as chaves, [r.group()] é todo o texto encontrado, e [{name}] é mantido como está se nenhum valor for fornecido. [Matcher.quoteReplacement] escapa os caracteres [$] e [\], que de outro modo teriam um significado específico para [replaceAll].
    // os parâmetros passados pelo Thymeleaf (ou pelo Spring): um único
    // dicionário, ou pares (nome, valor)
    @SuppressWarnings("unchecked")
    private static Map<String, String> params(Object[] args) {
        Map<String, String> params = new HashMap<>();
        if (args == null || args.length == 0) {
            return params;
        }
        if (args.length == 1 && args[0] instanceof Map<?, ?> dictionary) {
            dictionary.forEach((name, value) -> params.put(String.valueOf(name), String.valueOf(value)));
            return params;
        }
        for (int i = 0; i + 1 < args.length; i += 2) {
            params.put(String.valueOf(args[i]), String.valueOf(args[i + 1]));
        }
        return params;
    }

    // { "LOGIN": { "TITLE": "Login" } } -> { "LOGIN.TITLE": "Login" }
    private static void flatten(JsonNode node, String prefix, Map<String, String> result) {
        for (Map.Entry<String, JsonNode> property : node.properties()) {
            String key = prefix.isEmpty() ? property.getKey() : prefix + "." + property.getKey();
            if (property.getValue().isObject()) {
                flatten(property.getValue(), key, result);
            } else {
                result.put(key, property.getValue().asString());
            }
        }
    }

    // ——— a interface MessageSource

    @Override
    public String getMessage(String code, Object[] args, String defaultMessage, Locale locale) {
        return translate(code, params(args), locale);
    }

    @Override
    public String getMessage(String code, Object[] args, Locale locale) {
        return translate(code, params(args), locale);
    }

    // uma mensagem descrita por vários códigos possíveis (um erro de
    // validação, por exemplo): o primeiro código presente no dicionário
    // vence; caso contrário, a mensagem padrão, que é ela própria uma chave
    @Override
    public String getMessage(MessageSourceResolvable message, Locale locale) {
        Map<String, String> dictionary = dictionaries.get(language(locale));
        String[] codes = message.getCodes() == null ? new String[0] : message.getCodes();
        for (String code : codes) {
            if (dictionary.containsKey(code)) {
                return translate(code, params(message.getArguments()), locale);
            }
        }
        return translate(message.getDefaultMessage(), Map.of(), locale);
    }
}

Vamos analisar este código:

  • Linhas 5–18: os parâmetros de uma mensagem são passados como um array de objetos ([Object[]]) de duas maneiras possíveis. Uma view que escreve [#{AREA.HELLO('name', ${patient})}] passa pares (nome, valor) (linhas 14–16). Uma view que exibe uma mensagem flash ou um erro escreve [#{${message.key}(${message.params})}]: ela passa um único argumento, o dicionário de parâmetros (linhas 10–13). [instanceof Map<?, ?> dictionary] verifica o tipo e armazena o objeto convertido na variável [dictionary]; [<?, ?>] significa “chaves e valores de qualquer tipo”. [String.valueOf] converte qualquer objeto em texto;
  • linhas 21–30: achatamento do JSON: [{ "LOGIN": { "TITLE": "Login" } }] torna-se [{ "LOGIN.TITLE": "Login" }]. O método é recursivo: ele chama a si mesmo para cada objeto aninhado, estendendo o prefixo da chave;
  • linhas 34–42: os dois principais métodos da interface [MessageSource]: um código (a chave), seus argumentos e o idioma. [@Override] instrui o compilador a verificar se o método de fato redefine um método da interface. A mensagem padrão fornecida pelo primeiro método é ignorada: uma chave ausente é exibida como está;
  • linhas 47–57: o terceiro método recebe uma mensagem descrita por vários códigos possíveis, como os gerados pelo [Spring] para um erro de validação ou de conversão ([typeMismatch.version], [typeMismatch]...). O primeiro código encontrado no dicionário tem precedência; caso contrário, a mensagem padrão é traduzida. Nesta aplicação, as mensagens das restrições de validação são chaves de tradução (veja [models/Forms.java]): a mensagem padrão é, portanto, ela própria uma chave.

O idioma da requisição não aparece em nenhum lugar dos controllers: é o [LocaleResolver] (bean [localeResolver] de [config/WebConfig.java], veja “Configuração do projeto”) que o lê do cookie [rdvmedecins_language] no início de cada requisição; o [Spring] então o repassa ao [Thymeleaf], que o repassa a [getMessage].

11.14.2. web/CommonModel.java

// =========================================================================
// web/CommonModel.java
// -------------------------------------------------------------------------
// O que TODAS as views precisam, seja qual for a página (veja o exemplo
// 15): @ControllerAdvice faz desta classe um complemento de todos os
// controllers, e cada método @ModelAttribute, executado antes de cada
// action, adiciona um atributo ao modelo da view:
//   - user     : o usuário conectado (ou null), para a barra de navegação;
//   - language : "fr" ou "en";
//   - path     : a URL solicitada (menu ativo da barra de navegação,
//                link "Another image" do CAPTCHA).
// A mensagem flash é adicionada ao modelo pelo próprio Spring MVC,
// sob o nome [flash] (veja CookieFlashMapManager.java).
// =========================================================================
package rdvmedecins.web;

import java.util.Locale;

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ModelAttribute;

import jakarta.servlet.http.HttpServletRequest;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.ConnectedUser;

@ControllerAdvice
public class CommonModel {

    private final AuthService authService;

    public CommonModel(AuthService authService) {
        this.authService = authService;
    }

    @ModelAttribute("user")
    public ConnectedUser user(HttpServletRequest request) {
        return authService.currentUser(request);
    }

    // Locale: o idioma da requisição, fornecido pelo Spring (veja config/WebConfig.java)
    @ModelAttribute("language")
    public String language(Locale locale) {
        return Translator.language(locale);
    }

    @ModelAttribute("path")
    public String path(HttpServletRequest request) {
        return request.getRequestURI();
    }
}

Todas as páginas exibem a mesma barra de navegação: o nome do usuário logado, seus menus de acordo com o papel, o menu atualmente selecionado em destaque e os botões FR / EN. Portanto, o modelo de cada view deve conter o usuário, o idioma e a URL solicitada. Em vez de adicioná-los em cada action, nós os adicionamos de uma vez por todas, como no Exemplo 15:

  • linha 26: [@ControllerAdvice] transforma a classe em um componente de todos os controllers (veja os Exemplos 15 e 24);
  • Linhas 35–38: um método anotado com [@ModelAttribute("user")] é executado antes de cada action, e o valor que ele retorna é adicionado ao modelo com o nome especificado. Aqui, o usuário logado, ou [null], obtido por meio de [AuthService.currentUser] (veja [auth/AuthService.java]): a barra de navegação exibe [${user.name}], [${user.isAdmin()}]... Assim como as actions, esses métodos recebem os parâmetros de que precisam — neste caso, a requisição;
  • linhas 41–44: o idioma atual ([fr] ou [en]), para o atributo [lang] da página e para os botões FR / EN. Um parâmetro do tipo [Locale] recebe o idioma da requisição, definido pelo [LocaleResolver];
  • linhas 47–49: o caminho da URL solicitada, por exemplo [/my-area]: a barra de navegação destaca o menu cujo caminho começa dessa forma (veja o Exemplo 16), e o link “Outra imagem” do CAPTCHA recarrega a página atual.

A mensagem flash, o quarto dado comum, não requer um método: o [Spring MVC] a adiciona ao modelo por conta própria (veja [CookieFlashMapManager.java], adiante). No [ASP.NET Core MVC], esses dados eram propriedades de uma classe-mãe compartilhada por todas as views; o [Thymeleaf] não tem uma classe-mãe para as views e, em vez disso, o modelo de cada view recebe esses dados.

11.14.3. web/FlashType.java

1
2
3
4
5
6
7
8
9
// =========================================================================
// web/FlashType.java - os dois tipos de mensagens flash (veja Flash.java)
// =========================================================================
package rdvmedecins.web;

public enum FlashType {
    SUCCESS, // classe Bootstrap alert-success: no topo da página
    DANGER // um erro: no rodapé da página (veja templates/fragments/errors.html)
}
  • linhas 6–9: os dois tipos de mensagens flash, na forma de uma enumeração: um tipo cujos valores possíveis são fixados de uma vez por todas. Uma mensagem de sucesso é exibida no topo da página (fragmento [templates/fragments/flash.html]), e uma mensagem de erro na parte inferior (fragmento [templates/fragments/errors.html]; veja “Views”).

11.14.4. web/FlashMessage.java

// =========================================================================
// web/FlashMessage.java
// -------------------------------------------------------------------------
// Uma mensagem "flash": uma mensagem a exibir UMA VEZ, na PRÓXIMA página
// (veja o exemplo 20). key: chave de tradução; params: seus parâmetros
// ({name}, {login}...).
// =========================================================================
package rdvmedecins.web;

import java.util.Map;

public record FlashMessage(FlashType type, String key, Map<String, String> params) {

    // o nome do atributo flash, no modelo das views
    public static final String ATTRIBUTE = "flash";

    public static FlashMessage success(String key) {
        return new FlashMessage(FlashType.SUCCESS, key, Map.of());
    }

    public static FlashMessage success(String key, Map<String, String> params) {
        return new FlashMessage(FlashType.SUCCESS, key, params);
    }

    public static FlashMessage error(String key) {
        return new FlashMessage(FlashType.DANGER, key, Map.of());
    }

    public static FlashMessage error(String key, Map<String, String> params) {
        return new FlashMessage(FlashType.DANGER, key, params);
    }

    public boolean successful() {
        return type == FlashType.SUCCESS;
    }
}
  • linha 12: uma mensagem flash (veja o Exemplo 20) consiste em um tipo, uma chave de tradução e seus parâmetros — e não em um texto pré-traduzido — e será traduzida pela página seguinte para o idioma dessa página;
  • linha 15: o nome sob o qual a mensagem é passada e sob o qual as views a encontram em seu modelo: [flash]. Um controller, por exemplo, escreve [redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"))];
  • linhas 17–31: quatro métodos estáticos que criam uma mensagem, com ou sem parâmetros. Métodos com o mesmo nome, mas parâmetros diferentes, são sobrecargas: o compilador seleciona a correta com base nos argumentos. [Map.of()] é um dicionário vazio;
  • linhas 33–35: um teste para as views: [${flash.successful()}].

11.14.5. web/CookieFlashMapManager.java

// =========================================================================
// web/CookieFlashMapManager.java
// -------------------------------------------------------------------------
// As mensagens "flash": uma mensagem a exibir UMA VEZ, na PRÓXIMA
// página. É o complemento natural do padrão "Post / Redirect / Get"
// usado por todos os formulários da aplicação: um POST bem-sucedido não
// constrói uma página, ele redireciona (302) para uma página GET; a mensagem
// precisa sobreviver ao redirecionamento.
//
// O Spring MVC a oferece de série: um controller coloca um atributo flash
// (RedirectAttributes.addFlashAttribute, veja o exemplo 20), que vai parar
// no modelo da PRÓXIMA requisição e depois desaparece. Por padrão, o Spring
// o mantém na SESSÃO HTTP (SessionFlashMapManager). Mas nosso
// servidor é STATELESS: ele não guarda nada entre duas requisições (o token
// JWT está em um cookie). Substituímos, portanto, o "gerenciador de
// atributos flash" (FlashMapManager) do Spring pelo nosso, que os armazena em um
// COOKIE - é o bean [flashMapManager] de config/WebConfig.java.
//
// AbstractFlashMapManager faz a maior parte do trabalho (para qual requisição a
// mensagem se destina, expiração...): resta apenas ler e escrever a
// lista de atributos flash. Guardamos só um, como texto JSON
// codificado em base64 (um cookie não pode conter qualquer caractere).
//
// O cookie não é criptografado nem assinado: ele contém apenas uma
// CHAVE de tradução e seus parâmetros, exibidos com escape. Um usuário que
// o modificasse só mudaria a mensagem que ele mesmo vê.
// =========================================================================
package rdvmedecins.web;

import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Base64;
import java.util.List;

import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.web.servlet.FlashMap;
import org.springframework.web.servlet.support.AbstractFlashMapManager;
import org.springframework.web.util.WebUtils;

import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import tools.jackson.databind.ObjectMapper;

public class CookieFlashMapManager extends AbstractFlashMapManager {

    public static final String COOKIE = "rdvmedecins_flash";

    // o que o cookie contém: a página à qual a mensagem se destina, a
    // data de expiração (em milissegundos), a mensagem
    private record CookieContent(String path, long expires, FlashMessage flash) {
    }

    private final ObjectMapper json = new ObjectMapper();

    // os atributos flash da requisição anterior (null: nenhum)
    @Override
    protected List<FlashMap> retrieveFlashMaps(HttpServletRequest request) {
        Cookie cookie = WebUtils.getCookie(request, COOKIE);
        if (cookie == null) {
            return null;
        }
        try {
            byte[] bytes = Base64.getUrlDecoder().decode(cookie.getValue());
            CookieContent content = json.readValue(bytes, CookieContent.class);
            FlashMap flashMap = new FlashMap();
            flashMap.put(FlashMessage.ATTRIBUTE, content.flash());
            flashMap.setTargetRequestPath(content.path());
            flashMap.setExpirationTime(content.expires());
            // uma lista MODIFICÁVEL: o Spring remove dela mesmo as mensagens
            // consumidas (List.of(...) daria uma lista imutável)
            return new ArrayList<>(List.of(flashMap));
        } catch (RuntimeException e) {
            return null; // cookie ilegível: nós o ignoramos
        }
    }

    // a lista a manter para as próximas requisições: vazia -> apagamos o cookie
    @Override
    protected void updateFlashMaps(List<FlashMap> flashMaps, HttpServletRequest request,
            HttpServletResponse response) {
        ResponseCookie cookie;
        if (flashMaps.isEmpty() || !(flashMaps.getLast().get(FlashMessage.ATTRIBUTE) instanceof FlashMessage flash)) {
            cookie = ResponseCookie.from(COOKIE, "").path("/").maxAge(0).build();
        } else {
            FlashMap last = flashMaps.getLast();
            CookieContent content = new CookieContent(last.getTargetRequestPath(), last.getExpirationTime(), flash);
            String value = Base64.getUrlEncoder().withoutPadding()
                    .encodeToString(json.writeValueAsString(content).getBytes(StandardCharsets.UTF_8));
            cookie = ResponseCookie.from(COOKIE, value).path("/").httpOnly(true).sameSite("Lax").build();
        }
        response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
    }
}

No Exemplo 20, os atributos Flash do [Spring MVC] eram preservados entre o redirecionamento e a página seguinte na sessão HTTP: um espaço de memória do servidor específico de cada navegador, identificado pelo cookie [JSESSIONID]. No entanto, nosso servidor é stateless: ele não retém nada na memória entre as requisições, pois o usuário é identificado por seu token. Esta classe, portanto, armazena os atributos Flash em um cookie, assim como o [TempData] fazia na versão [ASP.NET Core]. Vamos comentar este código:

  • linha 46: o [Spring MVC] delega o armazenamento dos atributos Flash a um bean do tipo [FlashMapManager]. [AbstractFlashMapManager] faz a maior parte do trabalho: ele sabe para qual requisição um atributo Flash se destina, quando expira e quando foi consumido. Uma classe derivada só precisa implementar dois métodos: a leitura da lista de atributos Flash pendentes (linhas 58–77) e o seu salvamento (linhas 80–94). O bean [flashMapManager] de [config/WebConfig.java] cria um objeto desta classe; ele tem o nome sob o qual o [Spring MVC] procura esse gerenciador e, assim, substitui o do [Spring MVC];
  • linhas 52–53: o conteúdo do cookie: o caminho da página à qual a mensagem se destina, sua data de expiração (em milissegundos) e a mensagem;
  • linha 55: o [Jackson] converte um objeto em texto JSON e vice-versa, inclusive um record;
  • linhas 58–77: o processo de leitura, chamado no início de cada requisição. O cookie é decodificado (base64 e depois JSON), e a mensagem é colocada de volta em um objeto [FlashMap] (um dicionário de atributos flash, com seu caminho de destino e sua data de expiração), o único da lista. A lista retornada deve ser modificável (linhas 71–73): o [Spring MVC] remove a mensagem da lista por conta própria quando a consome. Um cookie ilegível (modificado manualmente, por exemplo) não deve provocar a falha da página: a exceção é capturada e o cookie é ignorado;
  • Linhas 80–94: a função chamada quando a lista foi alterada — uma mensagem foi postada, consumida ou expirou. Uma lista vazia apaga o cookie; caso contrário, a última mensagem postada é gravada no cookie. A expressão [instanceof FlashMessage flash], colocada na condição, verifica o tipo do atributo e o armazena na variável [flash], que é usada na linha 88. O texto JSON é codificado em Base64 ([Base64.getUrlEncoder()], uma variante sem os caracteres [+] e [/]), porque um cookie não pode conter qualquer caractere; as aspas e os acentos do JSON não são permitidos. O cookie não tem tempo de expiração ([Max-Age]): é um cookie de sessão do navegador, e o que importa é o prazo de expiração do conteúdo (três minutos por padrão);
  • Linhas 24–26: o cookie não é criptografado nem assinado, ao contrário do cookie do [TempData] e do [ASP.NET Core]. Isso é desnecessário: ele contém apenas uma chave de tradução e seus parâmetros, que são exibidos de forma escapada pelas views; um usuário que o modificasse apenas mudaria a mensagem que ele próprio vê.

Vimos, com o [SecurityConfig], que uma mensagem de “sessão expirada” era armazenada neste cookie. Eis o conteúdo decodificado do cookie usado no comando a seguir (capturado durante um teste diferente do anterior: apenas a data de expiração difere):

{"path":"/login","expires":1790355130312,"flash":{"type":"DANGER","key":"ERRORS.SESSION_EXPIRED","params":{}}}

A requisição seguinte, para [/login], consome a mensagem: a página a exibe, e a resposta apaga o cookie.

curl -i -H "Cookie: rdvmedecins_flash=eyJwYXRoIjoiL2xvZ2luIiwiZXhwaXJlcyI6MTc5MDM1NTEzMDMxMiwiZmxhc2giOnsidHlwZSI6IkRBTkdFUiIsImtleSI6IkVSUk9SUy5TRVNTSU9OX0VYUElSRUQiLCJwYXJhbXMiOnt9fX0" http://localhost:8081/login
1
2
3
4
5
6
7
8
9
HTTP/1.1 200
Set-Cookie: rdvmedecins_flash=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/html;charset=UTF-8
...
  <div class="error-zone" role="alert">

    <div>Your session has expired: please log in again.</div>
  </div>
...

A mensagem é exibida apenas uma vez: quando a página é recarregada, ela não aparece mais.

11.14.6. web/Flash.java

// =========================================================================
// web/Flash.java
// -------------------------------------------------------------------------
// Colocar uma mensagem flash de QUALQUER LUGAR, inclusive fora do
// Spring MVC: a autenticação JWT (sessão expirada, veja
// config/SecurityConfig.java) roda em um filtro do Spring Security,
// ANTES do Spring MVC - um RedirectAttributes ainda não existe ali.
// Então nos dirigimos diretamente ao FlashMapManager (CookieFlashMapManager).
// Em um controller, usamos antes RedirectAttributes.addFlashAttribute.
// =========================================================================
package rdvmedecins.web;

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.FlashMap;
import org.springframework.web.servlet.FlashMapManager;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Component
public class Flash {

    private final FlashMapManager manager;

    public Flash(FlashMapManager manager) {
        this.manager = manager;
    }

    // coloca [message], destinada à página [target] (a próxima requisição)
    public void put(HttpServletRequest request, HttpServletResponse response, FlashMessage message, String target) {
        FlashMap flashMap = new FlashMap();
        flashMap.put(FlashMessage.ATTRIBUTE, message);
        flashMap.setTargetRequestPath(target);
        manager.saveOutputFlashMap(flashMap, request, response);
    }
}

Em um controller, uma mensagem flash é exibida com [RedirectAttributes.addFlashAttribute] (veja o Exemplo 20). O entry point do [SecurityConfig], por outro lado, é executado em um filtro do [Spring Security], antes de o [Spring MVC] assumir a requisição:

  • linha 20: [@Component] transforma a classe em um bean, que o [SecurityConfig] recebe como parâmetro;
  • linhas 25–27: o bean recebe o gerenciador de atributos Flash, ou seja, o nosso [CookieFlashMapManager];
  • linhas 30–35: nós mesmos criamos o [FlashMap] — que normalmente o [Spring MVC] cria — incluindo a mensagem e o caminho da página que deve recebê-la ([/login]). [saveOutputFlashMap] o passa ao gerenciador, que grava o cookie na resposta.

11.14.7. web/HtmlExceptionHandler.java

// =========================================================================
// web/HtmlExceptionHandler.java
// -------------------------------------------------------------------------
// Como os erros viram páginas HTML. Três mecanismos
// dividem o trabalho (veja o exemplo 24):
//
//   1. esta classe: uma InvalidSessionException (conta excluída desde
//      o login) -> volta para a página de login;
//   2. uma resposta de erro 400, 403 ou 404 (ResponseStatusException lançada
//      por um controller, papel insuficiente, página desconhecida...) é repassada
//      pelo servidor ao endereço /error: o ErrorController a transforma em página;
//   3. qualquer outra exceção (uma anomalia real) é escrita no log do
//      servidor e depois repassada também a /error: o usuário
//      vê a página de erro 500 - nunca o stack trace.
// =========================================================================
package rdvmedecins.web;

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.support.RequestContextUtils;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.InvalidSessionException;

@ControllerAdvice
public class HtmlExceptionHandler {

    @ExceptionHandler(InvalidSessionException.class)
    public String invalidSession(HttpServletRequest request, HttpServletResponse response) {
        AuthService.clearToken(response);
        // o atributo flash do redirecionamento que se segue (o equivalente de
        // RedirectAttributes.addFlashAttribute, para um método @ExceptionHandler)
        RequestContextUtils.getOutputFlashMap(request)
                .put(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.SESSION_EXPIRED"));
        return "redirect:/login";
    }
    // as outras exceções não são tratadas aqui: elas se propagam
    // até o servidor, que as repassa a /error (página 500)
}

O comentário de cabeçalho (linhas 4–14) descreve os três mecanismos que convertem erros em páginas HTML (veja o Exemplo 24). Dois deles não exigem código: uma resposta de erro ([sendError(403)], uma [ResponseStatusException] lançada por um controller, uma URL desconhecida) é enviada pelo servidor ao endereço [/error], onde o [ErrorController] gera a página; uma exceção não tratada é registrada no log do servidor, junto com sua pilha de chamadas, e depois também encaminhada para [/error], que exibe a página de erro 500. O usuário nunca vê a pilha de chamadas, que ajudaria um atacante (propriedade [spring.web.error.include-stacktrace=never]; veja “Configuração do projeto”). Resta um caso especial, tratado aqui:

  • linha 27: [@ControllerAdvice], como no [CommonModel]: os métodos da classe se aplicam a todos os controllers;
  • linhas 30–31: um método [@ExceptionHandler] é chamado quando uma action lança a exceção especificada (veja o Exemplo 24). Ele pode receber a requisição e a resposta e retornar o nome de uma view ou um redirecionamento, exatamente como uma action;
  • linhas 32–37: a conta do usuário logado foi excluída depois que ele fez login, embora seu token ainda seja válido (veja [auth/InvalidSessionException.java]). Apagamos o cookie do token, exibimos uma mensagem flash de “sessão expirada” e redirecionamos para a página de login: o usuário é tratado como se sua sessão tivesse expirado. Um método anotado com [@ExceptionHandler] não pode aceitar um parâmetro do tipo [RedirectAttributes]: [RequestContextUtils.getOutputFlashMap(request)] retorna diretamente o [FlashMap] que o redirecionamento passará à página seguinte.

11.14.8. web/ApplicationModel.java

O arquivo é apresentado em dois trechos.

// =========================================================================
// web/ApplicationModel.java
// -------------------------------------------------------------------------
// O cache / fachada já presente no servidor JSON (equivalente da
// classe [ApplicationModel] do projeto Spring original): as listas de
// médicos e clientes são lidas uma vez na inicialização e depois servidas
// a partir da memória.
//
// Essas listas podem MUDAR (o ADMIN adiciona, edita e exclui
// médicos e clientes): cada escrita passa, portanto, por esta fachada,
// que recarrega a lista afetada logo em seguida. Esse é todo o sentido de um
// ÚNICO ponto de entrada para a camada de negócio: a regra "escrita =>
// recarga do cache" é escrita somente aqui.
//
// A fachada é um bean SINGLETON, como a própria camada de negócio: com
// o Spring, os DAOs e a camada de negócio não dependem de nenhuma requisição (é
// o Spring que associa a cada thread SUA transação e SUA conexão). O
// cache e a fachada podem, portanto, ser o mesmo objeto.
//
// O Spring processa as requisições EM PARALELO, em várias threads. Por isso nunca
// modificamos uma lista no lugar: nós a SUBSTITUÍMOS inteiramente por uma
// nova. Trocar uma referência é atômico; "volatile" garante que
// todas as threads vejam imediatamente a nova lista.
// =========================================================================
package rdvmedecins.web;

import java.time.LocalDate;
import java.util.List;
import java.util.Objects;
import java.util.Optional;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;

import jakarta.annotation.PostConstruct;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Doctor;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.Business;

// mesmo contrato da camada de negócio (Business)
@Service
public class ApplicationModel implements Business {

    private final Business business;

    private volatile List<Doctor> doctors = List.of();
    private volatile List<Client> clients = List.of();

    // dois beans implementam Business: BusinessService e o próprio ApplicationModel.
    // @Qualifier designa o que queremos, pelo seu nome.
    public ApplicationModel(@Qualifier("businessService") Business business) {
        this.business = business;
    }

    // -----------------------------------------------------------------------
    // carga inicial das duas listas. @PostConstruct: o Spring chama
    // este método uma vez criado o objeto e injetadas suas dependências, na
    // inicialização da aplicação. Um erro de leitura não é capturado:
    // ele interrompe o servidor, em vez de deixá-lo subir "vazio" (um
    // banco de dados inacessível o interrompe ainda antes, assim que o Hibernate inicia).
    // -----------------------------------------------------------------------
    @PostConstruct
    public void load() {
        reloadDoctors();
        reloadClients();
    }

    private void reloadDoctors() {
        doctors = List.copyOf(business.getAllDoctors());
    }

    private void reloadClients() {
        clients = List.copyOf(business.getAllClients());
    }

    // - leituras a partir do cache

    @Override
    public List<Doctor> getAllDoctors() {
        return doctors;
    }

    @Override
    public List<Client> getAllClients() {
        return clients;
    }

    // o médico cuja conta de usuário é [userId] - usado para pré-selecionar,
    // para um médico conectado, a sua própria agenda
    public Optional<Doctor> getDoctorByUserId(int userId) {
        return doctors.stream().filter(d -> Objects.equals(d.getUserId(), userId)).findFirst();
    }

As listas de médicos e de clientes são exibidas em quase todas as páginas (listas suspensas na agenda, páginas de administração). Em vez de recuperá-las do banco de dados a cada requisição, nós as mantemos na memória: são dados de escopo de aplicação (veja o Exemplo 23). Vamos comentar este código:

  • Linhas 45–46: a classe é um bean singleton que implementa a interface [Business], que é a interface da camada de negócio (veja “A camada de negócio”): para os controllers, esta classe é a camada de negócio, e é a única que eles recebem (por exemplo, [public ScheduleController(ApplicationModel application)]). Ela é uma fachada: um único ponto de entrada que oculta o que há por trás dele. No [ASP.NET Core], o cache precisava ser um serviço separado da fachada, porque a camada de negócio ali existe apenas durante uma requisição; com o [Spring], a própria camada de negócio é um singleton (é o [Spring] que associa cada [thread] à sua transação e à sua conexão com o banco de dados): um único objeto basta (linhas 15–18);
  • linha 48: a camada de negócio propriamente dita, [BusinessService], para a qual a fachada encaminha as requisições;
  • linhas 50–51: o cache propriamente dito: as duas listas, inicialmente vazias ([List.of()]). O [Spring] processa as requisições em paralelo em várias [threads] . Uma lista compartilhada nunca deve, portanto, ser modificada enquanto outra requisição a percorre. A regra escolhida é simples: nunca modificar uma lista; em vez disso, substituí-la por uma nova. A substituição de uma referência é feita em uma única operação, e a palavra-chave [volatile] garante que todas as [threads] vejam imediatamente a nova lista; sem ela, uma [thread] poderia continuar lendo um valor antigo, armazenado no cache de seu processador;
  • Linhas 55–57: dois beans são do tipo [Business]: [BusinessService] e [ApplicationModel] em si. Simplesmente solicitar “um [Business]” seria ambíguo, e o [Spring] se recusaria a iniciar. [@Qualifier("businessService")] refere-se ao bean desejado pelo nome; um bean declarado por [@Service] recebe por padrão o nome de sua classe, com a primeira letra minúscula;
  • Linhas 66–70: o carregamento inicial das duas listas. [@PostConstruct] faz o [Spring] chamar o método assim que o objeto é criado e suas dependências são injetadas, durante a inicialização da aplicação, antes que o servidor aceite qualquer requisição. Um erro de leitura não é capturado: ele encerra a aplicação, o que é melhor do que ter um servidor iniciado com listas vazias (um banco de dados inacessível, aliás, encerra a aplicação ainda mais cedo, assim que o [Hibernate] é iniciado; veja “Instalação e execução”);
  • linhas 72–78: recarga de uma lista: a lista inteira é lida do banco de dados e substitui a do cache. [List.copyOf] cria uma cópia somente leitura da lista;
  • linhas 82–90: as listas são servidas a partir da memória. A lista retornada é a do próprio cache: como é somente leitura, um chamador que tentasse adicionar um item a ela provocaria uma exceção, e o cache não pode ser modificado acidentalmente;
  • linhas 94–96: o médico associado a uma conta, recuperado do cache: um médico logado vê imediatamente a sua própria agenda. O stream de médicos é filtrado ([filter]), e [findFirst] retorna o primeiro médico selecionado em um [Optional], que fica vazio se nenhum for adequado. [getUserId()] retorna um [Integer] (um objeto), e [userId] é um [int]: [Objects.equals] compara os dois valores sem risco de erro, mesmo que [Integer] fosse igual a [null].
    // - delegações simples

    @Override
    public List<Slot> getAllSlots(int doctorId) {
        return business.getAllSlots(doctorId);
    }

    @Override
    public List<Appointment> getDoctorDayAppointments(int doctorId, LocalDate day) {
        return business.getDoctorDayAppointments(doctorId, day);
    }

    @Override
    public Optional<Client> getClientById(int id) {
        return business.getClientById(id);
    }

    @Override
    public Optional<Doctor> getDoctorById(int id) {
        return business.getDoctorById(id);
    }

    @Override
    public Optional<Appointment> getAppointmentById(int id) {
        return business.getAppointmentById(id);
    }

    @Override
    public Optional<Slot> getSlotById(int id) {
        return business.getSlotById(id);
    }

    @Override
    public Optional<DoctorDaySchedule> getDoctorDaySchedule(int doctorId, LocalDate day) {
        return business.getDoctorDaySchedule(doctorId, day);
    }

    // sem cache aqui: o que importa são os dados mais recentes (um paciente
    // que acabou de editar ou excluir sua conta)
    @Override
    public Optional<Client> getClientByUserId(int userId) {
        return business.getClientByUserId(userId);
    }

    @Override
    public List<Appointment> getClientUpcomingAppointments(int clientId) {
        return business.getClientUpcomingAppointments(clientId);
    }

    @Override
    public Appointment addAppointment(LocalDate day, Slot slot, Client client) {
        return business.addAppointment(day, slot, client);
    }

    @Override
    public void deleteAppointment(Appointment appointment) {
        business.deleteAppointment(appointment);
    }

    // - escritas => recarga

    @Override
    public Doctor addDoctor(PersonData data) {
        Doctor doctor = business.addDoctor(data);
        reloadDoctors();
        return doctor;
    }

    @Override
    public Doctor editDoctor(int id, PersonData data) {
        Doctor doctor = business.editDoctor(id, data);
        reloadDoctors();
        return doctor;
    }

    @Override
    public void deleteDoctor(int id) {
        business.deleteDoctor(id);
        reloadDoctors();
    }

    @Override
    public Client addClient(PersonData data) {
        Client client = business.addClient(data);
        reloadClients();
        return client;
    }

    @Override
    public Client editClient(int id, PersonData data) {
        Client client = business.editClient(id, data);
        reloadClients();
        return client;
    }

    @Override
    public void deleteClient(int id) {
        business.deleteClient(id);
        reloadClients();
    }
}

Vamos comentar este código:

  • linhas 3–58: as demais requisições são repassadas como estão à camada de negócio;
  • linhas 38–43: o titular da conta intencionalmente não é buscado no cache; um paciente que acabou de modificar ou excluir sua conta deve ser visto como aparece no banco de dados;
  • linhas 60–101: qualquer operação de escrita envolvendo médicos ou clientes é seguida de uma recarga da lista correspondente. Como este bean é o único ponto de entrada dos controllers para a camada de negócio, a regra “escrita = recarga do cache” é implementada somente aqui, e o cache não pode ficar desatualizado. Se a camada de negócio rejeitar a operação ([BusinessException]), a exceção encerra o método antes da recarga do cache, pois essa etapa deixa de ser necessária.

11.14.9. web/Validation.java

// =========================================================================
// web/Validation.java
// -------------------------------------------------------------------------
// O que é necessário para EXIBIR DE NOVO um formulário recusado: os erros de entrada
// campo a campo, e os campos a destacar em vermelho.
// =========================================================================
package rdvmedecins.web;

import java.util.Collection;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;

import rdvmedecins.models.ViewModels.FormState;
import rdvmedecins.models.ViewModels.Message;

public final class Validation {

    private Validation() {
    }

    // -----------------------------------------------------------------------
    // BindingResult (preenchido pelo Spring durante o binding e a validação
    // do formulário) -> o dicionário campo -> chave da mensagem, mantendo
    // apenas a primeira mensagem de cada campo: { "lastName": "ERRORS.LASTNAME_REQUIRED", ... }
    //
    // Um erro de CONVERSÃO (um texto onde se espera um número:
    // version="abc") tem o código "typeMismatch" e uma mensagem técnica, em
    // inglês: nós a substituímos pela chave ERRORS.INVALID_FORM.
    // -----------------------------------------------------------------------
    public static Map<String, String> errorsOf(BindingResult result) {
        Map<String, String> errors = new HashMap<>();
        for (FieldError error : result.getFieldErrors()) {
            String key = error.isBindingFailure() || error.getDefaultMessage() == null
                    ? "ERRORS.INVALID_FORM"
                    : error.getDefaultMessage();
            errors.putIfAbsent(error.getField(), key);
        }
        return errors;
    }

    // -----------------------------------------------------------------------
    // os campos do formulário afetados por cada erro de negócio de "entrada"
    // (uma duplicata): eles são destacados em vermelho, estando a mensagem no rodapé da página
    // -----------------------------------------------------------------------
    public static final Map<String, List<String>> BUSINESS_ERROR_FIELDS = Map.of(
            "ERRORS.LOGIN_TAKEN", List.of("login"),
            "ERRORS.DOCTOR_ALREADY_EXISTS", List.of("firstName", "lastName"),
            "ERRORS.PATIENT_ALREADY_EXISTS", List.of("firstName", "lastName"));

    // o estado de um formulário a (re)exibir: uma mensagem sob cada campo
    // recusado pela validação (errors), e os campos a destacar em vermelho,
    // esses mais eventualmente outros (otherFields)
    public static FormState state(Map<String, String> errors, Collection<String> otherFields) {
        Set<String> fields = new HashSet<>(errors.keySet());
        if (otherFields != null) {
            fields.addAll(otherFields);
        }
        return new FormState(errors, fields);
    }

    // A mensagem de erro ÚNICA da página, exibida no rodapé da página: [error] se
    // houver, senão "The form contains errors." se houver
    // erros de campo, senão nada
    public static Message pageMessage(Map<String, String> errors, Message error) {
        if (error != null) {
            return error;
        }
        return errors.isEmpty() ? null : Message.of("ERRORS.INVALID_FORM");
    }
}

Quando um formulário é rejeitado, a página é exibida novamente com os dados informados, uma mensagem abaixo de cada campo inválido, os campos inválidos destacados em vermelho e uma mensagem na parte inferior da página. Esta classe prepara essas informações para os controllers:

  • linhas 22–25: uma classe utilitária: [final] (não pode ser estendida), um construtor privado (não é possível criar objetos dessa classe) e apenas métodos estáticos;
  • linhas 36–45: converte o [BindingResult] (veja os exemplos 09 e 19) — preenchido pelo [Spring] durante o binding e a validação do formulário — em um dicionário simples “campo → chave de mensagem”. [putIfAbsent] adiciona uma entrada somente se o campo ainda não tiver uma: apenas a primeira mensagem de cada campo é mantida, e apenas uma mensagem é exibida abaixo do campo. As mensagens das restrições de validação são chaves de tradução (veja [models/Forms.java]); um erro de conversão ([isBindingFailure()]: texto onde se espera um número), por outro lado, tem uma mensagem técnica em inglês, substituída pela chave [ERRORS.INVALID_FORM];
  • linhas 51–54: certos erros da camada de negócio dizem respeito a campos específicos: um nome de usuário já em uso, ou um médico ou cliente com o mesmo nome. Esses campos serão destacados em vermelho, com a mensagem exibida na parte inferior da página. [Map.of] gera o dicionário em uma única expressão;
  • linhas 59–65: o estado do formulário a ser exibido: as mensagens abaixo dos campos e os campos a serem destacados em vermelho — ou seja, aqueles que têm uma mensagem — mais os campos [otherFields] (aqueles que indicam um erro de negócio). Um [HashSet] é um conjunto: cada elemento aparece apenas uma vez. O resultado é um record [FormState] (veja [models/ViewModels.java]);
  • linhas 70–75: a mensagem na parte inferior da página: a mensagem de erro específica, se houver; caso contrário, se houver erros de campo, a mensagem “O formulário contém erros”; caso contrário, nada ([null]).

11.14.10. web/Utils.java

// =========================================================================
// web/Utils.java
// -------------------------------------------------------------------------
// Pequenas funções utilitárias da camada web:
//   - rótulos: "Mme Alice DURAND";
//   - datas: "yyyy-MM-dd", horas "8:05", dias "Wednesday 23 September 2026";
//   - entrada: leitura de um inteiro positivo enviado pelo navegador;
//   - paciente: o paciente (entidade Client) do usuário conectado.
//
// Uma classe "utilitária": somente métodos estáticos, nunca criamos
// um objeto dessa classe (construtor privado).
// =========================================================================
package rdvmedecins.web;

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.format.ResolverStyle;
import java.util.Locale;
import java.util.Optional;

import org.springframework.security.oauth2.jwt.Jwt;

import rdvmedecins.auth.InvalidSessionException;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Person;

public final class Utils {

    private Utils() {
    }

    // - rótulos

    // "Mme Alice DURAND"
    public static String label(Person p) {
        return p.getTitle() + " " + p.getFirstName() + " " + p.getLastName();
    }

    // - datas

    // o formato das datas nas URLs e no campo <input type="date">;
    // ESTRITO: "2026-02-30" é recusado (e não levado a 2 de março)
    private static final DateTimeFormatter ISO = DateTimeFormatter.ofPattern("uuuu-MM-dd")
            .withResolverStyle(ResolverStyle.STRICT);

    // a data, se [text] for uma data que existe no formato yyyy-MM-dd
    public static Optional<LocalDate> validDate(String text) {
        try {
            return Optional.of(LocalDate.parse(text, ISO));
        } catch (DateTimeParseException | NullPointerException e) {
            return Optional.empty();
        }
    }

    public static String iso(LocalDate day) {
        return day.format(ISO);
    }

    // "8:05" em vez de "8:5"
    public static String formatTime(int h, int m) {
        return "%d:%02d".formatted(h, m);
    }

    public static String time(Slot s) {
        return formatTime(s.getStartHour(), s.getStartMinute()) + " - " + formatTime(s.getEndHour(), s.getEndMinute());
    }

    // "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", conforme o
    // idioma da requisição
    public static String formatDay(LocalDate day, Locale language) {
        return day.format(DateTimeFormatter.ofPattern("EEEE d MMMM yyyy", language));
    }

    // - entrada

    // "3" -> 3 ; "", "abc", "-2", "+2", null -> null
    public static Integer positiveInteger(String value) {
        if (value == null || !value.matches("\\d{1,9}")) {
            return null;
        }
        int n = Integer.parseInt(value);
        return n > 0 ? n : null;
    }

    // - usuário

    // o usuário descrito pelo token da requisição (parâmetro
    // @AuthenticationPrincipal Jwt token de uma action). Um token válido mas
    // incompleto (claims ausentes) é tratado como sessão expirada.
    public static ConnectedUser user(Jwt token) {
        ConnectedUser user = ConnectedUser.of(token);
        if (user == null) {
            throw new InvalidSessionException();
        }
        return user;
    }

    // - paciente

    // -----------------------------------------------------------------------
    // O paciente (entidade Client) que corresponde ao usuário conectado.
    //
    // O token JWT contém apenas o id da CONTA (users.id). Para um papel
    // USER, encontramos o cliente correspondente graças à coluna clients.user.
    //
    // Se não houver nenhum, a conta foi excluída desde o
    // login enquanto seu token ainda é válido: tratamos isso como uma sessão
    // expirada (veja InvalidSessionException).
    // -----------------------------------------------------------------------
    public static Client connectedPatient(ApplicationModel application, ConnectedUser user) {
        if (user == null) {
            throw new InvalidSessionException();
        }
        return application.getClientByUserId(user.userId()).orElseThrow(InvalidSessionException::new);
    }
}

Vamos comentar este código:

  • linhas 38–40: o nome de um médico ou de um cliente: “Mme Alice DURAND.” O parâmetro é do tipo [Person], a classe-mãe das entidades [Doctor] e [Client] (veja “Entidades”): a mesma função é usada para ambas;
  • Linhas 46–47: o formato da data nas URLs e no campo [<input type="date">]. O modo [STRICT] rejeita uma data que não existe: [2026-02-30] é um erro, em vez de ser convertida em 2 de março (veja o Exemplo 12). Nesse modo, o ano é escrito como [uuuu]: [yyyy] se referiria ao ano “da era”, o que exigiria especificar também a era (antes ou depois de Cristo);
  • linhas 50–56: a data, se o texto for uma data válida no formato [yyyy-MM-dd]; caso contrário, vazio. Um texto no formato [null] provoca uma [NullPointerException], que é interceptada como uma data malformada: o formato [catch (A | B e)] intercepta dois tipos de exceções;
  • linhas 58–60: a operação inversa: uma data convertida no texto [yyyy-MM-dd];
  • linhas 63–69: um horário no formato [8:05] (o formato [%02d] escreve um inteiro com pelo menos dois dígitos, preenchido com zeros) e o horário de um intervalo: [8:00 - 8:20];
  • linhas 73–75: um dia escrito por extenso, no idioma da requisição, que o controller recebe como parâmetro ([Locale]): “mercredi 23 septembre 2026” ou “Wednesday 23 September 2026.” [EEEE] é o dia da semana por extenso, e [MMMM] é o mês;
  • linhas 80–86: um identificador enviado pelo navegador (na URL ou em um campo de formulário): um inteiro estritamente positivo ou [null]. A expressão regular [\d{1,9}] aceita apenas dígitos, até nove: sem sinais, sem espaços e sem números grandes demais para um [int]. O controller então precisa apenas testar [null];
  • linhas 93–99: o usuário identificado pelo token da requisição, que uma action recebe por meio de um parâmetro declarado como [@AuthenticationPrincipal Jwt token]. Um token devidamente assinado, mas incompleto, é tratado como uma sessão expirada;
  • Linhas 113–118: o paciente (entidade [Client]) associado ao usuário logado. O token JWT contém apenas o ID da conta; buscamos o cliente associado a essa conta. Se ele não existir mais, significa que a conta foi excluída desde que o usuário fez login: a [InvalidSessionException] será tratada pelo [HtmlExceptionHandler], como vimos acima, que redireciona para a página de login. [orElseThrow] extrai o cliente do [Optional], ou lança a exceção gerada por seu argumento se o [Optional] estiver vazio. [InvalidSessionException::new] é uma referência a construtor: a forma abreviada do lambda [() -> new InvalidSessionException()].

11.15. Modelos de formulário e de view

Dois tipos de classes transferem dados entre o navegador, os controllers e as views: os formulários, que são preenchidos pelo binding de modelo a partir do que o navegador envia e depois validados; e os modelos de view, que são preparados pelos controllers para as views. Os primeiros são JavaBeans, os segundos são records; veremos por quê. Eles ficam na pasta [models], junto com as regras de validação de entrada que compartilham.

11.15.1. models/InputRules.java

// =========================================================================
// models/InputRules.java
// -------------------------------------------------------------------------
// As regras de entrada comuns aos formulários de "pessoa".
// =========================================================================
package rdvmedecins.models;

import java.util.List;

public final class InputRules {

    private InputRules() {
    }

    public static final List<String> TITLES = List.of("Mr", "Mme", "Melle");

    // login: letras minúsculas, dígitos, ponto, hífen, sublinhado - no máximo 30 caracteres
    public static final String LOGIN_FORMAT = "^[a-z0-9._-]{1,30}$";

    // tamanho mínimo de uma senha ESCOLHIDA por um paciente
    public static final int PASSWORD_MIN = 6;

    // "  dupont " -> "dupont" ; "   " -> null
    public static String clean(String value) {
        return value == null || value.isBlank() ? null : value.trim();
    }

    // um campo vazio -> null; para uma senha, NÃO removemos os
    // espaços (eles podem fazer parte dela)
    public static String emptyToNull(String value) {
        return value == null || value.isEmpty() ? null : value;
    }
}
  • linha 15: os títulos possíveis. Eles são usados para gerar a lista suspensa dos formulários (veja [ViewModels.java], adiante);
  • linha 18: o formato de um nome de usuário, descrito por uma expressão regular: de 1 a 30 caracteres compostos por letras minúsculas, dígitos, ponto, sublinhado e hífen. [^] e [$] indicam o início e o fim do texto;
  • linha 21: o comprimento mínimo de uma senha escolhida por um paciente;
  • linhas 18 e 21: esses dois campos são constantes: [static final], inicializados com um valor fixo no programa. O compilador conhece seus valores, o que permite usá-los como argumentos de uma anotação, por exemplo, [@Size(min = InputRules.PASSWORD_MIN)]. Não é o caso da lista [TITLES] (linha 15), que é criada em tempo de execução;
  • linhas 24–26: limpeza de uma entrada: os espaços no início e no fim são removidos, e um campo vazio ou composto apenas de espaços ([isBlank()]) torna-se [null], ou seja, ausente;
  • linhas 30–32: para uma senha, um campo vazio torna-se [null], mas os espaços são mantidos: eles fazem parte da senha.

11.15.2. models/Forms.java

O arquivo é apresentado em dois trechos.

// =========================================================================
// models/Forms.java
// -------------------------------------------------------------------------
// Os campos dos formulários de "pessoa" e suas restrições. Três
// formulários compartilham os mesmos campos de identidade (título, nome, sobrenome):
//
//   PersonFields                  título, nome, sobrenome
//    ├─ PersonForm                + login / senha OPCIONAIS, version
//    │                              (o ADMIN adiciona ou edita um médico / cliente)
//    ├─ RegistrationForm          + login / senha / confirmação OBRIGATÓRIOS
//    │                              (um paciente cria sua conta)
//    └─ MyAccountForm             + login, nova senha opcional,
//                                   senha ATUAL obrigatória, version
//                                   (um paciente edita sua conta)
//
// MODEL BINDING: quando uma action de controller recebe um parâmetro de
// uma dessas classes, o Spring MVC cria o objeto e preenche cada campo, por meio
// do seu setter, com o parâmetro de mesmo nome (veja o exemplo 18).
//
// VALIDAÇÃO: com @Valid, o Spring então verifica as restrições
// (@NotBlank, @Size...) e armazena os erros no BindingResult que segue
// o parâmetro (veja os exemplos 09 e 19).
//
// As mensagens de erro são CHAVES de tradução (veja i18n/*.json).
//
// LIMPEZA DA ENTRADA: os setters removem os espaços supérfluos
// (uma entrada vazia vira null) e colocam o login em minúsculas. Uma
// senha, por outro lado, não é "limpa" (espaços podem fazer parte dela).
//
// As classes são "aninhadas" (static) na classe Forms: um único
// arquivo para quatro classes pequenas. Elas são designadas por
// Forms.PersonForm...
// =========================================================================
package rdvmedecins.models;

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

public final class Forms {

    private Forms() {
    }

    // - base comum
    public abstract static class PersonFields {

        @NotNull(message = "ERRORS.INVALID_TITLE")
        @Pattern(regexp = "Mr|Mme|Melle", message = "ERRORS.INVALID_TITLE")
        private String title;

        // comprimentos máximos = os das colunas SQL (VARCHAR(20))
        @NotBlank(message = "ERRORS.FIRSTNAME_REQUIRED")
        @Size(max = 20, message = "ERRORS.FIRSTNAME_TOO_LONG")
        private String firstName;

        @NotBlank(message = "ERRORS.LASTNAME_REQUIRED")
        @Size(max = 20, message = "ERRORS.LASTNAME_TOO_LONG")
        private String lastName;

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

        public String getFirstName() { return firstName; }
        public void setFirstName(String firstName) { this.firstName = InputRules.clean(firstName); }

        public String getLastName() { return lastName; }
        public void setLastName(String lastName) { this.lastName = InputRules.clean(lastName); }
    }

O comentário de cabeçalho (linhas 4–32) descreve os três formulários de “pessoa” e sua base comum. Os formulários seguem a abordagem usada nos Exemplos 18 e 19: uma action recebe um parâmetro anotado com [@Valid], seguido de um parâmetro [BindingResult]. O [Spring MVC] cria o objeto, preenche-o com os campos recebidos (binding de modelo), depois verifica as restrições definidas pelas anotações (validação) e armazena os eventuais erros em [BindingResult]. Essas anotações ([@NotNull], [@NotBlank], [@Size], [@Pattern]) são as do padrão [Bean Validation] (pacote [jakarta.validation]), introduzido pelo starter [spring-boot-starter-validation] juntamente com sua implementação, o [Hibernate Validator]. Vamos comentar este código:

  • linhas 41–44: uma classe cujo único propósito é agrupar quatro pequenas classes aninhadas em um único arquivo. Declaradas como [static], elas são independentes de qualquer instância de [Forms]: são referenciadas como [Forms.PersonForm], ou simplesmente [PersonForm] após um [import];
  • linha 47: os campos de identidade, comuns aos três formulários. A classe é abstrata ([abstract]): não é possível criar um objeto dela, apenas derivar dela;
  • linhas 49–51: o título, que é obrigatório ([@NotNull]) e selecionado da lista ([@Pattern]). Os valores são repetidos na expressão regular [Mr|Mme|Melle] ([|] significa “ou”): o argumento de uma anotação deve ser uma constante, o que a lista [InputRules.TITLES] não é. [@Pattern] exige que o texto inteiro corresponda à expressão;
  • linhas 53–60: o nome e o sobrenome, que são obrigatórios e devem ter no máximo 20 caracteres: as larguras das colunas SQL (veja “O banco de dados”). [@NotBlank] rejeita [null], texto vazio e texto composto apenas de espaços. Cada restrição tem sua própria mensagem; as mensagens são chaves de tradução (veja o Exemplo 22), traduzidas pela view para o idioma do usuário;
  • linhas 62–69: os getters, cada um escrito em uma única linha. Os setters limpam a entrada à medida que a recebem: como o binding de modelo atualiza os campos por meio dos setters antes da validação, é o valor já limpo que é validado. Um nome composto de espaços torna-se [null], e é o [@NotBlank] que o rejeita.

Por que JavaBeans, e não records? Um JavaBean é uma classe comum que tem um construtor sem parâmetros e, para cada propriedade, um par [getXxx()] e [setXxx()]. O [Spring MVC] cria o objeto vazio e depois chama um setter para cada campo recebido: cada campo é processado separadamente. O [Spring MVC] também pode preencher um record, mas chamando seu construtor com todos os campos de uma só vez: se um único campo não puder ser convertido (como texto no campo numérico [version]), o objeto não é construído e nenhuma restrição é verificada. Com um JavaBean, um erro de conversão em um campo não impede a validação dos outros: o usuário vê todos os erros de uma vez. O JavaBean também permite limpar a entrada nos setters.

    // - ADMIN
    public static class PersonForm extends PersonFields {

        // opcional (veja business/PersonData.java)
        @Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
        private String login;

        // opcional; no máximo 72 caracteres (além disso, o bcrypt ignora o resto)
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        // campo oculto do formulário de edição (bloqueio otimista).
        // Integer: um campo ausente ou vazio resulta em null; um texto que não é
        // um número gera um erro de binding (typeMismatch)
        private Integer version;

        public String getLogin() { return login; }
        public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }

        public String getPassword() { return password; }
        public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }

        public Integer getVersion() { return version; }
        public void setVersion(Integer version) { this.version = version; }
    }

    // - criação de conta de um paciente
    public static class RegistrationForm extends PersonFields {

        @NotNull(message = "ERRORS.LOGIN_REQUIRED")
        @Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
        private String login;

        // duas restrições @Size, cada uma com sua mensagem
        @NotNull(message = "ERRORS.PASSWORD_REQUIRED")
        @Size(min = InputRules.PASSWORD_MIN, message = "ERRORS.PASSWORD_TOO_SHORT")
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        @NotNull(message = "ERRORS.CONFIRMATION_REQUIRED")
        private String confirmation;

        public String getLogin() { return login; }
        public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }

        public String getPassword() { return password; }
        public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }

        public String getConfirmation() { return confirmation; }
        public void setConfirmation(String confirmation) { this.confirmation = InputRules.emptyToNull(confirmation); }
    }

    // - "Manage my account"
    public static class MyAccountForm extends PersonFields {

        @NotNull(message = "ERRORS.LOGIN_REQUIRED")
        @Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
        private String login;

        // opcional: vazio = senha inalterada
        @Size(min = InputRules.PASSWORD_MIN, message = "ERRORS.PASSWORD_TOO_SHORT")
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        private String confirmation;

        // a senha ATUAL, exigida para qualquer edição da conta
        @NotNull(message = "ERRORS.CURRENT_PASSWORD_REQUIRED")
        private String currentPassword;

        private Integer version;

        public String getLogin() { return login; }
        public void setLogin(String login) { this.login = lowerCase(InputRules.clean(login)); }

        public String getPassword() { return password; }
        public void setPassword(String password) { this.password = InputRules.emptyToNull(password); }

        public String getConfirmation() { return confirmation; }
        public void setConfirmation(String confirmation) { this.confirmation = InputRules.emptyToNull(confirmation); }

        public String getCurrentPassword() { return currentPassword; }
        public void setCurrentPassword(String password) { this.currentPassword = InputRules.emptyToNull(password); }

        public Integer getVersion() { return version; }
        public void setVersion(Integer version) { this.version = version; }
    }

    private static String lowerCase(String text) {
        return text == null ? null : text.toLowerCase(java.util.Locale.ROOT);
    }
}

Vamos comentar este código:

  • linha 2: o formulário de ADMIN, para adicionar ou modificar um médico ou um cliente. A classe herda os campos de identidade, suas restrições e seus acessores;
  • linhas 4–6: o login, que aqui é opcional (se deixado em branco, assume por padrão o sobrenome em minúsculas na criação e permanece inalterado na modificação; veja “A camada de negócio”), mas deve estar no formato correto se informado. Como todas as restrições do [Bean Validation] exceto [@NotNull] e [@NotBlank], [@Pattern] aceita o valor [null]: é isso que torna o campo opcional. O setter (linha 18) limpa o login e o converte para minúsculas (método [lowerCase], linhas 89–91);
  • linhas 8–10: a senha, que também é opcional, com no máximo 72 caracteres: o algoritmo [bcrypt] ignora os caracteres seguintes. Ela não é higienizada, mas simplesmente definida como [null] se estiver vazia (linha 21);
  • linhas 12–15: a versão do registro, em um campo oculto do formulário de atualização (bloqueio otimista; veja o Exemplo 28). O tipo [Integer] — e não [int] — aceita o valor [null]: um campo ausente ou vazio resulta em [null]. Um texto que não é um número produz um erro de conversão, que [web/Validation.java] converte na mensagem “O formulário contém erros”;
  • linha 28: um paciente cria uma conta. O login é obrigatório (linha 30): [@NotNull] é suficiente, pois o setter converte uma entrada vazia em [null];
  • linhas 34–38: a senha, obrigatória, de 6 a 72 caracteres. Duas anotações [@Size] no mesmo campo: uma anotação declarada como repetível pode aparecer várias vezes, neste caso para que cada limite tenha sua própria mensagem;
  • linhas 40–41: confirmação da senha, obrigatória. Verificar que a senha corresponde à sua confirmação envolve dois campos: isso é verificado pelo controller ([RegistrationController], veja “A camada web: controllers”);
  • linha 54: um paciente modificando sua conta. O login é obrigatório; a nova senha é opcional (linhas 60–63): se deixada em branco, permanece inalterada, e sua confirmação (linha 65) não é, portanto, exigida aqui. A senha atual, porém, é obrigatória para qualquer alteração (linhas 67–69), assim como a versão do registro em um campo oculto (linha 71);
  • linhas 89–91: conversão do nome de usuário para minúsculas. [Locale.ROOT] torna a conversão independente do idioma do servidor (em turco, por exemplo, a minúscula de [I] não é [i]). O nome completo [java.util.Locale] evita uma linha como [import].

11.15.3. models/ViewModels.java

O arquivo é apresentado em dois trechos.

// =========================================================================
// models/ViewModels.java
// -------------------------------------------------------------------------
// Os "view models": o que cada controller passa à
// sua view, sob o nome [model]. São records: objetos imutáveis,
// construídos de uma só vez pelo controller, que a view apenas lê
// (${model.schedule.rows}...).
//
// Regra seguida por todas as páginas: nenhuma lógica nas views. Os
// controllers preparam dados JÁ formatados ("Mme Marie
// PELISSIER", "8:00 - 8:20", selected = true...) e já filtrados conforme o
// papel do usuário; as views apenas os posicionam no HTML.
// =========================================================================
package rdvmedecins.models;

import java.util.List;
import java.util.Map;
import java.util.Set;

import rdvmedecins.auth.Captcha;

public final class ViewModels {

    private ViewModels() {
    }

    // -------------------------------------------------------------------------
    // o que TODAS as páginas têm em comum, lido pelo layout
    // (templates/layout.html): a chave do título da página e A mensagem
    // de erro da página, exibida no rodapé da página (null: sem erro)
    // -------------------------------------------------------------------------
    public interface ViewModel {
        String pageTitle();

        Message error();
    }

    // uma mensagem a traduzir: sua chave e seus parâmetros
    public record Message(String key, Map<String, String> params) {

        public static Message of(String key) {
            return new Message(key, Map.of());
        }
    }

    // uma opção de uma lista suspensa (médico, paciente)
    public record OptionView(int id, String label, boolean selected) {
    }

    // - login
    public record LoginModel(String pageTitle, Message error, String login, Captcha captcha) implements ViewModel {
    }

    // - agenda
    public record ScheduleRowView(
            int slotId,
            String time, // "8:00 - 8:20"
            boolean free,
            String patient, // nome exibido para um horário reservado; null = "Booked"
            boolean mine, // a consulta do paciente conectado
            boolean bookable, // exibir o botão "Book"?
            String bookUrl,
            Integer appointmentId) { // preenchido apenas se o botão "Cancel" for exibido
    }

    public record ScheduleView(String doctor, String day, List<ScheduleRowView> rows) {
    }

    public record BookingView(
            int slotId,
            String time,
            List<OptionView> clients, // ADMIN / DOCTOR: os pacientes entre os quais escolher
            String patient) { // USER: o paciente é ele mesmo
    }

    public record ScheduleModel(
            String pageTitle,
            Message error,
            List<OptionView> doctors,
            Integer doctorId,
            String day, // "yyyy-MM-dd"
            ScheduleView schedule,
            BookingView booking,
            String backUrl, // a agenda exibida, sem diálogo de reserva
            // paciente que já tem uma consulta futura: a mensagem que explica
            // por que não há botão "Book"
            String info) implements ViewModel {
    }

Os modelos de view seguem uma regra já aplicada nos exemplos: nenhuma lógica nas views. Os controllers preparam dados já formatados (“Mme Marie PELISSIER”, “8:00 – 8:20”) e já filtrados de acordo com o papel do usuário; as views apenas os colocam no HTML. Trata-se de records: construídos uma só vez pelo controller, eles são depois apenas lidos pela view, que escreve, por exemplo, [${model.schedule.rows}]; o [Thymeleaf] então chama os acessores [schedule()], seguido de [rows()]. Cada controller armazena o modelo de sua view sob o nome [model]. Vamos comentar este código:

  • linhas 32–36: o que todas as páginas têm em comum, lido pelo template [templates/layout.html] (veja “Views”): a chave de tradução do título da página e a mensagem de erro da página, exibida na parte inferior, ou [null]. Trata-se de uma interface, e não de uma classe-mãe: um record não pode herdar de uma classe, mas pode implementar interfaces. Um record que tem os componentes [pageTitle] e [error] tem automaticamente os acessores [pageTitle()] e [error()]: ele implementa a interface sem nenhuma linha de código adicional;
  • linhas 39–44: uma mensagem a ser traduzida: sua chave e seus parâmetros. O método estático [of] cria uma mensagem sem parâmetros;
  • linhas 47–48: uma opção de uma lista suspensa (um médico, um paciente), já marcada como selecionada ou não selecionada (veja o Exemplo 18);
  • linhas 51–52: a página de login: o nome de usuário já digitado e o CAPTCHA a ser exibido. O corpo do record está vazio: tudo está em seus componentes;
  • linhas 55–64: uma entrada na agenda, ou seja, um intervalo de horário. O controller já determinou tudo: se o nome do paciente é exibido ou não (um paciente não pode ver os nomes dos outros: [patient] é então equivalente a [null], e a view exibe “Reservado”), se o botão “Reservar” é exibido ou não e se o botão “Cancelar” é exibido ou não ([appointmentId] está preenchido). [appointmentId] é um [Integer], que pode ser equivalente a [null];
  • linhas 66–67: a agenda de um médico para um determinado dia: o médico, o dia por extenso e as linhas;
  • linhas 69–74: a janela de consulta: a lista de pacientes para ADMIN e para os médicos, ou apenas o nome do paciente logado, no caso de um único paciente;
  • linhas 76–88: a página da agenda de consultas: a lista de médicos, o médico e o dia selecionados, a agenda de consultas ([null] enquanto nenhum médico estiver selecionado), a janela de reserva (se aplicável), a URL da agenda de consultas sem essa janela (linha 84) e a mensagem que explica a um paciente por que ele não pode fazer uma reserva.
    // - formulários de "pessoa"

    // os valores exibidos nos campos do formulário (nunca a senha)
    public record PersonValues(String title, String firstName, String lastName, String login, Integer version) {

        public static PersonValues empty() {
            return new PersonValues("Mr", "", "", "", null);
        }
    }

    // o estado de um formulário recusado: a mensagem exibida SOB cada campo
    // (campo -> chave da mensagem), e os campos a destacar em vermelho (classe
    // Bootstrap is-invalid): os que têm uma mensagem, mais eventualmente outros
    // (nome + sobrenome duplicados, login já usado...)
    public record FormState(Map<String, String> errors, Set<String> invalidFields) {

        public static FormState empty() {
            return new FormState(Map.of(), Set.of());
        }

        public String errorOf(String field) {
            return errors.get(field);
        }

        public String invalidClass(String field) {
            return invalidFields.contains(field) ? "is-invalid" : "";
        }
    }

    // uma opção da lista de títulos
    public record TitleOption(String value, boolean selected) {
    }

    // o que o fragmento comum person-fields.html usa (título, nome, sobrenome)
    public interface FormView extends ViewModel {
        PersonValues values();

        FormState state();

        // um método "default": escrito na interface, herdado pelos records
        default List<TitleOption> titles() {
            return InputRules.TITLES.stream().map(t -> new TitleOption(t, t.equals(values().title()))).toList();
        }
    }

    public record PersonFormModel(
            String pageTitle,
            Message error,
            PersonValues values,
            FormState state,
            boolean creating, // true: adicionar; false: editar
            String action, // URL do POST
            String listUrl) implements FormView {
    }

    public record RegistrationModel(String pageTitle, Message error, PersonValues values, FormState state)
            implements FormView {

        public int passwordMin() {
            return InputRules.PASSWORD_MIN;
        }
    }

    public record MyAccountModel(String pageTitle, Message error, PersonValues values, FormState state)
            implements FormView {

        public int passwordMin() {
            return InputRules.PASSWORD_MIN;
        }
    }

    // - listas de médicos / clientes

    // as chaves de tradução específicas de cada tipo de pessoa
    public record PersonKeys(
            String title, // "Doctors"
            String add, // "Add a doctor"
            String edit, // "Edit a doctor"
            String empty, // "No doctors."
            String confirmDelete, // "Delete this doctor and their account?"
            String added, // "Doctor {name} has been added (login: {login})."
            String edited,
            String deleted) {
    }

    public record PersonView(String title, String firstName, String lastName, String login, String editUrl,
            String deleteUrl) {
    }

    public record PersonListModel(String pageTitle, Message error, PersonKeys keys, String addUrl,
            List<PersonView> persons) implements ViewModel {
    }

    // - área do paciente
    public record AppointmentView(int id, String day, String time, String doctor, String scheduleUrl) {
    }

    public record AreaModel(String pageTitle, Message error, String patient, List<AppointmentView> appointments)
            implements ViewModel {
    }

    // - página de erro
    public record ErrorModel(String pageTitle, Message error, int code, String message) implements ViewModel {
    }
}

Vamos analisar este código:

  • linhas 4–9: os valores exibidos nos campos de um formulário de “pessoa”; nunca a senha — uma senha não é enviada de volta ao navegador. [empty()] fornece os valores de um formulário de adição;
  • linhas 15–28: o estado de um formulário, preparado por [web/Validation.java]: as mensagens abaixo dos campos e os campos a serem destacados em vermelho. Um record pode ter métodos: [errorOf] retorna a mensagem de um campo (ou [null]), [invalidClass] retorna a classe [Bootstrap] [is-invalid], que contorna um campo em vermelho, ou uma string vazia. Por exemplo, as views escrevem [th:classappend="${state.invalidClass('login')}"], onde [state] refere-se a [model.state];
  • linhas 31–32: uma opção da lista de títulos, com a selecionada marcada (veja o Exemplo 18);
  • linhas 35–44: o que o fragmento comum [person-fields.html] usa, que exibe os campos de título, nome e sobrenome dos três formulários: os valores e o estado. Uma interface pode herdar de outra ([extends ViewModel]). Linhas 41–43: um método default ([default]) é um método cujo código é escrito na própria interface; as classes e records que implementam a interface o herdam. Aqui, a lista de títulos, gerada a partir dos valores do formulário: o stream de títulos é transformado ([map]) em opções, e [toList()] reúne o resultado em uma lista. Os três modelos de formulário se beneficiam disso sem exigir nenhum código adicional;
  • linhas 46–54: o formulário de ADMIN, usado para adicionar e modificar registros (veja o Exemplo 28): o modo, a URL de envio do formulário e a URL da lista para o botão de voltar;
  • Linhas 56–70: os formulários de cadastro e de gerenciamento de conta; eles passam à view o comprimento mínimo da senha, que é usado como parâmetro [{min}] na mensagem de erro do campo e, no cadastro, no texto de ajuda. Um método comum no corpo do record é suficiente: a view escreve [${model.passwordMin()}];
  • linhas 75–84: as páginas de gerenciamento de médicos e clientes são as mesmas views; apenas seus textos diferem. Este record contém as chaves de tradução específicas de cada tipo de pessoa;
  • linhas 86–92: uma linha da lista de médicos ou de clientes, com os endereços de seus botões Editar e Excluir, e o modelo da página de lista;
  • linhas 95–100: a área do paciente: seu nome e suas próximas consultas, cada uma com um link para a agenda do dia;
  • linhas 103–104: a página de erro: o código HTTP e a chave da mensagem.

11.16. A camada web: controllers

Os controllers são a parte visível da camada web: cada um recebe as requisições de um grupo de páginas, lê seus parâmetros, consulta a camada de negócio (sempre por meio do serviço [ApplicationModel]), depois seleciona uma view e passa um modelo a ela, ou redireciona a requisição. Uma action retorna uma string: ou o nome de uma view (["schedule"] refere-se ao arquivo [templates/schedule.html]; veja o Exemplo 13), ou um redirecionamento (["redirect:/login"]; veja o Exemplo 04). O modelo da view é sempre um único objeto, um [record] do arquivo [models/ViewModels.java], armazenado no [Model] do Spring sob o nome [model]. Todos os formulários POST seguem o padrão Post/Redirect/Get (veja o Exemplo 20); todas as mensagens são chaves de tradução, traduzidas pela view. O controller de login, [AuthController], foi comentado junto com a autenticação.

11.16.1. controllers/LanguageController.java

// =========================================================================
// controllers/LanguageController.java
// -------------------------------------------------------------------------
// GET /language/fr, GET /language/en: os dois botões FR / EN da barra de
// navegação. Rota não protegida: é preciso poder trocar de idioma antes de
// fazer login.
//
// A escolha é lembrada no cookie do CookieLocaleResolver (veja
// config/WebConfig.java): a cada requisição seguinte, o Spring MVC o lê de volta
// e define o idioma da requisição (o parâmetro Locale das actions, o
// idioma das mensagens #{...} das views). Depois voltamos à página de
// onde viemos.
// =========================================================================
package rdvmedecins.controllers;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.Locale;

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.LocaleResolver;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.web.Translator;

@Controller
public class LanguageController {

    private final LocaleResolver localeResolver;

    public LanguageController(LocaleResolver localeResolver) {
        this.localeResolver = localeResolver;
    }

    @GetMapping("/language/{language}")
    public String change(@PathVariable String language, HttpServletRequest request, HttpServletResponse response) {
        if (!Translator.LANGUAGES.contains(language)) {
            // -> página de erro 404 (veja ErrorController)
            throw new ResponseStatusException(HttpStatus.NOT_FOUND);
        }
        // define o cookie de idioma
        localeResolver.setLocale(request, response, Locale.of(language));
        return "redirect:" + originPage(request);
    }

    // -----------------------------------------------------------------------
    // a página anterior, conforme o cabeçalho HTTP "Referer" enviado pelo
    // navegador. Guardamos apenas o caminho (/schedule?...): redirecionar para
    // um endereço completo fornecido pela requisição permitiria enviar
    // o usuário a outro site (a chamada falha de "open redirect").
    // -----------------------------------------------------------------------
    private static String originPage(HttpServletRequest request) {
        String referer = request.getHeader(HttpHeaders.REFERER);
        if (referer == null) {
            return "/";
        }
        try {
            URI url = new URI(referer);
            String path = url.getRawPath();
            // "//site.com/..." seria entendido pelo navegador como um endereço
            // em OUTRO site: também recusado
            if (!url.isAbsolute() || path == null || !path.startsWith("/") || path.startsWith("//")
                    || path.startsWith("/language/")) {
                return "/";
            }
            return url.getRawQuery() == null ? path : path + "?" + url.getRawQuery();
        } catch (URISyntaxException e) {
            return "/";
        }
    }
}

Este é, mais ou menos, o controller do Exemplo 22: a mesma rota [/language/{language}], o mesmo cookie do [CookieLocaleResolver], o mesmo retorno à página de origem por meio do cabeçalho [Referer]. Vamos comentá-lo:

  • linha 32: [@Controller] transforma a classe em um controller MVC, detectado na inicialização e criado pelo [Spring] como um bean (um objeto cuja criação o Spring gerencia e que ele pode injetar em outros lugares, veja o Exemplo 06);
  • linhas 35–39: o controller recebe, por meio de injeção de dependência, o [LocaleResolver] definido em [config/WebConfig.java]. A classe tem apenas um construtor: o Spring o chama fornecendo os beans solicitados, sem necessidade de anotá-lo com [@Autowired]. Todos os controllers da aplicação são escritos dessa maneira;
  • linhas 41–42: a rota [GET /language/{language}]. [@PathVariable] associa o parâmetro [language] ao segmento [{language}] da URL (veja o Exemplo 02). A action também recebe a requisição e a resposta do servidor ([Servlet]): basta declará-las como parâmetros, e o Spring MVC as fornecerá;
  • linhas 43–46: um idioma desconhecido ([/language/de]) retorna uma página 404. A action não gera essa página: ela lança uma [ResponseStatusException], que o Spring MVC converte em uma resposta de erro 404; o servidor então encaminha a requisição para [/error], onde o [ErrorController] (adiante) gera a página;
  • linha 48: [setLocale] define o cookie de idioma (seu nome, [rdvmedecins_language], sua duração de um ano e suas opções [HttpOnly] e [SameSite=Lax] foram definidos em [WebConfig]). A cada requisição subsequente, o [CookieLocaleResolver] lê esse cookie e define o idioma da requisição;
  • linha 49: retorno à página anterior. O prefixo [redirect:] solicita ao Spring MVC uma resposta 302;
  • linhas 58–76: a página anterior, com base no cabeçalho [Referer]. Mantemos apenas o caminho e os parâmetros ([/schedule?doctorId=1&day=...]): redirecionar para uma URL completa fornecida pela requisição poderia enviar o usuário a outro site (uma vulnerabilidade conhecida como “open redirect”);
  • Linhas 68–71: são rejeitados, resultando em um retorno à raiz do site: um endereço relativo, um caminho que começa com [//] (que o navegador interpretaria como o endereço de outro site) e uma página chamada [/language/...], que faria o navegador entrar em loop. [getRawPath] e [getRawQuery] restauram o caminho e os parâmetros como apareciam na URL, ainda codificados ([%20]...), prontos para serem reinseridos em uma URL.

Vamos verificar isso com o [curl]:

curl -i -H "Referer: http://localhost:8081/login" http://localhost:8081/language/en
1
2
3
4
HTTP/1.1 302
Set-Cookie: rdvmedecins_language=en; Path=/; Max-Age=31536000; Expires=Sat, 25 Sep 2027 16:47:10 GMT; HttpOnly; SameSite=Lax
Location: http://localhost:8081/login
Content-Length: 0

O cookie é definido e o navegador é redirecionado para a página de login, que agora será exibida em inglês.

11.16.2. controllers/ScheduleController.java

A página principal da aplicação e o controller com mais funcionalidades. Vamos analisá-lo seção por seção.

11.16.2.1. As URLs da página

// =========================================================================
// controllers/ScheduleController.java
// -------------------------------------------------------------------------
// A página da agenda: escolha de um médico e de um dia, agenda desse
// médico nesse dia, reserva e cancelamento de consultas.
//
//   GET  /schedule?doctorId=1&day=2026-09-23               a página
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        a mesma página, com
//                                                          o diálogo de reserva
//                                                          do horário 7 aberto
//   POST /schedule/book                                    cria uma consulta
//   POST /schedule/cancel                                  cancela uma consulta
//
// A página inteira é descrita pela sua URL: ela pode ser recarregada, colocada
// nos favoritos, o botão "Voltar" do navegador pode ser usado - sem uma linha
// de JavaScript.
//
// O que cada um vê e pode fazer:
//
//   | papel          | horário reservado exibido         | Reservar             | Cancelar |
//   |================|===================================|======================|==========|
//   | ADMIN, DOCTOR  | nome do paciente                  | para um paciente     | sim      |
//   |                |                                   | escolhido em uma lista |          |
//   | USER (paciente)| "Booked", ou SEU nome se for      | para si mesmo, se    | não (*)  |
//   |                | a sua própria consulta            | não tiver consulta   |          |
//   |                |                                   | futura               |          |
//
//   (*) o paciente cancela sua consulta na sua página "My area".
//
// CONFIDENCIALIDADE: para um paciente, o nome dos OUTROS pacientes não é
// simplesmente ocultado pela view - ele nunca é colocado no modelo
// passado à view. O HTML enviado ao navegador, portanto, não o contém,
// nem mesmo oculto (um simples "Exibir código-fonte da página" o revelaria de outra forma).
//
// Sem reserva no passado: o botão "Book" aparece apenas
// para hoje e os dias seguintes (e a camada de negócio a recusaria
// de qualquer forma).
//
// Segurança: todas as URLs /schedule exigem um usuário autenticado
// (veja SecurityConfig: anyRequest().authenticated()). @PreAuthorize em uma
// action exige, além disso, um dos papéis listados. Sem token válido: volta para
// /login; papel insuficiente: página 403.
// =========================================================================
package rdvmedecins.controllers;

import java.time.LocalDate;
import java.util.List;
import java.util.Locale;
import java.util.Optional;

import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import jakarta.servlet.http.HttpServletRequest;
import rdvmedecins.auth.ConnectedUser;
import rdvmedecins.domain.DoctorDaySchedule;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Slot;
import rdvmedecins.entities.Person;
import rdvmedecins.entities.Role;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.Dates;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.ViewModels.ScheduleModel;
import rdvmedecins.models.ViewModels.ScheduleView;
import rdvmedecins.models.ViewModels.ScheduleRowView;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.OptionView;
import rdvmedecins.models.ViewModels.BookingView;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Utils;

@Controller
@RequestMapping("/schedule")
public class ScheduleController {

    // o que o controller sabe sobre o usuário, para decidir a exibição
    private record Rights(
            boolean manager, // ADMIN ou DOCTOR
            Client patient, // o cliente conectado (papel USER), senão null
            boolean patientCanBook) { // USER sem consulta futura
    }

    // os campos ocultos doctorId / day, comuns aos dois formulários POST
    private record ScheduleRequest(int doctorId, LocalDate day) {
    }

    private final ApplicationModel application;

    public ScheduleController(ApplicationModel application) {
        this.application = application;
    }
  • linhas 7–12: as rotas da página. Observe que a janela de reserva não é aberta pelo [JavaScript]: é um parâmetro da URL ([book=7]) que instrui o servidor a renderizar a página com a janela aberta. O botão “Reservar” é, portanto, simplesmente um link. A página inteira é descrita por sua URL: você pode recarregá-la, adicioná-la aos favoritos ou usar o botão “Voltar” do navegador;
  • linhas 20–28: o que cada papel vê e pode fazer. Esta tabela é a “especificação” da página: o restante do controller a implementa;
  • linhas 30–33: a regra de privacidade, à qual voltaremos: os nomes dos outros pacientes não são ocultados pela view; eles nunca são enviados ao navegador;
  • linhas 39–42: segurança. A classe não tem anotações de segurança: é a configuração do [Spring Security] ([anyRequest().authenticated()], veja [config/SecurityConfig.java]) que exige um usuário logado para qualquer endereço [/schedule...]. As actions que exigem adicionalmente um papel são anotadas com [@PreAuthorize] (veja o Exemplo 26);
  • linhas 84–86: [@RequestMapping("/schedule")], aplicada à classe, é o prefixo de todas as rotas do controller (veja o Exemplo 02);
  • linhas 88–93: o que o controller sabe sobre o usuário logado, calculado uma vez por requisição (veja o método [rights], adiante). Trata-se de um record (veja “O domínio: a agenda”), cujos acessores são [rights.manager()], [rights.patient()]... Este [record] é privado e declarado dentro da classe: ele é usado somente por essa classe. Um gerente é um ADMIN ou um DOCTOR; [patient] só é preenchido para um cliente (papel USER);
  • linhas 95–97: o médico e a data lidos dos campos ocultos dos dois formulários POST da página, depois de convertidos;
  • linhas 99–103: o serviço [ApplicationModel] (veja “A camada web: serviços comuns”), recebido pelo construtor.

11.16.2.2. GET /schedule

    // -----------------------------------------------------------------------
    // GET /schedule
    // Os parâmetros da URL são lidos brutos (request.getParameter), para
    // distinguir um parâmetro AUSENTE (null) de um parâmetro VAZIO (?doctorId=).
    // -----------------------------------------------------------------------
    @GetMapping
    public String show(@AuthenticationPrincipal Jwt token, HttpServletRequest request,
            Locale locale, Model model) {
        String error = null;
        ConnectedUser user = Utils.user(token);
        Rights rights = rights(user);

        // o dia: o da URL se for válido, senão hoje
        LocalDate day = Dates.today();
        String rawDay = request.getParameter("day");
        if (rawDay != null) {
            Optional<LocalDate> requestedDay = Utils.validDate(rawDay);
            if (requestedDay.isPresent()) {
                day = requestedDay.get();
            } else {
                error = "ERRORS.INVALID_DATE";
            }
        }
        boolean dayBookable = !day.isBefore(Dates.today());

        // o médico: o da URL; na falta dele, para um médico conectado, ele mesmo
        String rawDoctorId = request.getParameter("doctorId");
        Integer doctorId = Utils.positiveInteger(rawDoctorId);
        if (rawDoctorId == null && user.role() == Role.DOCTOR) {
            doctorId = application.getDoctorByUserId(user.userId()).map(d -> d.getId()).orElse(null);
        }

        // a lista suspensa dos médicos ("final": utilizável na lambda)
        final Integer chosenId = doctorId;
        List<OptionView> doctors = application.getAllDoctors().stream()
                .map(d -> option(d, d.getId().equals(chosenId)))
                .toList();

        // a agenda, se um médico for escolhido (e a data válida)
        ScheduleView schedule = null;
        if (doctorId != null && error == null) {
            Optional<DoctorDaySchedule> doctorSchedule = application.getDoctorDaySchedule(doctorId, day);
            if (doctorSchedule.isEmpty()) {
                error = "ERRORS.DOCTOR_NOT_FOUND";
            } else {
                schedule = scheduleView(doctorSchedule.get(), rights, dayBookable, locale);
            }
        }
  • linha 7: [@GetMapping] sem caminho: a action responde a [GET /schedule], o prefixo do controller;
  • Linhas 8–9: os parâmetros da action, todos fornecidos pelo Spring MVC. [@AuthenticationPrincipal Jwt token] é o token [JWT] do usuário logado, já verificado pelo [Spring Security] (veja “Autenticação”); [request] fornece acesso aos parâmetros brutos da URL; [locale] é o idioma da requisição, definido pelo [CookieLocaleResolver]; [model] é o modelo, que a action preenche para a view. A action não declara os parâmetros [doctorId] ou [day]: ela os lê por conta própria a partir da requisição ([HttpServletRequest], veja o Exemplo 05): [request.getParameter] retorna [null] para um parâmetro ausente e uma string vazia para um parâmetro vazio ([?doctorId=]). Esses dois casos devem ser distinguidos (veja adiante);
  • Linhas 11–12: o usuário logado e suas permissões. [Utils.user] (pasta [web]) lê as informações do token (claims: ID, login, nome, papel) e as converte em um objeto [ConnectedUser];
  • linhas 15–25: a data solicitada, se válida; caso contrário, hoje. Se o parâmetro [day] estiver ausente, retorna hoje sem mensagem de erro. Se estiver presente, mas inválido ([day=2026-02-30]), gera uma mensagem de erro. [Utils.validDate] retorna um [Optional] (veja “A camada DAO”), que é testado com [isPresent()] antes de extrair seu valor com [get()]. As reservas só podem ser feitas a partir de hoje ([dayBookable]);
  • linhas 28–32: o médico solicitado. [Utils.positiveInteger] retorna um inteiro estritamente positivo, ou [null] se o valor estiver ausente, vazio ou inválido: seu tipo é [Integer], a versão “objeto” do tipo [int], que pode ser [null]. Se o parâmetro [doctorId] estiver ausente da URL, um médico logado vê sua própria agenda: essa é a sua página inicial. Se estiver vazio ([doctorId=], a opção “escolha um médico” da lista), nenhuma agenda é exibida. Linha 31: [map(d -> d.getId())] converte o [Optional<Doctor>] retornado por [getDoctorByUserId] em um [Optional<Integer>], e [orElse(null)] extrai o valor dele, ou [null] se estiver vazio;
  • linhas 35–38: as opções da lista suspensa de médicos, lidas do cache do [ApplicationModel]; a opção do médico solicitado é selecionada (veja o método [option] no final do arquivo). [stream()] converte a lista em um stream, que o [map] processa elemento por elemento e que o [toList()] converte de volta em uma lista. [d -> option(...)] é um lambda: uma função anônima, definida no próprio local. Um lambda só pode usar uma variável local se ela nunca for modificada depois: é por isso que [doctorId], modificado na linha 31, é copiado na linha 35 para uma variável [final] (que não pode ser modificada). Na linha 37, os dois valores [Integer] são comparados por [equals], que compara seus valores, e não por [==], que compararia dois objetos: uma armadilha clássica do [Java];
  • Linhas 41–49: a agenda só é calculada se um médico estiver selecionado e a data for válida. Um ID de médico desconhecido gera uma mensagem, e não uma página de erro. A agenda calculada pela camada de negócio (um objeto [DoctorDaySchedule] da pasta [domain]) é formatada pelo método [scheduleView], comentado adiante.

11.16.2.3. A janela de reserva e o modelo da view

        // o diálogo de reserva: somente se o horário solicitado puder ser
        // reservado por este usuário
        BookingView booking = null;
        Integer slotId = Utils.positiveInteger(request.getParameter("book"));
        if (schedule != null && slotId != null) {
            Optional<ScheduleRowView> row = schedule.rows().stream()
                    .filter(r -> r.slotId() == slotId && r.bookable())
                    .findFirst();
            if (row.isPresent()) {
                booking = new BookingView(
                        row.get().slotId(),
                        row.get().time(),
                        rights.manager()
                                ? application.getAllClients().stream().map(c -> option(c, false)).toList()
                                : List.of(),
                        rights.patient() != null ? Utils.label(rights.patient()) : null);
            }
        }

        model.addAttribute("model", new ScheduleModel(
                "SCHEDULE.PAGE_TITLE",
                error == null ? null : Message.of(error),
                doctors,
                doctorId,
                Utils.iso(day),
                schedule,
                booking,
                doctorId != null ? scheduleUrl(doctorId, day, null) : "/schedule",
                patientInfo(rights, schedule)));
        return "schedule";
    }
  • linhas 3–8: o intervalo de horário para o qual a URL solicita uma reserva ([book=7]). Ele deve aparecer na agenda exibida e poder ser reservado por este usuário: uma URL criada manualmente (um intervalo no passado, um intervalo ocupado ou um intervalo pertencente a outro médico) não abre a janela. [filter] mantém apenas as linhas que satisfazem a condição, e [findFirst] retorna a primeira delas em um [Optional] (vazio se nenhuma for adequada);
  • linhas 9–17: o modelo da janela. Um gerente seleciona um paciente de uma lista (todos os clientes, lidos do cache); um paciente faz uma reserva para si mesmo: a janela simplesmente exibe seu nome. [List.of()] é uma lista vazia;
  • Linhas 20–29: o modelo da página, um [ScheduleModel] (veja [models/ViewModels.java]), armazenado no modelo sob o nome [model]. Os argumentos do construtor do [record] são listados na ordem de seus campos: a chave do título da página, um eventual erro (uma [Message]: uma chave de tradução e seus parâmetros), os médicos, o médico selecionado, o dia no formato [yyyy-MM-dd], a agenda, a janela de reserva etc. [condition ? value1 : value2] é igual a [value1] se a condição for verdadeira e a [value2] caso contrário;
  • linha 28: o endereço da agenda exibida, sem a janela de reserva — este é o endereço do botão que fecha a janela;
  • linha 29: uma mensagem informativa para pacientes que já têm uma consulta futura: ela explica por que eles não veem um botão “Reservar”. Ela é calculada pelo método [patientInfo], no final do arquivo;
  • linha 30: o nome da view: [templates/schedule.html].

11.16.2.4. POST /schedule/book

    // -----------------------------------------------------------------------
    // POST /schedule/book   campos: doctorId, day, slotId, clientId
    //
    // Para um paciente (USER), o campo clientId é IGNORADO: ele sempre reserva
    // para si mesmo. Confiar em um campo enviado pelo
    // navegador permitiria a um paciente esperto reservar em nome de outro.
    //
    // Padrão "Post / Redirect / Get": seja qual for o resultado, não
    // construímos uma página aqui - colocamos uma mensagem flash e redirecionamos
    // para a agenda (veja o exemplo 20).
    // -----------------------------------------------------------------------
    @PostMapping("/book")
    @PreAuthorize("hasAnyRole('ADMIN', 'DOCTOR', 'USER')")
    public String book(
            @RequestParam(required = false) String doctorId,
            @RequestParam(required = false) String day,
            @RequestParam(required = false) String slotId,
            @RequestParam(required = false) String clientId,
            @AuthenticationPrincipal Jwt token,
            RedirectAttributes redirect) {
        ScheduleRequest req = readScheduleRequest(doctorId, day);
        Integer sltId = Utils.positiveInteger(slotId);
        if (req == null || sltId == null) {
            // -> página de "requisição inválida" (veja ErrorController)
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
        }
        ConnectedUser user = Utils.user(token);

        Optional<Client> client;
        if (user.isPatient()) {
            client = Optional.of(Utils.connectedPatient(application, user));
        } else {
            Integer cliId = Utils.positiveInteger(clientId);
            if (cliId == null) {
                // nenhum paciente escolhido: reabrimos o diálogo de reserva
                redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CHOOSE_PATIENT"));
                return "redirect:" + scheduleUrl(req.doctorId(), req.day(), sltId);
            }
            client = application.getClientById(cliId);
        }

        Optional<Slot> slot = application.getSlotById(sltId);
        FlashMessage flash;
        if (client.isEmpty()) {
            flash = FlashMessage.error("ERRORS.PATIENT_NOT_FOUND");
        } else if (slot.isEmpty() || slot.get().getDoctorId() != req.doctorId()) {
            flash = FlashMessage.error("ERRORS.SLOT_NOT_FOUND");
        } else {
            try {
                // as regras (não no passado, uma única consulta futura por
                // paciente, horário livre) são verificadas pela camada de negócio
                application.addAppointment(req.day(), slot.get(), client.get());
                flash = FlashMessage.success("SCHEDULE.BOOKED");
            } catch (BusinessException e) {
                // mesma regra, mas uma mensagem na 2ª pessoa quando é o próprio
                // paciente que reserva ("You already have..." em vez
                // de "This patient..."). As outras exceções (anomalias
                // reais) não são capturadas: página 500.
                flash = e.getKey().equals("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT") && user.isPatient()
                        ? FlashMessage.error("SCHEDULE.ALREADY_BOOKED_INFO")
                        : FlashMessage.error(e.getKey(), e.getParams());
            }
        }
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, flash);
        return "redirect:" + scheduleUrl(req.doctorId(), req.day(), null);
    }
  • Linha 13: [@PreAuthorize] exige, além de um usuário logado, um dos papéis listados (veja o Exemplo 26). A anotação contém uma expressão, avaliada pelo [Spring Security] antes de o método ser chamado: [hasAnyRole('ADMIN', 'DOCTOR', 'USER')] é verdadeira se o usuário tiver um desses papéis. Aqui, ela não impõe nenhuma restrição adicional; documenta a regra e a protegeria caso surgisse um quarto papel;
  • linhas 15–18: os campos do formulário na janela de reserva (veja o Exemplo 11). [@RequestParam] vincula cada parâmetro do método ao campo de mesmo nome; [required = false]: um campo ausente resulta em [null] em vez de um erro 400 do Spring (MVC). Eles são recebidos como strings e depois convertidos com cuidado;
  • linha 20: [RedirectAttributes] é usado para exibir uma mensagem flash antes de um redirecionamento (veja o exemplo 20);
  • Linhas 21–26: o “médico” e o “dia” são campos ocultos do formulário; eles permitem que o usuário volte à agenda exibida. Se forem inválidos, a requisição não se originou de nossa página — foi criada manualmente. A exceção [ResponseStatusException(HttpStatus.BAD_REQUEST)] gera uma resposta 400, que o servidor converte em uma página de erro (veja [ErrorController]);
  • linhas 29–31: para um paciente, o campo [clientId] é ignorado — o sistema sempre faz a reserva para o próprio paciente. Confiar nesse campo, enviado pelo navegador, permitiria que um paciente malicioso fizesse uma reserva em nome de outra pessoa. [Utils.connectedPatient] identifica o cliente por meio do token; [Optional.of] o coloca em um [Optional], para que tenha o mesmo tipo que o da linha 39;
  • Linhas 33–38: um administrador que não selecionou um paciente é redirecionado para a janela de reserva (a URL com [book]), junto com uma mensagem flash de erro. [addFlashAttribute] armazena a mensagem nos atributos flash, que o [web/CookieFlashMapManager.java] transporta em um cookie até a próxima requisição;
  • linhas 42–47: o paciente deve existir, e o intervalo de horário deve existir e pertencer ao médico da agenda: não é possível reservar um intervalo de um médico com outro;
  • linha 52: as regras de negócio (não estar no passado, intervalo disponível, apenas uma consulta futura por paciente) são verificadas pela camada de lógica de negócio, que lança uma [BusinessException] em caso de rejeição;
  • Linhas 54–62: qualquer [BusinessException] torna-se uma mensagem flash de erro, com sua chave e seus parâmetros. Para um paciente, a mensagem “Este paciente já tem uma consulta futura” é substituída por uma mensagem na segunda pessoa. As outras exceções não são capturadas: são erros verdadeiros, que resultam em uma página de erro 500. (O [C#] tem um filtro de exceção para esse caso, [catch ... when], que não existe em [Java]: a condição é verificada no bloco [catch]);
  • Linhas 64–65: o esquema PRG: independentemente do resultado, uma mensagem flash é exibida e o usuário é redirecionado para a agenda, que exibirá a mensagem.

11.16.2.5. POST /schedule/cancel

    // -----------------------------------------------------------------------
    // POST /schedule/cancel   campos: appointmentId, doctorId, day
    // (um paciente cancela SUA consulta em "My area", não daqui)
    // -----------------------------------------------------------------------
    @PostMapping("/cancel")
    @PreAuthorize("hasAnyRole('ADMIN', 'DOCTOR')")
    public String cancel(
            @RequestParam(required = false) String appointmentId,
            @RequestParam(required = false) String doctorId,
            @RequestParam(required = false) String day,
            RedirectAttributes redirect) {
        ScheduleRequest req = readScheduleRequest(doctorId, day);
        Integer id = Utils.positiveInteger(appointmentId);
        if (req == null || id == null) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
        }
        Optional<Appointment> appointment = application.getAppointmentById(id);
        if (appointment.isEmpty()) {
            // já cancelada (por outra pessoa, ou clique duplo)
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.APPOINTMENT_NOT_FOUND"));
        } else {
            application.deleteAppointment(appointment.get());
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"));
        }
        return "redirect:" + scheduleUrl(req.doctorId(), req.day(), null);
    }
  • Linhas 5–6: o cancelamento é reservado aos administradores; um paciente cancela sua consulta em “Minha área” (veja [PatientAreaController]). Um paciente que enviasse essa requisição receberia uma página 403: o [Spring Security] rejeita a chamada do método, e seu tratador de rejeição (veja [SecurityConfig]) responde com um erro 403, que o servidor encaminha para [/error];
  • linhas 12–16: as mesmas verificações da reserva;
  • linhas 17–20: uma consulta que já foi cancelada (por duplo clique ou por cancelamento feito por outro gerente) retorna uma mensagem de erro, e não uma página de erro;
  • linhas 21–25: exclusão, seguida do esquema PRG.

Com o cookie de token de um paciente logado (o do Sr. Jean MARTIN, que o leitor copiará de seu navegador; veja “Autenticação”; ele é abreviado aqui como [...]), a requisição é rejeitada:

curl -i -b "rdvmedecins_jwt=..." -X POST http://localhost:8081/schedule/cancel -d "appointmentId=1&doctorId=1&day=2026-09-25"
1
2
3
4
5
6
7
8
HTTP/1.1 403
Content-Type: text/html;charset=UTF-8

<!doctype html>
...
      <h1 class="display-4 text-danger">403</h1>
      <p class="lead">Your role does not allow you to access this page.</p>
...

11.16.2.6. Permissões, agenda formatada e funções utilitárias

    // -----------------------------------------------------------------------
    // quem está conectado e o que ele pode fazer nesta página?
    // -----------------------------------------------------------------------
    private Rights rights(ConnectedUser user) {
        if (!user.isPatient()) {
            return new Rights(true, null, false);
        }
        Client patient = Utils.connectedPatient(application, user);
        List<Appointment> upcoming = application.getClientUpcomingAppointments(patient.getId());
        return new Rights(false, patient, upcoming.isEmpty());
    }

    // -----------------------------------------------------------------------
    // a agenda do médico, formatada para a view - e filtrada pelos direitos
    // -----------------------------------------------------------------------
    private ScheduleView scheduleView(DoctorDaySchedule doctorSchedule, Rights rights, boolean dayBookable,
            Locale locale) {
        int doctorId = doctorSchedule.doctor().getId();
        LocalDate day = doctorSchedule.day();
        List<ScheduleRowView> rows = doctorSchedule.doctorDaySlots().stream().map(dds -> {
            Slot slot = dds.slot();
            Appointment appointment = dds.appointment();
            boolean free = appointment == null;
            // a consulta do paciente conectado?
            boolean mine = appointment != null && rights.patient() != null && appointment.getClientId().equals(rights.patient().getId());
            return new ScheduleRowView(
                    slot.getId(),
                    Utils.time(slot),
                    free,
                    // O ponto da confidencialidade: um paciente recebe o nome apenas
                    // de SUA consulta; para as outras, null (a view exibe "Booked")
                    appointment != null && (rights.manager() || mine) ? Utils.label(appointment.getClient()) : null,
                    mine,
                    free && dayBookable && (rights.manager() || rights.patientCanBook()),
                    scheduleUrl(doctorId, day, slot.getId()),
                    appointment != null && rights.manager() ? appointment.getId() : null);
        }).toList();
        return new ScheduleView(Utils.label(doctorSchedule.doctor()), Utils.formatDay(day, locale), rows);
    }

    // - funções utilitárias

    // os campos ocultos doctorId / day dos formulários POST; null se forem inválidos
    private static ScheduleRequest readScheduleRequest(String rawDoctorId, String rawDay) {
        Integer doctorId = Utils.positiveInteger(rawDoctorId);
        Optional<LocalDate> day = Utils.validDate(rawDay);
        return doctorId == null || day.isEmpty() ? null : new ScheduleRequest(doctorId, day.get());
    }

    private static String scheduleUrl(int doctorId, LocalDate day, Integer book) {
        String url = "/schedule?doctorId=" + doctorId + "&day=" + Utils.iso(day);
        return book == null ? url : url + "&book=" + book;
    }

    private static OptionView option(Person p, boolean selected) {
        return new OptionView(p.getId(), Utils.label(p), selected);
    }

    // -----------------------------------------------------------------------
    // a mensagem informativa de um paciente que já tem uma consulta futura
    // (por que não há botão "Book"), ou null. Inútil se SUA
    // consulta aparece na agenda exibida (em azul): é o caso logo
    // depois de ele a ter acabado de reservar, quando a mensagem estaria fora de lugar.
    // -----------------------------------------------------------------------
    private static String patientInfo(Rights rights, ScheduleView schedule) {
        if (rights.patient() == null || rights.patientCanBook()) {
            return null;
        }
        boolean appointmentShown = schedule != null && schedule.rows().stream().anyMatch(ScheduleRowView::mine);
        return appointmentShown ? null : "SCHEDULE.ALREADY_BOOKED_INFO";
    }
}
  • linhas 4–11: um administrador tem todas as permissões; um paciente pode fazer uma reserva se não tiver consultas futuras;
  • linhas 16–17: a agenda calculada pela camada de negócio é convertida em elementos de array, um por intervalo de horário ([ScheduleRowView]);
  • linha 20: a função lambda passada para [map] ocupa várias linhas aqui: seu corpo é um bloco delimitado por chaves, terminando com um [return];
  • linha 25: [mine] determina se a consulta pertence ao paciente logado;
  • linha 28: a view recebe apenas dados já formatados ([8:00 - 8:20]); ela não tem mais nada a calcular;
  • linha 32: o controle de privacidade da aplicação. O nome do paciente é incluído no modelo apenas para um administrador ou para o paciente a quem a consulta pertence. Para todos os demais, o modelo contém [null], e a view exibe “Reservado”. O nome não é simplesmente ocultado pela view: ele nunca é enviado ao navegador, e “Exibir código-fonte da página” não o revelaria;
  • linhas 34–36: o que a view deve exibir, conforme determinado pelo controller: o botão “Reservar” (intervalo disponível, data não passada e usuário autorizado a reservar), seu link (a URL da página, junto com [book]) e o botão “Cancelar” ([appointmentId] só é preenchido para um administrador). A view não toma nenhuma decisão: ela segue essas instruções;
  • linha 38: a agenda completa: o médico, o dia, formatado no idioma da requisição (“Friday 25 September 2026”), as linhas;
  • linhas 44–48: os valores dos dois campos ocultos comuns aos formulários POST: um [ScheduleRequest], ou [null] se forem inválidos;
  • linhas 50–53: a URL da agenda de um médico em um determinado dia, possivelmente com a janela de reserva aberta. Todos os redirecionamentos do controller a geram por meio deste método: as URLs da página são escritas em um único lugar;
  • linhas 55–57: uma opção de lista suspensa (ID, rótulo, seleção), tanto para médicos quanto para clientes: o parâmetro é do tipo [Person], a classe-mãe de ambas as entidades;
  • Linhas 59–71: a mensagem informativa para o paciente que já tem uma consulta futura. Ela não é enviada se essa consulta aparecer na agenda exibida: o nome do paciente em azul é suficiente, e esta é justamente a página que o paciente vê logo após reservar, na qual a mensagem “Você já tem uma consulta futura” estaria fora de lugar. Linha 69: [anyMatch] indica se pelo menos uma linha do fluxo satisfaz a condição; [ScheduleRowView::mine] é uma referência a método: o equivalente ao lambda [r -> r.mine()].

Eis o que o navegador do Sr. Jean (papel USER) recebe para a agenda da Sra. PELISSIER, que tem dois intervalos reservados (trecho):

curl -b "rdvmedecins_jwt=..." "http://localhost:8081/schedule?doctorId=1&day=2026-09-26"
  <div class="card p-3">
    <h5>Schedule for Saturday 26 September 2026 - Mme Marie PELISSIER</h5>
...
        <tr>
          <td>8:20 - 8:40</td>
          <td>
            <span class="badge text-bg-secondary">Booked</span>
          </td>
          <td>
          </td>
        </tr>
...
        <tr>
          <td>9:00 - 9:20</td>
          <td>
            <span class="badge text-bg-primary">Mr Jean MARTIN</span>
          </td>
          <td>
          </td>
        </tr>

O intervalo das 8h20 está reservado por outro paciente: o nome dele não aparece em lugar nenhum da página. O intervalo das 9h00 é a consulta do Sr. MARTIN: o nome dele aparece em azul. Como ele já tem uma consulta futura, nenhum botão “Reservar” é exibido. A mensagem informativa (“Você já tem uma consulta futura...”) não aparece aqui, pois essa consulta está bem diante dele; ela aparece na agenda de outro dia ou de outro médico para explicar a ausência dos botões.

11.16.3. controllers/PersonsControllerBase.java

// =========================================================================
// controllers/PersonsControllerBase.java
// -------------------------------------------------------------------------
// A gestão dos médicos e a dos clientes (reservadas ao ADMIN) são
// IDÊNTICAS: mesma lista, mesmo formulário, mesmas regras. Em vez de
// escrever as mesmas actions duas vezes, nós as escrevemos uma vez nesta
// classe ABSTRATA e GENÉRICA, da qual DoctorsController
// (@RequestMapping("/doctors")) e ClientsController
// (@RequestMapping("/clients")) herdam. Cada subclasse só precisa fornecer sua
// "configuração": quais métodos chamar, quais rótulos exibir.
//
// As rotas definidas AQUI (@GetMapping("/add")...) são herdadas e
// completam a rota da subclasse. Obtemos, portanto, para cada uma:
//
//   GET  /doctors                    lista
//   GET  /doctors/add                formulário vazio
//   POST /doctors/add                criação
//   GET  /doctors/{id}/edit          formulário pré-preenchido
//   POST /doctors/{id}/edit          edição
//   POST /doctors/{id}/delete        exclusão
//
// (e as mesmas URLs sob /clients). As views também são comuns:
// templates/persons/list.html e templates/persons/form.html.
//
// Uma classe abstrata nunca é um bean: somente suas subclasses concretas,
// anotadas com @Controller, são controllers.
//
// SEGURANÇA: @PreAuthorize("hasRole('ADMIN')") é colocada NESTA classe,
// e não nas subclasses. Para decidir qual regra se aplica a uma
// action, o Spring Security olha a anotação do método e depois a da
// classe que DECLARA o método - aqui, PersonsControllerBase. Colocada
// somente em DoctorsController, a anotação seria ignorada para as
// actions herdadas: um USER poderia abrir /doctors!
// =========================================================================
package rdvmedecins.controllers;

import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.function.BiFunction;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.Supplier;

import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import jakarta.validation.Valid;
import rdvmedecins.entities.Person;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.PersonForm;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.models.ViewModels.FormState;
import rdvmedecins.models.ViewModels.PersonFormModel;
import rdvmedecins.models.ViewModels.PersonListModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.PersonView;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Validation;

@PreAuthorize("hasRole('ADMIN')")
public abstract class PersonsControllerBase<T extends Person> {

    // -----------------------------------------------------------------------
    // o que cada subclasse deve fornecer. Os cinco últimos campos são
    // FUNÇÕES (interfaces funcionais de java.util.function): a
    // subclasse armazena nelas referências de método, application::getAllDoctors...
    // -----------------------------------------------------------------------
    protected record PersonsConfig<T>(
            String url, // "/doctors" ou "/clients"
            PersonKeys keys,
            Supplier<List<T>> list, // () -> lista
            Function<Integer, Optional<T>> find, // id -> pessoa
            Function<PersonData, T> add, // dados -> pessoa criada
            BiFunction<Integer, PersonData, T> edit, // (id, dados) -> pessoa editada
            IntConsumer delete) { // id -> nada
    }

    protected abstract PersonsConfig<T> config();

    // as views comuns
    private static final String LIST_VIEW = "persons/list";
    private static final String FORM_VIEW = "persons/form";

    // -----------------------------------------------------------------------
    // GET /doctors (ou /clients)
    // -----------------------------------------------------------------------
    @GetMapping
    public String list(Model model) {
        PersonsConfig<T> config = config();
        List<PersonView> persons = config.list().get().stream()
                .map(p -> new PersonView(p.getTitle(), p.getFirstName(), p.getLastName(), login(p),
                        config.url() + "/" + p.getId() + "/edit",
                        config.url() + "/" + p.getId() + "/delete"))
                .toList();
        model.addAttribute("model", new PersonListModel(config.keys().title(), null, config.keys(),
                config.url() + "/add", persons));
        return LIST_VIEW;
    }

    // -----------------------------------------------------------------------
    // GET /doctors/add
    // -----------------------------------------------------------------------
    @GetMapping("/add")
    public String addForm(Model model) {
        return showForm(model, null, PersonValues.empty(), Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /doctors/add
    // [form] foi preenchido E validado pelo Spring MVC (@Valid): o
    // BindingResult que o segue diz se a entrada está correta.
    // -----------------------------------------------------------------------
    @PostMapping("/add")
    public String add(@Valid PersonForm form, BindingResult result, Model model,
            RedirectAttributes redirect) {
        if (result.hasErrors()) {
            return showForm(model, null, enteredValues(form), Validation.errorsOf(result),
                    null, null);
        }
        try {
            T person = config().add().apply(data(form));
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.success(config().keys().added(), messageParams(person)));
            return "redirect:" + config().url();
        } catch (BusinessException e) {
            return showBusinessError(model, redirect, null, enteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // GET /doctors/{id}/edit
    // {id:\d+}: o id deve ser composto de dígitos - /doctors/abc/edit
    // não corresponde a nenhuma rota (página 404)
    // -----------------------------------------------------------------------
    @GetMapping("/{id:\\d+}/edit")
    public String editForm(@PathVariable int id, Model model) {
        T person = config().find().apply(id)
                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
        PersonValues values = new PersonValues(person.getTitle(), person.getFirstName(), person.getLastName(),
                login(person), person.getVersion());
        return showForm(model, id, values, Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/edit
    // -----------------------------------------------------------------------
    @PostMapping("/{id:\\d+}/edit")
    public String edit(@PathVariable int id, @Valid PersonForm form, BindingResult result,
            Model model, RedirectAttributes redirect) {
        if (result.hasErrors()) {
            return showForm(model, id, enteredValues(form), Validation.errorsOf(result),
                    null, null);
        }
        try {
            T person = config().edit().apply(id, data(form));
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.success(config().keys().edited(), messageParams(person)));
            return "redirect:" + config().url();
        } catch (BusinessException e) {
            return showBusinessError(model, redirect, id, enteredValues(form), e);
        }
    }

    // -----------------------------------------------------------------------
    // POST /doctors/{id}/delete
    // (a confirmação "Are you sure?" é solicitada antes de o formulário ser
    // enviado, veja static/js/app.js)
    // -----------------------------------------------------------------------
    @PostMapping("/{id:\\d+}/delete")
    public String delete(@PathVariable int id, RedirectAttributes redirect) {
        Optional<T> person = config().find().apply(id);
        FlashMessage flash;
        try {
            config().delete().accept(id);
            flash = FlashMessage.success(config().keys().deleted(), messageParams(person.orElse(null)));
        } catch (BusinessException e) {
            flash = FlashMessage.error(e.getKey(), e.getParams());
        }
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, flash);
        return "redirect:" + config().url();
    }

    // - métodos privados

    // id null: formulário de criação; senão: formulário de edição.
    // errors: campo -> chave da mensagem; error: a mensagem no rodapé da página;
    // otherFields: campos adicionais a destacar em vermelho
    private String showForm(Model model, Integer id, PersonValues values,
            Map<String, String> errors, String error, List<String> otherFields) {
        PersonsConfig<T> config = config();
        boolean creating = id == null;
        FormState state = Validation.state(errors, otherFields);
        model.addAttribute("model", new PersonFormModel(
                creating ? config.keys().add() : config.keys().edit(),
                Validation.pageMessage(errors, error == null ? null : Message.of(error)),
                values,
                state,
                creating,
                creating ? config.url() + "/add" : config.url() + "/" + id + "/edit",
                config.url()));
        return FORM_VIEW;
    }

    // uma regra de negócio recusou a escrita: exibimos o formulário de novo,
    // com a entrada do usuário e a mensagem da camada de negócio
    private String showBusinessError(Model model, RedirectAttributes redirect, Integer id,
            PersonValues values, BusinessException e) {
        if (e.getKey().equals("ERRORS.DOCTOR_NOT_FOUND") || e.getKey().equals("ERRORS.PATIENT_NOT_FOUND")) {
            // excluído nesse meio tempo por outro ADMIN: volta para a lista
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error(e.getKey()));
            return "redirect:" + config().url();
        }
        // a mensagem vai no rodapé da página; os campos afetados, se houver, são
        // destacados em vermelho para que o usuário veja de imediato o que corrigir
        return showForm(model, id, values, Map.of(), e.getKey(),
                Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
    }

    // o que o usuário digitou (senha excluída: nunca a enviamos de
    // volta ao navegador)
    private static PersonValues enteredValues(PersonForm f) {
        return new PersonValues(
                f.getTitle() == null ? "" : f.getTitle(),
                f.getFirstName() == null ? "" : f.getFirstName(),
                f.getLastName() == null ? "" : f.getLastName(),
                f.getLogin() == null ? "" : f.getLogin(),
                f.getVersion());
    }

    // o formulário validado -> os dados esperados pela camada de negócio
    private static PersonData data(PersonForm f) {
        return new PersonData(f.getTitle(), f.getLastName(), f.getFirstName(), f.getLogin(), f.getPassword(),
                f.getVersion());
    }

    // {name} e {login} das mensagens de "adicionado / editado / excluído"
    private static Map<String, String> messageParams(Person person) {
        return person == null
                ? Map.of("name", "", "login", "")
                : Map.of("name", person.getFirstName() + " " + person.getLastName(), "login", login(person));
    }

    private static String login(Person p) {
        return p.getUser() == null ? "" : p.getUser().getLogin();
    }
}

O tratamento de médicos e clientes é idêntico. Em vez de escrever dois controllers semelhantes, escrevemos suas actions uma só vez, em uma classe-mãe abstrata e genérica. Vamos comentar este código:

  • linhas 15–20: as rotas geradas para os médicos; as mesmas existem em [/clients];
  • linhas 22–23: as views também são compartilhadas (arquivo [templates/persons]);
  • linhas 25–26: a classe não é anotada com [@Controller] e, por ser abstrata, não poderia ser instanciada de qualquer forma: apenas suas subclasses [DoctorsController] e [ClientsController] são beans e recebem requisições;
  • Linhas 28–33 e linha 70: a restrição aos papéis ADMIN e [@PreAuthorize("hasRole('ADMIN')")] é aplicada a esta classe. Quando aplicada a uma classe, a anotação vale para todos os seus métodos. No entanto, para determinar qual regra se aplica a uma action, o [Spring Security] verifica a anotação do método e depois a da classe que declara o método. Ora, as actions [list], [add]... são declaradas aqui, em [PersonsControllerBase], e são apenas herdadas pelo [DoctorsController]. Se aplicada ao [DoctorsController], a anotação seria ignorada para elas: um paciente (USER) poderia abrir [/doctors]. Isso difere do [ASP.NET Core MVC], em que o atributo [[Authorize(Roles = "ADMIN")]] de uma subclasse também se aplica às actions herdadas;
  • linha 71: a classe é abstrata ([abstract]: não é possível criar um objeto dela; ela existe apenas para ser derivada) e genérica: [T] é um parâmetro de tipo, que cada subclasse substitui por [Doctor] ou [Client]. [T extends Person] é uma restrição: [T] deve ser [Person] ou uma de suas classes derivadas; o código pode, portanto, usar [p.getFirstName()] ou [p.getUser()], que são comuns a todas as pessoas;
  • Linhas 78–86: a configuração fornecida por cada subclasse, na forma de um [record]: a URL base, os textos (chaves de tradução, agrupadas no [record], [PersonKeys], e [models/ViewModels.java]) e cinco funções a chamar para listar, pesquisar, adicionar, modificar e excluir. Uma função armazenada em uma variável tem um tipo que é uma interface funcional do pacote [java.util.function] (veja “A camada de negócio”): [Supplier<R>] (sem parâmetros, retorna um [R], método [get]), [Function<P, R>] (um parâmetro: [P]; retorna um [R]; método: [apply]), [BiFunction<P1, P2, R>] (dois parâmetros), [IntConsumer] (um [int]; não retorna nada; método [accept]). [protected]: [record] é visível apenas para a classe e suas subclasses (e para o pacote);
  • linha 88: um método abstrato: cada subclasse deve implementá-lo para especificar sua configuração;
  • linhas 91–92: as duas views, designadas por seu caminho na pasta [templates];
  • linhas 97–108: a listagem. As anotações de roteamento aplicadas aos métodos de uma classe-mãe são herdadas: combinadas com o [@RequestMapping("/doctors")] da subclasse, resultam em [GET /doctors]. [config.list().get()] chama a função especificada na configuração. Para cada pessoa, o modelo contém os valores de URL para seus botões Editar e Excluir;
  • linhas 113–116: o formulário vazio. [Map.of()] é um dicionário vazio: sem erro;
  • Linhas 123–138: a adição, em três etapas, como no Exemplo 28. O parâmetro [form] foi preenchido pelo Spring MVC com os campos enviados, depois validado com base em suas anotações ([@NotBlank], [@Size]..., veja [models/Forms.java]) porque está anotado com [@Valid] (veja o Exemplo 19). O resultado da validação está contido no parâmetro [BindingResult], que vem logo em seguida: uma entrada inválida reexibe o formulário, com os valores informados e uma mensagem abaixo de cada campo incorreto; uma entrada válida é passada à camada de negócio, e então o navegador é redirecionado para a lista, com uma mensagem flash (PRG); uma rejeição pela camada de negócio (um nome duplicado, um login já em uso) reexibe o formulário;
  • Linhas 145–152: o formulário de edição, pré-preenchido. [{id:\\d+}] é uma variável de caminho associada a uma expressão regular: o identificador deve ser composto de dígitos ([\d+], com [\] duplicada na string [Java]). [/doctors/abc/edit] não corresponde, portanto, a nenhuma rota, resultando em uma página 404. Um usuário inexistente também resulta em um 404: [orElseThrow] extrai o valor do [Optional]ou, se ele estiver vazio, lança a exceção gerada pelo lambda. O número de versão, um campo oculto do formulário, será usado para o bloqueio otimista (veja o Exemplo 28);
  • linhas 157–172: a atualização, seguindo o mesmo padrão da inserção;
  • linhas 179–191: a exclusão. A pessoa é recuperada previamente para exibir seu nome na mensagem de sucesso ([orElse(null)]: a pessoa, ou [null] se ela não existia). Uma rejeição da camada de negócio (um médico que tem consultas) resulta em uma mensagem flash de erro na página de listagem;
  • Linhas 198–212: o formulário, tanto para criação ([id] é equivalente a [null]) quanto para modificação: apenas o título e o endereço de correspondência mudam. [Validation.state] e [Validation.pageMessage] (pasta [web]) preparam os erros por campo, os campos a serem destacados em vermelho e a mensagem na parte inferior da página;
  • linhas 216–227: uma pessoa que foi excluída nesse meio-tempo (por outro administrador) é exibida na lista; os demais erros de negócio reexibem o formulário, com a mensagem de rodapé e os campos pertinentes destacados em vermelho ([Validation.BUSINESS_ERROR_FIELDS] associa cada código de erro aos campos correspondentes: [firstName] e [lastName] para um homônimo);
  • linhas 231–238: os valores a serem reexibidos — nunca a senha;
  • linhas 241–244: os dados transmitidos à camada de negócio;
  • linhas 247–251: os parâmetros [{name}] e [{login}] para as mensagens de sucesso: o nome e o sobrenome da pessoa, e seu login;
  • linhas 253–255: o login da conta associada (uma string vazia se a conta estivesse ausente, por precaução: todos têm uma conta).

11.16.4. controllers/DoctorsController.java

// =========================================================================
// controllers/DoctorsController.java
// -------------------------------------------------------------------------
// Gestão dos médicos (somente papel ADMIN). Todas as actions são
// herdadas de PersonsControllerBase: resta apenas dizer O QUE
// chamar e QUAIS rótulos exibir.
//
// A restrição ao papel ADMIN é colocada na classe pai (veja o comentário
// "SEGURANÇA" de PersonsControllerBase).
// =========================================================================
package rdvmedecins.controllers;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import rdvmedecins.entities.Doctor;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.web.ApplicationModel;

@Controller
@RequestMapping("/doctors")
public class DoctorsController extends PersonsControllerBase<Doctor> {

    private final PersonsConfig<Doctor> config;

    public DoctorsController(ApplicationModel application) {
        // application::getAllDoctors: uma "referência de método", o método
        // getAllDoctors do objeto application, armazenado em uma variável
        this.config = new PersonsConfig<>(
                "/doctors",
                new PersonKeys(
                        "DOCTORS.TITLE",
                        "DOCTORS.ADD",
                        "DOCTORS.EDIT",
                        "DOCTORS.EMPTY",
                        "DOCTORS.DELETE_CONFIRM",
                        "DOCTORS.ADDED",
                        "DOCTORS.UPDATED",
                        "DOCTORS.DELETED"),
                application::getAllDoctors,
                application::getDoctorById,
                application::addDoctor,
                application::editDoctor,
                application::deleteDoctor);
    }

    @Override
    protected PersonsConfig<Doctor> config() {
        return config;
    }
}
  • linhas 8–9: a restrição ao papel ADMIN é feita pela classe-mãe, pelo motivo explicado acima;
  • linhas 20–22: um controller ([@Controller]) cujas rotas começam todas com [/doctors]. Ele herda ([extends]) de [PersonsControllerBase<Doctor>]: o tipo [T] da classe-mãe torna-se [Doctor];
  • linhas 26–45: o construtor recebe o [ApplicationModel] por injeção e cria a configuração de uma vez por todas: a URL base e as chaves de tradução específicas dos médicos;
  • linhas 40–44: as funções a chamar, que são métodos do ***[ApplicationModel]***. ***[application::getAllDoctors] é uma *referência a método: ela não chama o método; apenas se refere a ele. O compilador a converte em um valor da interface funcional esperada pelo [record] ([Supplier<List<Doctor>>] no caso da primeira), cujo método [get], chamará [application.getAllDoctors()]. Trata-se de uma notação abreviada para o lambda [() -> application.getAllDoctors()];
  • linha 29: [new PersonsConfig<>(...)]: o operador [<>], conhecido como operador “diamante”, permite ao compilador inferir o tipo genérico ([Doctor]);
  • Linhas 47–50: o método abstrato da classe-mãe, escrito aqui com [@Override], instrui o compilador a verificar se ele de fato sobrescreve um método da classe-mãe.

Como vimos na autenticação, um paciente que solicita [/doctors] recebe uma página 403: a proteção definida na classe-mãe está, portanto, funcionando. Observamos também que a barra de navegação dessa página de erro exibe o usuário (veja o método [currentUser] de [auth/AuthService.java]). Com o cookie de token do Sr. Jean MARTIN (papel USER):

curl -i -b "rdvmedecins_jwt=..." http://localhost:8081/doctors
HTTP/1.1 403
Content-Type: text/html;charset=UTF-8

<!doctype html>
...
      <span class="badge text-bg-light text-primary">USER</span>
      <span class="text-white">Jean MARTIN</span>
...
      <h1 class="display-4 text-danger">403</h1>
      <p class="lead">Your role does not allow you to access this page.</p>
...

11.16.5. controllers/ClientsController.java

// =========================================================================
// controllers/ClientsController.java
// -------------------------------------------------------------------------
// Gestão dos clientes (os PACIENTES do consultório), somente papel ADMIN.
// Mesmo princípio de DoctorsController (veja seus comentários).
// =========================================================================
package rdvmedecins.controllers;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import rdvmedecins.entities.Client;
import rdvmedecins.models.ViewModels.PersonKeys;
import rdvmedecins.web.ApplicationModel;

@Controller
@RequestMapping("/clients")
public class ClientsController extends PersonsControllerBase<Client> {

    private final PersonsConfig<Client> config;

    public ClientsController(ApplicationModel application) {
        this.config = new PersonsConfig<>(
                "/clients",
                new PersonKeys(
                        "CLIENTS.TITLE",
                        "CLIENTS.ADD",
                        "CLIENTS.EDIT",
                        "CLIENTS.EMPTY",
                        "CLIENTS.DELETE_CONFIRM",
                        "CLIENTS.ADDED",
                        "CLIENTS.UPDATED",
                        "CLIENTS.DELETED"),
                application::getAllClients,
                application::getClientById,
                application::addClient,
                application::editClient,
                application::deleteClient);
    }

    @Override
    protected PersonsConfig<Client> config() {
        return config;
    }
}

O mesmo controller, para os clientes: rota diferente (linhas 16–18), chaves de tradução diferentes, métodos diferentes do [ApplicationModel] (linhas 34–38).

11.16.6. controllers/RegistrationController.java

// =========================================================================
// controllers/RegistrationController.java
// -------------------------------------------------------------------------
// "Create a client account": um paciente que ainda não tem conta
// a cria ele mesmo. Rotas NÃO protegidas (ainda não se tem conta, por
// definição):
//
//   POST /register/access     botão "Create a client account" da
//                             página de autenticação: verifica o CAPTCHA
//                             DESTA página e depois abre o formulário
//   GET  /register            o formulário
//   POST /register            a criação, depois volta à página de login
//
// O fluxo é protegido contra robôs por UM CAPTCHA, o da página de
// autenticação:
//   1. o botão "Create a client account" envia o formulário de login
//      para /register/access; se o CAPTCHA for copiado corretamente, o servidor
//      emite um passe (veja auth/RegistrationPassService.java);
//   2. sem um passe válido, /register devolve à página de
//      autenticação - digitar a URL diretamente é inútil;
//   3. o passe é consumido na criação: um CAPTCHA resolvido
//      permite criar UMA conta;
//   4. além disso, o número de contas criadas por hora e por endereço IP é
//      limitado (veja auth/AttemptLimiterService.java).
//
// A conta criada é exatamente a que o ADMIN criaria pela
// página "Clients" (mesmo método da camada de negócio: addClient), exceto
// que o paciente ESCOLHE seu login e sua senha (obrigatórios,
// com confirmação).
// =========================================================================
package rdvmedecins.controllers;

import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.CookieValue;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;
import org.springframework.web.util.UriUtils;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import rdvmedecins.auth.CaptchaService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.auth.RegistrationPassService;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.RegistrationForm;
import rdvmedecins.models.ViewModels.RegistrationModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Validation;

@Controller
@RequestMapping("/register")
public class RegistrationController {

    private final ApplicationModel application;
    private final CaptchaService captchaService;
    private final AttemptLimiterService limiter;
    private final RegistrationPassService passes;

    public RegistrationController(ApplicationModel application, CaptchaService captchaService,
            AttemptLimiterService limiter, RegistrationPassService passes) {
        this.application = application;
        this.captchaService = captchaService;
        this.limiter = limiter;
        this.passes = passes;
    }

    // -----------------------------------------------------------------------
    // POST /register/access   campos: captchaId, captcha (os da
    // página de autenticação; login e senha, enviados também, são ignorados)
    // -----------------------------------------------------------------------
    @PostMapping("/access")
    public String access(@RequestParam(required = false) String captchaId,
            @RequestParam(required = false) String captcha,
            HttpServletRequest request, HttpServletResponse response, RedirectAttributes redirect) {
        String ip = AuthController.ipAddress(request);

        // contas demais criadas recentemente a partir deste endereço: inútil ir além
        long minutes = limiter.registrationBlockMinutes(ip);
        if (minutes > 0) {
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.error("ERRORS.TOO_MANY_ACCOUNTS", Map.of("minutes", String.valueOf(minutes))));
            return "redirect:/login";
        }

        // CAPTCHA ausente ou errado: volta à página de autenticação, com
        // uma nova imagem (uma falha conta como falha de login)
        if (!captchaService.verify(captchaId, captcha)) {
            limiter.loginFailure(ip, "");
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
            return "redirect:/login";
        }

        // CAPTCHA correto: emitimos o passe e abrimos o formulário
        response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.cookie(passes.issue()).toString());
        return "redirect:/register";
    }

    // -----------------------------------------------------------------------
    // GET /register
    // @CookieValue: o valor do cookie com esse nome (null se ele estiver ausente)
    // -----------------------------------------------------------------------
    @GetMapping
    public String form(@CookieValue(name = RegistrationPassService.COOKIE, required = false) String pass,
            Model model, RedirectAttributes redirect) {
        if (!passes.isValid(pass)) {
            return backToLogin(redirect);
        }
        return show(model, PersonValues.empty(), Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /register
    // O parâmetro [form] é preenchido e VALIDADO pelo Spring MVC antes
    // da chamada: o resultado da validação está em [result].
    // -----------------------------------------------------------------------
    @PostMapping
    public String create(@Valid RegistrationForm form, BindingResult result,
            @CookieValue(name = RegistrationPassService.COOKIE, required = false) String pass,
            HttpServletRequest request, HttpServletResponse response, Model model,
            RedirectAttributes redirect) {
        if (!passes.isValid(pass)) {
            return backToLogin(redirect);
        }
        String ip = AuthController.ipAddress(request);
        PersonValues values = new PersonValues(
                form.getTitle() == null ? "Mr" : form.getTitle(),
                form.getFirstName() == null ? "" : form.getFirstName(),
                form.getLastName() == null ? "" : form.getLastName(),
                form.getLogin() == null ? "" : form.getLogin(),
                null);

        // 1. contas demais criadas recentemente a partir deste endereço?
        long minutes = limiter.registrationBlockMinutes(ip);
        if (minutes > 0) {
            return show(model, values, Map.of(),
                    new Message("ERRORS.TOO_MANY_ACCOUNTS", Map.of("minutes", String.valueOf(minutes))), null);
        }

        // 2. todos os erros de entrada de uma vez (campos + confirmação):
        //    o usuário os corrige todos de uma só vez
        Map<String, String> errors = new HashMap<>(Validation.errorsOf(result));
        if (!errors.containsKey("password") && !errors.containsKey("confirmation")
                && !form.getPassword().equals(form.getConfirmation())) {
            errors.put("confirmation", "ERRORS.PASSWORDS_DIFFER");
        }
        if (!errors.isEmpty()) {
            return show(model, values, errors, null, null);
        }

        // 3. a criação (cliente + conta USER, em uma transação)
        try {
            application.addClient(new PersonData(form.getTitle(), form.getLastName(),
                    form.getFirstName(), form.getLogin(), form.getPassword(), null));
        } catch (BusinessException e) {
            // login ou nome + sobrenome já usados: o passe continua válido
            return show(model, values, Map.of(), Message.of(e.getKey()),
                    Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
        }

        // 4. o passe foi usado: ele não permitirá criar uma 2ª conta
        passes.consume(pass);
        response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.clearedCookie().toString());
        limiter.registrationSuccess(ip);

        // 5. volta à página de login, com o login pré-preenchido
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                FlashMessage.success("REGISTRATION.DONE", Map.of("login", form.getLogin())));
        return "redirect:/login?login=" + UriUtils.encodeQueryParam(form.getLogin(), StandardCharsets.UTF_8);
    }

    // - métodos privados

    // nenhum passe válido: volta à página de autenticação
    private static String backToLogin(RedirectAttributes redirect) {
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
        return "redirect:/login";
    }

    // o formulário; nunca uma senha devolvida ao navegador
    private static String show(Model model, PersonValues values, Map<String, String> errors,
            Message error, List<String> otherFields) {
        model.addAttribute("model", new RegistrationModel("REGISTRATION.TITLE",
                Validation.pageMessage(errors, error), values, Validation.state(errors, otherFields)));
        return "registration";
    }
}

Vamos comentar este código:

  • linhas 14–24: proteção contra bots, em quatro etapas. O CAPTCHA e o limitador de tentativas foram abordados no Exemplo 27, junto com a autenticação;
  • linhas 66–81: as rotas [/register...] são declaradas públicas no [SecurityConfig] ([permitAll()]), e o controller não tem anotações ([@PreAuthorize]): suas páginas estão abertas a todos. Ele recebe quatro serviços por injeção;
  • linhas 87–90: o botão “Criar uma conta de paciente” da página de login envia o formulário de login para este endereço (atributo [formaction]; veja o Exemplo 21). Somente os campos do CAPTCHA são lidos;
  • linha 91: o endereço IP do navegador, obtido por meio de um método estático de [AuthController];
  • linhas 94–99: contas demais criadas a partir deste endereço na última hora: redireciona para a página de login, com uma mensagem em pop-up indicando o número de minutos de espera. [Map.of("minutes", ...)] gera o dicionário de parâmetros da mensagem;
  • linhas 103–107: um CAPTCHA ausente ou incorreto conta como uma tentativa de login malsucedida (com nome de usuário vazio): um robô não pode tentar indefinidamente. O retorno à página de login exibe uma nova imagem;
  • linhas 110–111: o CAPTCHA está correto: um token (veja [auth/RegistrationPassService.java]) é armazenado em um cookie por meio de um cabeçalho [Set-Cookie] adicionado à resposta, e o navegador é redirecionado para o formulário;
  • linhas 118–125: o formulário, mas somente com um token válido. Digitar diretamente o endereço [/register] não produz nenhum efeito. [@CookieValue] vincula o parâmetro [pass] ao valor do cookie com esse nome ([null] se ele estiver ausente, graças a [required = false]);
  • linhas 132–136: criação. O formulário [RegistrationForm] (pasta [models]) foi vinculado e validado pelo Spring MVC ([@Valid]), com o resultado armazenado em [result];
  • linhas 137–139: o token é verificado novamente: a requisição POST pode ter sido enviada sem passar pelo formulário;
  • linhas 141–146: os valores a serem reexibidos em caso de erro, sem a senha. O título padrão é [Mr];
  • linhas 149–153: o prazo limite, verificado novamente no momento da criação;
  • linhas 157–164: erros de entrada, campo por campo (veja o Exemplo 19). [Validation.errorsOf] os reúne em um dicionário (campo, chave da mensagem), copiado para um [HashMap] para que possa ser complementado. A correspondência entre a senha e sua confirmação — que envolve dois campos — é verificada aqui manualmente; ela só é testada se esses dois campos estiverem corretos individualmente. Todos os erros são informados juntos: o usuário os corrige de uma só vez;
  • linhas 167–174: criação do cliente e de sua conta USER, usando o método da camada de negócio empregado por ADMIN. Se um nome de usuário ou uma combinação de nome e sobrenome já estiver em uso, o formulário é reexibido com os campos correspondentes destacados em vermelho; o token continua válido;
  • linhas 177–179: o token foi utilizado: ele é consumido no lado do servidor e seu cookie é excluído. A criação é, por fim, contabilizada no limite por hora;
  • linhas 182–184: retorno à página de login, com o nome de usuário preenchido, junto com uma mensagem de sucesso. [UriUtils.encodeQueryParam] codifica o nome de usuário para que ele possa ser incluído em uma URL;
  • linhas 190–193: sem um pass, retorno à página de login com uma mensagem;
  • linhas 196–201: o formulário, preparado por [Validation], semelhante aos dos médicos e dos clientes. Um método declarado como [static] não usa nenhum campo do objeto; ele pode ser chamado sem ele.

11.16.7. controllers/PatientAreaController.java

// =========================================================================
// controllers/PatientAreaController.java
// -------------------------------------------------------------------------
// As páginas PESSOAIS do paciente (papel USER), as que ele vê logo
// após fazer login:
//
//   GET  /my-area                  página inicial: [Manage my account],
//                                  [View a schedule], e sua consulta futura
//   POST /my-area/cancel           cancela SUA consulta
//   GET  /my-account               formulário de edição da sua conta
//   POST /my-account               edição
//   POST /my-account/delete        exclusão da conta (e de suas consultas)
//
// Regra de ouro deste controller: o paciente em questão é SEMPRE o do
// token (Utils.connectedPatient), nunca um identificador enviado pelo
// navegador. Um paciente não pode, portanto, nem ver, nem editar, nem cancelar o que
// pertence a outro paciente, mesmo construindo ele mesmo suas requisições.
//
// Qualquer edição ou exclusão da conta exige a senha ATUAL:
// alguém que encontrasse uma sessão deixada aberta não poderia
// nem alterar a senha, nem excluir a conta. Os erros de senha atual
// são contados como falhas de login (mesmo limite).
// =========================================================================
package rdvmedecins.controllers;

import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import rdvmedecins.auth.AuthService;
import rdvmedecins.auth.AttemptLimiterService;
import rdvmedecins.entities.Client;
import rdvmedecins.entities.Appointment;
import rdvmedecins.business.PersonData;
import rdvmedecins.business.BusinessException;
import rdvmedecins.models.Forms.MyAccountForm;
import rdvmedecins.models.ViewModels.AreaModel;
import rdvmedecins.models.ViewModels.Message;
import rdvmedecins.models.ViewModels.MyAccountModel;
import rdvmedecins.models.ViewModels.AppointmentView;
import rdvmedecins.models.ViewModels.PersonValues;
import rdvmedecins.web.ApplicationModel;
import rdvmedecins.web.FlashMessage;
import rdvmedecins.web.Utils;
import rdvmedecins.web.Validation;

@Controller
@PreAuthorize("hasRole('USER')")
public class PatientAreaController {

    private final ApplicationModel application;
    private final AuthService authService;
    private final AttemptLimiterService limiter;

    public PatientAreaController(ApplicationModel application, AuthService authService,
            AttemptLimiterService limiter) {
        this.application = application;
        this.authService = authService;
        this.limiter = limiter;
    }

    // -----------------------------------------------------------------------
    // GET /my-area
    // -----------------------------------------------------------------------
    @GetMapping("/my-area")
    public String area(@AuthenticationPrincipal Jwt token, Locale locale, Model model) {
        Client patient = patient(token);
        List<AppointmentView> appointments = application.getClientUpcomingAppointments(patient.getId()).stream()
                .map(a -> new AppointmentView(
                        a.getId(),
                        Utils.formatDay(a.getDay(), locale),
                        Utils.time(a.getSlot()),
                        Utils.label(a.getSlot().getDoctor()),
                        // link para a agenda do médico nesse dia: o paciente vê seu nome ali
                        "/schedule?doctorId=" + a.getSlot().getDoctorId() + "&day=" + Utils.iso(a.getDay())))
                .toList();
        model.addAttribute("model", new AreaModel("AREA.TITLE", null, Utils.label(patient), appointments));
        return "area";
    }

    // -----------------------------------------------------------------------
    // POST /my-area/cancel   campo: appointmentId
    // -----------------------------------------------------------------------
    @PostMapping("/my-area/cancel")
    public String cancelAppointment(@RequestParam(required = false) String appointmentId, @AuthenticationPrincipal Jwt token,
            RedirectAttributes redirect) {
        Client patient = patient(token);
        Integer id = Utils.positiveInteger(appointmentId);
        Optional<Appointment> appointment = id == null ? Optional.empty() : application.getAppointmentById(id);
        // uma consulta que não existe e a de OUTRO paciente recebem
        // a mesma resposta: não revelamos nada sobre as consultas dos outros
        if (appointment.isEmpty() || !appointment.get().getClientId().equals(patient.getId())) {
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.APPOINTMENT_NOT_FOUND"));
        } else {
            application.deleteAppointment(appointment.get());
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"));
        }
        return "redirect:/my-area";
    }

    // -----------------------------------------------------------------------
    // GET /my-account
    // -----------------------------------------------------------------------
    @GetMapping("/my-account")
    public String accountForm(@AuthenticationPrincipal Jwt token, Model model) {
        Client patient = patient(token);
        PersonValues values = new PersonValues(patient.getTitle(), patient.getFirstName(), patient.getLastName(),
                patient.getUser().getLogin(), patient.getVersion());
        return show(model, values, Map.of(), null, null);
    }

    // -----------------------------------------------------------------------
    // POST /my-account
    // -----------------------------------------------------------------------
    @PostMapping("/my-account")
    public String editAccount(@Valid MyAccountForm form, BindingResult result,
            @AuthenticationPrincipal Jwt token, HttpServletRequest request, HttpServletResponse response,
            Model model, RedirectAttributes redirect) {
        Client patient = patient(token);
        PersonValues values = new PersonValues(
                form.getTitle() == null ? patient.getTitle() : form.getTitle(),
                form.getFirstName() == null ? "" : form.getFirstName(),
                form.getLastName() == null ? "" : form.getLastName(),
                form.getLogin() == null ? "" : form.getLogin(),
                form.getVersion());

        Map<String, String> errors = new HashMap<>(Validation.errorsOf(result));
        if (!errors.containsKey("password") && form.getPassword() != null
                && !form.getPassword().equals(form.getConfirmation())) {
            errors.put("confirmation", "ERRORS.PASSWORDS_DIFFER");
        }
        if (!errors.isEmpty()) {
            return show(model, values, errors, null, null);
        }

        // a senha atual
        Message passwordError = checkCurrentPassword(request, patient, form.getCurrentPassword());
        if (passwordError != null) {
            // senha errada: a mensagem também vai SOB o campo
            Map<String, String> fieldErrors = passwordError.key().equals("ERRORS.WRONG_CURRENT_PASSWORD")
                    ? Map.of("currentPassword", passwordError.key())
                    : Map.of();
            return show(model, values, fieldErrors, passwordError, null);
        }

        try {
            Client client = application.editClient(patient.getId(), new PersonData(form.getTitle(),
                    form.getLastName(), form.getFirstName(), form.getLogin(),
                    form.getPassword(), // null = inalterada
                    form.getVersion()));
            // o login e o nome de exibição estão NO token: emitimos um
            // novo, senão a barra de navegação manteria o nome antigo
            authService.setToken(response, client.getUser());
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("MY_ACCOUNT.UPDATED"));
            return "redirect:/my-area";
        } catch (BusinessException e) {
            return show(model, values, Map.of(), Message.of(e.getKey()),
                    Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
        }
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   campo: deletePassword
    // A conta, o cliente e TODAS as suas consultas desaparecem juntos,
    // depois o paciente é desconectado.
    // -----------------------------------------------------------------------
    @PostMapping("/my-account/delete")
    public String deleteAccount(@RequestParam(required = false) String deletePassword,
            @AuthenticationPrincipal Jwt token, HttpServletRequest request, HttpServletResponse response,
            RedirectAttributes redirect) {
        Client patient = patient(token);
        Message passwordError = checkCurrentPassword(request, patient, deletePassword);
        if (passwordError != null) {
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                    FlashMessage.error(passwordError.key(), passwordError.params()));
            return "redirect:/my-account";
        }
        application.deleteClient(patient.getId());
        AuthService.clearToken(response);
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("MY_ACCOUNT.DELETED"));
        return "redirect:/login";
    }

    // - métodos privados

    // o paciente do token
    private Client patient(Jwt token) {
        return Utils.connectedPatient(application, Utils.user(token));
    }

    // null se a senha atual estiver correta; senão, a mensagem de erro
    private Message checkCurrentPassword(HttpServletRequest request, Client patient, String password) {
        String ip = AuthController.ipAddress(request);
        String login = patient.getUser().getLogin();
        long minutes = limiter.loginBlockMinutes(ip, login);
        if (minutes > 0) {
            return new Message("ERRORS.TOO_MANY_ATTEMPTS", Map.of("minutes", String.valueOf(minutes)));
        }
        boolean ok = password != null && !password.isEmpty()
                && authService.validateUser(login, password).isPresent();
        if (!ok) {
            limiter.loginFailure(ip, login);
            return Message.of("ERRORS.WRONG_CURRENT_PASSWORD");
        }
        return null;
    }

    private static String show(Model model, PersonValues values, Map<String, String> errors,
            Message error, List<String> otherFields) {
        model.addAttribute("model", new MyAccountModel("MY_ACCOUNT.TITLE",
                Validation.pageMessage(errors, error), values, Validation.state(errors, otherFields)));
        return "account";
    }
}

Vamos analisar este código:

  • linhas 14–17: a regra de ouro deste controller: o paciente em questão é sempre aquele associado ao token, nunca um identificador enviado pelo navegador;
  • linhas 63–65: reservado aos pacientes. Aqui, [@PreAuthorize] na classe se aplica a todas as ações, já que todas estão declaradas nela. O controller não tem a anotação [@RequestMapping]: cada ação fornece sua URL completa, pois elas não compartilham um prefixo ([/my-area], [/my-account]);
  • linhas 81–95: a página “Minha área”. O método [patient] (abaixo) identifica o cliente com base no token; se a conta do cliente tiver sido excluída desde o login, ele lança uma exceção [InvalidSessionException], que [web/HtmlExceptionHandler.java] trata redirecionando o usuário de volta para a página de login. A data é formatada por [Utils.formatDay] no idioma da requisição (veja o Exemplo 22); cada consulta inclui um link para a agenda do médico naquele dia (linha 91);
  • linhas 100–115: cancelamento da consulta do paciente. Na linha 105, um identificador inválido retorna um [Optional] vazio ([Optional.empty()]). Uma consulta inexistente e uma pertencente a outro paciente (linha 108) recebem a mesma resposta: nenhuma informação é revelada sobre as consultas de outros pacientes;
  • Linhas 120–126: o formulário da conta, preenchido previamente com o número de versão (bloqueio otimista);
  • linhas 131–134: o processo de modificação, em três etapas: validação, verificação da senha atual, camada de negócio;
  • linhas 136–141: os valores a serem reexibidos em caso de erro — nunca as senhas;
  • linhas 143–150: erros de entrada. A nova senha é opcional (em branco: sem alteração); sua confirmação só é verificada se tiver sido informada;
  • linhas 153–160: a senha atual. Uma senha incorreta é sinalizada abaixo do campo e no final da página; um bloqueio (excesso de tentativas) é indicado apenas no final da página, junto com o número de minutos;
  • linhas 162–168: modificação pela camada de negócio, que aplica as mesmas regras que para ADMIN (unicidade, bloqueio otimista);
  • linha 169: o token contém o login e o nome de exibição: após uma alteração, um novo token é emitido; caso contrário, a barra de navegação manteria o nome antigo;
  • linhas 172–175: uma rejeição pela camada de negócio recarrega o formulário, com os campos correspondentes destacados em vermelho;
  • linhas 183–193: a exclusão da conta também exige a senha atual. Um erro é indicado por uma mensagem em pop-up na página da conta (PRG);
  • linhas 194–197: exclusão do registro, da conta e de todas as consultas (o método da camada de negócio usado por ADMIN), seguida de logout: o cookie do token é apagado;
  • linhas 203–205: o paciente do token;
  • linhas 208–222: verificação da senha atual. O método retorna [null] se a senha estiver correta; caso contrário, uma mensagem de erro (um [Message]: chave e parâmetros). A senha atual está sujeita às mesmas restrições que o login (veja o Exemplo 27): quem encontrar uma sessão deixada aberta não conseguirá alterar a senha, excluir a conta nem tentar adivinhar senhas indefinidamente. A verificação em si é feita por [AuthService]; uma falha é contabilizada como falha de login;
  • linhas 224–229: o formulário da conta.

11.16.8. controllers/ErrorController.java

// =========================================================================
// controllers/ErrorController.java
// -------------------------------------------------------------------------
// A página de erro (400, 403, 404, 405, 500...).
//
// Nunca se chega aqui por um link. Quando uma requisição termina em erro
// - uma exceção não tratada, um response.sendError(403), uma
// ResponseStatusException(NOT_FOUND)... - o servidor (Tomcat) ENCAMINHA (forward) a
// requisição ao endereço /error, para construir a página a retornar em vez
// de uma resposta vazia ou de um stack trace (veja o exemplo 24). Ele armazena
// no caminho o código de erro em um atributo da requisição.
//
// O Spring Boot já fornece um controller /error (BasicErrorController, a
// "Whitelabel Error Page"); ele se retira assim que um bean implementa
// a interface ErrorController, como este.
//
// @RequestMapping sem método HTTP: a action aceita todos os métodos -
// a requisição encaminhada mantém seu método original (um POST recusado continua POST).
// =========================================================================
package rdvmedecins.controllers;

import java.util.Map;

// (a interface ErrorController do Spring Boot tem o nome da nossa classe: escrita por extenso abaixo)
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;

import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import rdvmedecins.models.ViewModels.ErrorModel;

@Controller
public class ErrorController implements org.springframework.boot.webmvc.error.ErrorController {

    private static final Map<Integer, String> MESSAGES = Map.of(
            HttpServletResponse.SC_BAD_REQUEST, "ERRORS.BAD_REQUEST",
            HttpServletResponse.SC_FORBIDDEN, "ERRORS.FORBIDDEN",
            HttpServletResponse.SC_NOT_FOUND, "ERRORS.NOT_FOUND");

    @RequestMapping("/error")
    public String show(HttpServletRequest request, HttpServletResponse response, Model model) {
        // o código de erro original, armazenado pelo servidor na requisição
        Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        int code = status instanceof Integer c ? c : HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
        // a página mantém esse código (404 continua 404...); um código inesperado
        // (ou /error chamado diretamente) vira um erro 500
        if (code < 400 || code > 599) {
            code = HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
        }
        response.setStatus(code);
        model.addAttribute("model", new ErrorModel("ERROR_PAGE.TITLE", null, code,
                MESSAGES.getOrDefault(code, "ERRORS.SERVER_ERROR")));
        return "error";
    }
}

Este é o controller do Exemplo 24, com mensagens traduzidas:

  • linhas 6–11: você nunca chega a esta página por meio de um link. Quando uma requisição termina em erro (uma exceção não tratada, uma [ResponseStatusException], um [response.sendError(403)] do handler de rejeição do [Spring Security]...), o servidor [Tomcat] encaminha a requisição para o endereço [/error] para gerar a página a ser retornada, em vez de uma resposta vazia ou de uma pilha de chamadas;
  • linhas 13–15 e linhas 34–35: o [Spring Boot] já fornece um controller, [/error] ([BasicErrorController]), que gera a “Whitelabel Error Page”. Ele é removido assim que um bean implementa a interface [ErrorController] (importada na linha 24), como este;
  • linhas 37–40: a chave de mensagem para cada código de erro. [static final]: um único dicionário, criado quando a classe é carregada e nunca substituído; [Map.of] também o torna somente leitura;
  • linha 42: [@RequestMapping], que não especifica o método HTTP, aceita todos os métodos: uma requisição POST repassada para [/error] (por exemplo, um paciente tentando um cancelamento reservado aos administradores) continua sendo uma requisição POST;
  • Linhas 45–46: o código de erro original, que o servidor armazenou em um atributo da requisição chamado [RequestDispatcher.ERROR_STATUS_CODE]. O atributo é do tipo [Object]: [status instanceof Integer c] verifica se ele é de fato um [Integer] e, em caso afirmativo, o armazena na variável [c]. Caso contrário (endereço [/error] digitado manualmente), o código é 500;
  • linhas 49–51: um código HTTP que não é de erro é convertido em um erro 500;
  • linha 52: a página mantém o código de erro original (uma página desconhecida continua sendo uma resposta 404);
  • linhas 53–55: o template da página e o nome de sua view. [getOrDefault] retorna a chave associada ao código ou [ERRORS.SERVER_ERROR] para qualquer outro código (500, em particular).

11.17. Views

As views são escritas com [Thymeleaf] (veja os exemplos 13 a 16). Vamos relembrar o conceito: uma view é um verdadeiro arquivo HTML, enriquecido com atributos [th:...] que o [Thymeleaf] substitui ao gerar a página. Quando aberto diretamente em um navegador, sem servidor, o arquivo ainda é exibido, com seu texto de exemplo (“Mme Alice DURAND”, “8:00 – 8:20”): são os chamados “natural templates”. Os atributos usados no estudo de caso são os dos exemplos:

Atributo ou expressão
Função
[th:text="${model.day}"]
substitui o conteúdo do elemento pelo valor, com escape ([<] torna-se [&lt;])
[th:utext]
O mesmo que o anterior, sem escape (somente para a imagem do CAPTCHA)
[#{SCHEDULE.FREE}]
Uma mensagem traduzida (veja o Exemplo 22)
[#{BOOKING_DIALOG.SLOT('time', ${r.time})}]
uma mensagem com um parâmetro [{time}]
[#{${error.key}(${error.params})}]
uma mensagem cuja chave é ela própria um valor, com um dicionário de parâmetros
[th:if], [th:unless]
o elemento é escrito somente se a condição for verdadeira (falsa)
[th:each="row : ${rows}"]
o elemento é repetido para cada item da lista
[th:value], [th:href], [th:action]
Um atributo calculado
[th:selected], [th:autofocus]
um atributo booleano: escrito se o valor for verdadeiro, omitido caso contrário
[th:classappend]
adiciona uma classe CSS às do atributo [class]
[th:attr="data-confirmation=#{...}"]
qualquer atributo, calculado
[th:with="state=${model.state}"]
uma variável local ao elemento
[th:replace="~{fragments/flash :: flash}"]
substitui o elemento por um fragmento (veja o Exemplo 15)
[<th:block>]
uma tag que não deixa vestígio na página gerada
[<!--/* ... */-->]
um comentário, removido da página gerada

As views quase não têm decisões a tomar: seu template foi preparado pelos controllers na seção [record] do arquivo [models/ViewModels.java] (quais botões exibir, qual URL, quais chaves de tradução). Cada view começa com um comentário [<!--/* ... */-->] que descreve sua função; esses comentários não aparecem nas páginas enviadas ao navegador. Ao contrário do [Razor], o [Thymeleaf] não conhece o tipo do modelo: um erro de digitação em [${model.dayy}] não é detectado em tempo de compilação, mas sim quando a página é renderizada, resultando em uma exceção (e, portanto, em um erro 500).

Todas as views têm acesso às mesmas variáveis: [model], o modelo da página armazenado pelo controller; [user], [language] e [path] (o usuário logado, ou [null], o idioma da requisição, o caminho da URL solicitada), adicionadas ao modelo em todas as ações pelo método [@ModelAttribute] de [web/CommonModel.java]; e [flash], as eventuais mensagens flash: após um redirecionamento, o Spring MVC coloca automaticamente os atributos flash no modelo da requisição seguinte.

11.17.1. O template e os fragmentos

11.17.1.1. templates/layout.html

<!doctype html>
<!--/* =========================================================================
   templates/layout.html
   -------------------------------------------------------------------------
   The layout COMMON to all the pages (see example 15): a fragment
   [page] whose parameter [content] is the <main> block of the page requested
   by the controller (schedule.html, login.html...).

   Thymeleaf ESCAPES everything it displays with th:text (the characters
   < > & " ' become &lt; &gt;...): protection against HTML injection
   through a typed name, for example. To insert HTML as is, it must be
   requested explicitly (th:utext, see fragments/captcha.html).

   Messages: a success is displayed at the TOP of the page (flash fragment), an
   error at the BOTTOM, on a light pink background (errors fragment).

   The layout shares the variables of the page: [model] (the view model
   passed by the controller, see models/ViewModels.java), where it reads the
   title of the page; [language], [user], [path], added to all
   the views by web/CommonModel.java; [flash], the possible flash message.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:lang="${language}" th:fragment="page(content)">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <!--/* #{${key}}: a mensagem cuja chave é o VALOR da expressão ${key} */-->
  <title th:text="|#{${model.pageTitle}} - #{APP.TITLE}|">RdvMedecins</title>
  <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-4">
    <nav th:replace="~{fragments/navbar :: navbar}"></nav>
    <div th:replace="~{fragments/flash :: flash}"></div>
    <main th:replace="${content}"></main>
    <div th:replace="~{fragments/errors :: errors}"></div>
  </div>
  <!--/* o diálogo "Are you sure?", oculto enquanto não for necessário */-->
  <div th:replace="~{fragments/confirmation :: confirmation}"></div>
  <script src="/js/app.js"></script>
</body>
</html>

Este é o template do Exemplo 15. Toda página da aplicação começa com [<html th:replace="~{layout :: page(~{::main})}">]: ela é substituída pelo fragmento [page] deste template, ao qual passa seu próprio elemento [<main>].

  • Linhas 2–21: um comentário do [Thymeleaf]: [<!--/*] e [*/-->] delimitam o texto que o [Thymeleaf] remove da página gerada. Um navegador que abre o arquivo sem servidor o vê como um comentário HTML comum;
  • linha 22: [th:fragment="page(content)"] transforma todo o elemento [<html>] em um fragmento chamado [page], que recebe um parâmetro, [content]. [th:lang] escreve o atributo [lang] da página: o idioma da requisição ([fr] ou [en]);
  • linha 27: o título, traduzido, por exemplo, “Agenda - RdvMedecins”. As barras verticais [|...|] delimitam uma substituição literal: um texto em que as expressões são substituídas por seus valores. [#{${model.pageTitle}}] é a mensagem cuja chave é o valor de [${model.pageTitle}]: esse título é fornecido pelo controller no modelo de cada página (no Exemplo 15, a página o passava como parâmetro de fragmento);
  • linhas 28–29: as folhas de estilo, servidas pelo [Spring Boot] a partir da pasta [src/main/resources/static]: [Bootstrap] ([static/lib/bootstrap]) e a folha de estilo específica da aplicação;
  • linhas 33–36: a barra de navegação, a mensagem de sucesso (no topo), o elemento [<main>] da página solicitada ([th:replace="${content}"]: o elemento é substituído pelo fragmento recebido como parâmetro) e a área de erros (na parte inferior);
  • linhas 39–40: a janela de confirmação (oculta) e seu script (veja o Exemplo 21), carregado no final da página.

O início da página de login, como recebido pelo navegador:

curl -i http://localhost:8081/login
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8

<!doctype html>

<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <title>Login - RdvMedecins</title>
  <link rel="stylesheet" href="/lib/bootstrap/css/bootstrap.min.css">
...

Os comentários [<!--/* ... */-->] desapareceram, deixando apenas linhas vazias; os atributos [th:...] também desapareceram.

11.17.1.2. templates/fragments/navbar.html

<!--/* =========================================================================
   templates/fragments/navbar.html - a barra de navegação.

   Título, FR/EN, papel, nome, logout - e um menu cujas entradas
   dependem do papel: "Doctors" e "Patients" aparecem apenas para
   o ADMIN. É apenas uma comodidade de exibição: a proteção real é
   o @PreAuthorize dos controllers (um USER que digite /doctors à mão
   recebe uma página 403). Um paciente (USER) também tem seu menu "My area".

   O menu da página atual é destacado (classe "active"):
   [path] é a URL requisitada (veja web/CommonModel.java).
   ========================================================================= */-->
<nav xmlns:th="http://www.thymeleaf.org" th:fragment="navbar"
     class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0" th:text="#{APP.TITLE}">RdvMedecins</span>

  <ul class="navbar-nav me-auto" th:if="${user != null}">
    <li class="nav-item" th:if="${user.isPatient()}">
      <a class="nav-link" th:classappend="${#strings.startsWith(path, '/my-')} ? 'active'"
         href="/my-area" th:text="#{APP.MENU_MY_AREA}">My area</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" th:classappend="${#strings.startsWith(path, '/schedule')} ? 'active'"
         href="/schedule" th:text="#{APP.MENU_SCHEDULE}">Schedule</a>
    </li>
    <!--/* th:block: uma tag do Thymeleaf que não deixa vestígio no HTML */-->
    <th:block th:if="${user.isAdmin()}">
      <li class="nav-item">
        <a class="nav-link" th:classappend="${#strings.startsWith(path, '/doctors')} ? 'active'"
           href="/doctors" th:text="#{APP.MENU_DOCTORS}">Doctors</a>
      </li>
      <li class="nav-item">
        <a class="nav-link" th:classappend="${#strings.startsWith(path, '/clients')} ? 'active'"
           href="/clients" th:text="#{APP.MENU_PATIENTS}">Patients</a>
      </li>
    </th:block>
  </ul>
  <div class="me-auto" th:if="${user == null}"></div>

  <div class="d-flex align-items-center gap-2">
    <!--/* FR / EN: links simples (GET /language/fr), o idioma ativo destacado */-->
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      <a class="btn" th:classappend="${language == 'fr'} ? 'btn-light' : 'btn-outline-light'" href="/language/fr">FR</a>
      <a class="btn" th:classappend="${language == 'en'} ? 'btn-light' : 'btn-outline-light'" href="/language/en">EN</a>
    </div>

    <th:block th:if="${user != null}">
      <span class="badge text-bg-light text-primary" th:text="${user.role}">ADMIN</span>
      <span class="text-white" th:text="${user.name}">name</span>
      <!--/* logout é um POST: um formulário reduzido ao seu botão */-->
      <form method="post" action="/logout" class="m-0">
        <button type="submit" class="btn btn-sm btn-outline-light" th:text="#{APP.LOGOUT}">Log out</button>
      </form>
    </th:block>
  </div>
</nav>
  • linhas 13–14: o fragmento [navbar], inserido pelo template;
  • linha 17: o menu é exibido apenas para um usuário logado. Na página de login, [user] vale [null];
  • linhas 18–21: “Minha área”, somente para pacientes. [user.isPatient()] chama um método de [record] [ConnectedUser]: as expressões do [Thymeleaf] podem chamar métodos;
  • Linha 19: o menu da página atual é destacado (classe [active]). [#strings.startsWith] é uma função do objeto utilitário [#strings] do [Thymeleaf] (veja o Exemplo 14). [condition ? 'active'], sem a cláusula “else”, é avaliada como [null] se a condição for falsa, e [th:classappend] então não adiciona nada;
  • Linhas 27–36: “Médicos” e “Pacientes”, somente para ADMIN. [th:block] agrupa os dois elementos sob uma única condição, sem deixar tags na página. Trata-se apenas de uma conveniência de exibição: a proteção real vem do [@PreAuthorize] dos controllers (um USER que digitar manualmente [/doctors] recebe uma página 403, como vimos);
  • linha 38: se nenhum usuário estiver logado, um elemento vazio empurra os botões FR / EN para a direita da barra, assim como o menu faz;
  • linhas 43–44: os botões FR / EN são simplesmente links para [/language/fr] e [/language/en]; o do idioma ativo é destacado ([btn-light]). Aqui, a expressão condicional tem os dois ramos;
  • linhas 48–49: o papel e o nome do usuário, lidos do token;
  • linhas 51–53: o logout é uma requisição POST (veja o Exemplo 25), processada pelo [Spring Security] (veja [SecurityConfig]): um formulário reduzido a um único botão. Um link simples (GET), colocado em outro site, não conseguiria desconectar o usuário sem que ele soubesse.

11.17.1.3. templates/fragments/flash.html

<!--/* =========================================================================
   templates/fragments/flash.html - a mensagem de SUCESSO colocada pela ação
   anterior (consulta salva, médico adicionado...), exibida apenas
   uma vez, no topo da página (veja web/CookieFlashMapManager.java).
   Uma mensagem flash de ERRO é exibida no rodapé da página, por
   fragments/errors.html.

   #{${flash.key}(${flash.params})}: a mensagem cuja chave é
   flash.key, tendo como parâmetro o dicionário dos valores de {name},
   {login}... (veja web/Translator.java).
   ========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="flash"
     th:if="${flash != null and flash.successful()}" class="alert alert-success" role="status"
     th:text="#{${flash.key}(${flash.params})}">message</div>
  • linhas 12–14: a mensagem de sucesso exibida pela ação anterior, antes de um redirecionamento. [flash] é um [FlashMessage] (veja [web/FlashMessage.java]): um tipo (sucesso ou erro), uma chave de tradução e parâmetros. Este fragmento exibe apenas mensagens de sucesso; os erros são exibidos na parte inferior da página pelo fragmento seguinte. [role="status"] faz com que os leitores de tela anunciem a mensagem;
  • linha 14: [#{${flash.key}(${flash.params})}]: a mensagem com a chave [flash.key], tendo o dicionário [flash.params] como parâmetros (os valores de [{name}], [{login}]...). É o serviço [Translator] (veja “A camada web: serviços comuns”) que substitui esses parâmetros no texto.

11.17.1.4. templates/fragments/errors.html

<!--/* =========================================================================
   templates/fragments/errors.html - a zona de erro, no RODAPÉ de cada
   página, sobre um fundo rosa claro (classe .error-zone, veja static/css/styles.css).

   Ela reúne as duas fontes possíveis de erro:
     - model.error: o erro da página exibida (formulário recusado, login
       ou nome + sobrenome já usados, data inválida, senha incorreta...);
     - uma mensagem flash de erro, colocada pela ação anterior antes de um
       redirecionamento (horário já reservado, exclusão recusada...).

   th:with define variáveis locais ao elemento. Ele é colocado em um th:block
   ENVOLVENTE: no mesmo elemento, o Thymeleaf avalia th:if ANTES de
   th:with, e as variáveis ainda não existiriam. role="alert": um
   leitor de tela anuncia a mensagem assim que a página é exibida, mesmo que ela
   esteja no rodapé.
   ========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="errors"
          th:with="error=${model.error}, flashError=${flash != null and !flash.successful()} ? ${flash}">
  <div th:if="${error != null or flashError != null}" class="error-zone" role="alert">
    <div th:if="${error != null}" th:text="#{${error.key}(${error.params})}">page error</div>
    <div th:if="${flashError != null}" th:text="#{${flashError.key}(${flashError.params})}">flash error</div>
  </div>
</th:block>
  • linhas 5–9: a seção de erros reúne as duas fontes possíveis de erro: o erro da página ([model.error]) e uma mensagem de erro flash;
  • Linhas 17–18: [th:with] define duas variáveis locais. [error] é o erro da página; [flashError] é a mensagem flash, se for um erro, e [null] caso contrário (uma expressão condicional sem cláusula “else”, como na barra de navegação). Essas variáveis são definidas em um ***[th:block] que *envolve o elemento que as utiliza. Não é possível escrever [th:with] e ***[th:if] no mesmo elemento: o [Thymeleaf]* processa os atributos de um elemento em uma ordem fixa, que não depende da ordem em que são escritos, e [th:if] é avaliado antes de [th:with]**. A condição usaria variáveis que ainda não existem;
  • linha 19: o campo só é escrito se houver pelo menos uma mensagem. [role="alert"]: um leitor de tela anuncia a mensagem assim que a página é exibida, mesmo que ela esteja na parte inferior;
  • Linhas 20–21: as duas mensagens, traduzidas junto com seus parâmetros.

Por exemplo, para uma agenda solicitada com uma data inválida ([day=2026-02-30]), a parte inferior da página contém:

1
2
3
4
  <div class="error-zone" role="alert">
    <div>The requested date is not valid.</div>

  </div>

11.17.1.5. templates/fragments/confirmation.html

<!--/* =========================================================================
   templates/fragments/confirmation.html - o diálogo modal "Are you sure?".

   Ele substitui a caixa window.confirm() do navegador, que não pode ser
   estilizada nem traduzida (seus botões permanecem no idioma do
   navegador, não no da página).

   Um ÚNICO diálogo para a página inteira, oculto (d-none) no início. Seus
   rótulos são traduzidos aqui, pelo servidor, como o resto da página;
   o pequeno script static/js/app.js apenas o exibe, coloca nele
   a mensagem específica do formulário (atributo data-confirmation) e envia
   o formulário se o usuário confirmar.

   Mesmas classes Bootstrap do diálogo de reserva (fragments/booking.html).
   ========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="confirmation" id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title" th:text="#{CONFIRMATION.TITLE}">Confirmation</h5>
          <button type="button" class="btn-close" data-action="no" th:attr="aria-label=#{BOOKING_DIALOG.CLOSE_ARIA}"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <!--/* "No, go back" em vez de "Cancel": a pergunta às vezes
                 "Cancel this appointment?", e um botão "Cancel" seria ambíguo */-->
          <button type="button" class="btn btn-secondary" data-action="no" th:text="#{CONFIRMATION.NO}">No</button>
          <button type="button" class="btn btn-danger" data-action="yes" th:text="#{CONFIRMATION.YES}">Yes</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • Linhas 4–6: por que há uma janela na página em vez da caixa [window.confirm()] do navegador (veja o Exemplo 21)?
  • Linha 16: uma única janela para toda a página, inicialmente oculta pela classe [d-none] do [Bootstrap] ([display: none]). O script [static/js/app.js] a localiza pelo seu identificador;
  • Linhas 17–21: as classes do [Bootstrap] de uma janela modal: o fundo acinzentado ([modal-backdrop]) e, em seguida, a janela, que se torna visível ([show d-block]) assim que a classe [d-none] é removida. [role="alertdialog"], [aria-modal], [aria-labelledby] e [aria-describedby] descrevem a janela para os leitores de tela;
  • linha 24: o botão de fechar. Seu rótulo para leitores de tela ([aria-label]) é traduzido; [th:attr] calcula um atributo qualquer;
  • linha 27: o local da mensagem específica de cada formulário, colocada ali pelo script;
  • linhas 30–33: “Não, voltar” em vez de “Cancelar”: a pergunta às vezes é “Cancelar esta consulta?”. O atributo [data-action] informa ao script qual botão foi clicado.

11.17.1.6. templates/fragments/captcha.html

<!--/* =========================================================================
   templates/fragments/captcha.html - o CAPTCHA da página de autenticação
   (veja auth/CaptchaService.java). Ele protege tanto o login quanto
   o acesso à criação de conta (botão "Create a client account").
   Parâmetro: captcha, um objeto Captcha (id, svg).

   th:utext: a imagem SVG é inserida TAL COMO ESTÁ na página, sem
   escape. Isso é inofensivo aqui porque este SVG é construído pelo
   próprio servidor e não contém nada que venha do usuário - NUNCA
   faríamos isso com uma entrada.

   O campo oculto captchaId diz ao servidor QUAL CAPTCHA verificar; a resposta correta
   em si nunca é enviada ao navegador.
   "Another image" simplesmente recarrega a página ([path] = a URL atual).
   ========================================================================= */-->
<div xmlns:th="http://www.thymeleaf.org" th:fragment="captcha(captcha)" class="mb-3">
  <label class="form-label" for="captcha" th:text="#{CAPTCHA.LABEL}">Copy the characters</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" th:attr="aria-label=#{CAPTCHA.IMAGE_ALT}" th:utext="${captcha.svg}">image</div>
    <a class="small" th:href="${path}" th:text="#{CAPTCHA.NEW_IMAGE}">Another image</a>
  </div>
  <input type="hidden" name="captchaId" th:value="${captcha.id}">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
         spellcheck="false" required class="form-control">
  <div class="form-text" th:text="#{CAPTCHA.HELP}">help</div>
</div>
  • linha 16: um fragmento parametrizado: a página que o insere lhe passa o objeto [Captcha] (ID e imagem);
  • linha 19: a imagem SVG do CAPTCHA (veja o Exemplo 27) é inserida como está na página ([th:utext]), sem escape. Isso é seguro aqui porque esse SVG é gerado pelo próprio servidor e não contém nada fornecido pelo usuário; jamais faríamos isso com uma entrada do usuário. [role="img"] e [aria-label] descrevem a imagem para os leitores de tela;
  • linha 20: “Outra imagem” simplesmente recarrega a página ([path] é o caminho da URL atual): cada exibição gera um novo CAPTCHA;
  • linha 22: o campo oculto [captchaId] informa ao servidor qual CAPTCHA verificar; a resposta correta, porém, nunca é enviada ao navegador;
  • Linhas 23–24: os campos de entrada. [autocomplete="off"], [autocapitalize="off"], e [spellcheck="false"] impedem que o navegador sugira, coloque em maiúsculas ou corrija o que foi digitado.

11.17.1.7. templates/fragments/person-fields.html

<!--/* =========================================================================
   templates/fragments/person-fields.html - os campos de identidade (título,
   nome, sobrenome), comuns a três formulários: médico/cliente do ADMIN,
   "Create a client account" e "Manage my account".
   O fragmento lê a variável [model] da página que o insere (um
   FormView, veja models/ViewModels.java): valores, mensagem sob
   cada campo, campos destacados em vermelho.

   th:selected: um atributo booleano. O Thymeleaf escreve selected="selected"
   se o valor for true, e OMITE o atributo se for false.
   th:classappend: acrescenta uma classe às já presentes - aqui
   "is-invalid" (contorno vermelho do Bootstrap) para um campo recusado, ou nada.
   ========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="fields" th:with="state=${model.state}">
<div class="mb-3">
  <label class="form-label" for="title" th:text="#{PERSONS.TITLE_LABEL}">Title</label>
  <select id="title" name="title" class="form-select" th:classappend="${state.invalidClass('title')}">
    <option th:each="title : ${model.titles()}" th:value="${title.value}"
            th:selected="${title.selected}" th:text="${title.value}">Mr</option>
  </select>
  <div class="invalid-feedback" th:if="${state.errorOf('title') != null}"
       th:text="#{${state.errorOf('title')}}">error</div>
</div>

<div class="row g-3 mb-3">
  <div class="col-sm-6">
    <label class="form-label" for="firstName" th:text="#{PERSONS.FIRSTNAME_LABEL}">First name</label>
    <input id="firstName" name="firstName" type="text" maxlength="20" required
           class="form-control" th:classappend="${state.invalidClass('firstName')}" th:value="${model.values.firstName}">
    <div class="invalid-feedback" th:if="${state.errorOf('firstName') != null}"
         th:text="#{${state.errorOf('firstName')}}">error</div>
  </div>
  <div class="col-sm-6">
    <label class="form-label" for="lastName" th:text="#{PERSONS.LASTNAME_LABEL}">Last name</label>
    <input id="lastName" name="lastName" type="text" maxlength="20" required
           class="form-control" th:classappend="${state.invalidClass('lastName')}" th:value="${model.values.lastName}">
    <div class="invalid-feedback" th:if="${state.errorOf('lastName') != null}"
         th:text="#{${state.errorOf('lastName')}}">error</div>
  </div>
</div>
</th:block>

Os campos de título, nome e sobrenome são comuns a três formulários: o formulário de ADMIN (para médicos e clientes), o formulário de criação de conta e o formulário “Gerenciar minha conta”. Eles são escritos uma única vez, neste fragmento.

  • Linha 14: o fragmento [fields] é um [th:block]: ele não adiciona nenhuma tag ao redor dos campos. Ele lê a variável [model] da página que o insere: um modelo que implementa a interface [FormView] (veja [models/ViewModels.java]) e que, portanto, possui valores ([values]) e um estado ([state]). [th:with] armazena o estado em uma variável mais curta; não há [th:if] neste mesmo elemento;
  • linha 17: [th:classappend] adiciona a classe retornada por [state.invalidClass('title')]: [is-invalid] (a borda vermelha do [Bootstrap]) para um campo rejeitado, ou uma string vazia caso contrário;
  • linhas 18–19: os títulos ([Mr], [Mme], [Melle]), retornados pelo método [titles()] do modelo, um método default da interface [FormView]. Cada opção indica se está selecionada: [th:selected] escreve [selected="selected"] se o valor for verdadeiro e omite o atributo se for falso;
  • Linhas 21–22: a mensagem de erro do campo, se houver. [#{${state.errorOf('title')}}]: a mensagem cuja chave é retornada por [errorOf]. A classe [invalid-feedback] do [Bootstrap] exibe essa mensagem apenas abaixo de um campo [is-invalid];
  • Linhas 25–40: o nome e o sobrenome, no mesmo formato, lado a lado em telas razoavelmente largas ([col-sm-6]). [th:value] reexibe o que foi digitado; [maxlength] e [required] são recursos de conveniência para o usuário, pois a validação real é feita pelo servidor.

11.17.1.8. templates/fragments/booking.html

<!--/* =========================================================================
   templates/fragments/booking.html - o diálogo de reserva da
   agenda.

   As classes Bootstrap REAIS de um diálogo modal (.modal,
   .modal-backdrop...), tornadas visíveis "fixas no código" (show d-block) em vez de
   pelo JavaScript do Bootstrap. É o SERVIDOR que decide exibi-lo
   (parâmetro &book=... da URL), e fechá-lo equivale a seguir um link
   para a mesma página sem esse parâmetro.

   O fragmento lê diretamente a variável [model] da página que o insere
   (um ScheduleModel).
   ========================================================================= */-->
<th:block xmlns:th="http://www.thymeleaf.org" th:fragment="booking" th:with="booking=${model.booking}">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="/schedule/book" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title" th:text="#{BOOKING_DIALOG.TITLE}">Book this slot</h5>
        <a class="btn-close" th:href="${model.backUrl}" th:attr="aria-label=#{BOOKING_DIALOG.CLOSE_ARIA}"></a>
      </div>

      <div class="modal-body">
        <p th:text="#{BOOKING_DIALOG.SLOT('time', ${booking.time})}">Slot 8:00 - 8:20</p>

        <!--/* o que o servidor deve saber além do paciente escolhido */-->
        <input type="hidden" name="doctorId" th:value="${model.doctorId}">
        <input type="hidden" name="day" th:value="${model.day}">
        <input type="hidden" name="slotId" th:value="${booking.slotId}">

        <!--/* um paciente reserva para si mesmo: nenhuma lista para escolher
               (e o servidor ignora de qualquer modo um eventual clientId) */-->
        <p class="mb-0" th:if="${booking.patient != null}">
          <span th:text="#{BOOKING_DIALOG.PATIENT_LABEL}">Patient</span>:
          <strong th:text="${booking.patient}">Mme Alice DURAND</strong>
        </p>
        <th:block th:if="${booking.patient == null}">
          <label class="form-label" for="clientId" th:text="#{BOOKING_DIALOG.PATIENT_LABEL}">Patient</label>
          <select id="clientId" name="clientId" class="form-select" required autofocus>
            <option value="" th:text="#{BOOKING_DIALOG.CHOOSE_PATIENT}">-- choose a patient --</option>
            <option th:each="client : ${booking.clients}" th:value="${client.id}"
                    th:text="${client.label}">Mme Alice DURAND</option>
          </select>
        </th:block>
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" th:href="${model.backUrl}" th:text="#{BOOKING_DIALOG.CANCEL}">Cancel</a>
        <button type="submit" class="btn btn-primary" th:text="#{BOOKING_DIALOG.CONFIRM}">Confirm</button>
      </div>
    </form>
  </div>
</div>
</th:block>
  • Linhas 5–9: a janela de reserva usa as classes reais de uma janela modal do [Bootstrap], tornada visível de forma "fixa" ([show d-block]) em vez de pelo [JavaScript] do [Bootstrap]. É o servidor que decide se ela será exibida;
  • linha 14: o fragmento lê o modelo da página (um [ScheduleModel]); [th:with] armazena a janela ([model.booking]) na variável [booking];
  • linha 18: o formulário envia a reserva por POST para [/schedule/book];
  • linha 21: o botão de fechar é um link para a agenda, sem o parâmetro [book]: fechar a janela simplesmente exibe a página sem ele;
  • linha 25: “Horário 8:00 - 8:20”: uma mensagem com um parâmetro. Em [#{BOOKING_DIALOG.SLOT('time', ${booking.time})}], os parâmetros são fornecidos como pares (nome, valor): [{time}] é substituído pelo valor de [booking.time];
  • linhas 28–30: campos ocultos: o médico, o dia (para voltar à mesma agenda) e o horário;
  • linhas 34–37: um paciente faz a reserva para si mesmo: sem lista, apenas o seu nome (o servidor ignora qualquer [clientId] de qualquer maneira);
  • linhas 38–45: um administrador seleciona um paciente em uma lista — obrigatório ([required]) — que recebe o foco quando a página é aberta ([autofocus]);
  • linha 49: “Cancelar” também é um link para a página sem a janela pop-up.

11.17.2. As páginas

11.17.2.1. templates/login.html

<!doctype html>
<!--/* =========================================================================
   templates/login.html - o formulário de login (veja AuthController).
   Um <form> HTML comum: o próprio navegador envia login,
   senha e resposta ao CAPTCHA em POST /login, sem JavaScript. Em caso
   de falha, o servidor devolve ESTA página, com o login já digitado, um
   NOVO CAPTCHA e o erro, exibido no rodapé da página pelo layout.

   A página inteira é SUBSTITUÍDA pelo fragmento [page] do layout, ao qual
   passamos o bloco <main> desta página (~{::main}).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="loginTyped=${model.login != ''}">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3" th:text="#{LOGIN.TITLE}">Login</h5>

      <form method="post" action="/login">
        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{LOGIN.LOGIN_LABEL}">Login</label>
          <!--/* th:autofocus: um atributo booleano, escrito se o valor for true, omitido caso contrário */-->
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 th:value="${model.login}" required th:autofocus="${!loginTyped}">
        </div>
        <div class="mb-3">
          <label class="form-label" for="password" th:text="#{LOGIN.PASSWORD_LABEL}">Password</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required th:autofocus="${loginTyped}">
        </div>

        <div th:replace="~{fragments/captcha :: captcha(${model.captcha})}"></div>

        <button type="submit" class="btn btn-primary w-100" th:text="#{LOGIN.SUBMIT}">Log in</button>

        <!--/* ainda sem conta: um paciente pode criar uma ele mesmo.
               NÃO é um simples link: é um segundo botão de envio deste
               MESMO formulário, que vai para outro endereço (formaction). O
               servidor verifica ali o CAPTCHA acima antes de abrir a página de
               criação de conta (veja RegistrationController).
               formnovalidate: o navegador não exige login e senha
               (inútil para criar uma conta); é o servidor que verifica o
               CAPTCHA. Enter em um campo sempre aciona o PRIMEIRO
               botão do formulário, "Log in". */-->
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="/register/access" formnovalidate th:text="#{LOGIN.CREATE_ACCOUNT}">Create an account</button>
        <div class="form-text text-center" th:text="#{LOGIN.CREATE_ACCOUNT_HELP}">help</div>
      </form>

      <div class="text-muted small mt-3">
        <span th:text="#{LOGIN.DEMO_ACCOUNTS}">Demo accounts</span>
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - <span th:text="#{LOGIN.DEMO_ADMIN}">ADMIN</span></li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span th:text="#{LOGIN.DEMO_DOCTOR}">DOCTOR</span></li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span th:text="#{LOGIN.DEMO_USER}">USER</span></li>
        </ul>
      </div>
    </div>
  </div>
</main>
</body>
</html>
  • linha 12: a página é substituída pelo fragmento [page] do template, ao qual ela passa seu elemento [<main>]. [~{::main}] refere-se ao elemento [<main>] do arquivo atual. Portanto, somente esse elemento é usado: as tags [<html>] e [<body>] deste arquivo servem apenas para torná-lo um arquivo HTML completo, que pode ser aberto em um navegador;
  • linha 14: após uma tentativa malsucedida, o controller retorna esta página com o login já preenchido ([model.login]); a variável [loginTyped] indica se ele é conhecido;
  • linha 19: um formulário HTML padrão: o próprio navegador envia o nome de usuário, a senha e a resposta do CAPTCHA;
  • linhas 23–29: [th:autofocus] define o atributo booleano [autofocus] se o valor for verdadeiro e o omite caso contrário: apenas um dos dois campos o recebe. O cursor é colocado no campo do nome de usuário ou no campo da senha, se o nome de usuário já for conhecido. Os valores de [autocomplete] ([username], [current-password]) auxiliam os gerenciadores de senhas dos navegadores;
  • linha 32: o CAPTCHA, um fragmento parametrizado, que recebe o objeto [model.captcha];
  • linhas 45–46: o segundo botão envia o mesmo formulário para [/register/access] (atributo [formaction], veja o Exemplo 21): o servidor verifica o CAPTCHA ali antes de abrir a página de criação de conta. [formnovalidate]: o navegador não exige nome de usuário e senha, pois eles não são necessários para criar uma conta. Pressionar a tecla Enter em um campo sempre aciona o primeiro botão do formulário: “Entrar”;
  • Linhas 50–57: contas de demonstração (senha = login).

Aqui está o formulário gerado para o endereço [/login?login=martin] (a imagem do CAPTCHA foi recortada):

curl http://localhost:8081/login?login=martin
    <main class="row justify-content-center">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3">Login</h5>
      <form method="post" action="/login">
        <div class="mb-3">
          <label class="form-label" for="login">Login</label>
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="martin" required>
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">Password</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required autofocus="autofocus">
        </div>
        <div class="mb-3">
  <label class="form-label" for="captcha">Type the characters shown in the image</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="Anti-robot verification image"><svg xmlns="http://www.w3.org/2000/svg" width="150" height="50" ...</svg></div>
    <a class="small" href="/login">Another image</a>
  </div>
  <input type="hidden" name="captchaId" value="7cb0085e-e571-4756-878f-04ca6f429140">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
         spellcheck="false" required class="form-control">
  <div class="form-text">Upper or lower case, it does not matter.</div>
</div>
        <button type="submit" class="btn btn-primary w-100">Log in</button>

Como o login é conhecido, somente o campo da senha recebeu o atributo [autofocus]. O link “Outra imagem” aponta para [/login]: a variável [path] contém apenas o caminho da URL, sem seus parâmetros.

11.17.2.2. templates/schedule.html

<!doctype html>
<!--/* =========================================================================
   templates/schedule.html - a página principal (veja ScheduleController).
   Três blocos:
     1. a escolha do médico e do dia;
     2. a agenda;
     3. o diálogo de reserva (fragments/booking.html).
   Um eventual erro (data inválida, médico desconhecido) é exibido no
   rodapé da página pelo layout (veja fragments/errors.html).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>

  <!--/* 1. escolha do médico e do dia: um formulário GET, que simplesmente
         recarrega esta página com ?doctorId=...&day=... na URL */-->
  <form method="get" action="/schedule" class="card p-3 mb-3">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="doctorId" th:text="#{DOCTOR_DAY_PICKER.DOCTOR_LABEL}">Doctor</label>
        <select id="doctorId" name="doctorId" class="form-select" required>
          <option value="" th:text="#{DOCTOR_DAY_PICKER.CHOOSE_DOCTOR}">-- choose --</option>
          <option th:each="doctor : ${model.doctors}" th:value="${doctor.id}"
                  th:selected="${doctor.selected}" th:text="${doctor.label}">Mme Marie PELISSIER</option>
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day" th:text="#{DOCTOR_DAY_PICKER.DAY_LABEL}">Day</label>
        <input id="day" name="day" type="date" class="form-control" th:value="${model.day}" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100" th:text="#{DOCTOR_DAY_PICKER.VIEW_SCHEDULE}">View the schedule</button>
      </div>
    </div>
  </form>

  <!--/* paciente que já tem uma consulta futura: por que não há botão "Book" */-->
  <div class="alert alert-info" th:if="${model.info != null}">
    <span th:text="#{${model.info}}">info</span>
    <a href="/my-area" class="alert-link" th:text="#{APP.MENU_MY_AREA}">My area</a>
  </div>

  <!--/* 2. a agenda; th:object: ${schedule} pode então ser escrito *{...} */-->
  <div class="card p-3" th:if="${model.schedule != null}" th:object="${model.schedule}">
    <h5 th:text="|#{SCHEDULE.TITLE_PREFIX} *{day} - *{doctor}|">Schedule of ...</h5>

    <table class="table table-hover align-middle" th:unless="*{rows.isEmpty()}">
      <thead>
        <tr>
          <th th:text="#{SCHEDULE.COLUMN_SLOT}">Slot</th>
          <th th:text="#{SCHEDULE.COLUMN_STATUS}">Status</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr th:each="row : *{rows}" th:classappend="${row.bookable} ? 'free-slot'">
          <td th:text="${row.time}">8:00 - 8:20</td>
          <td>
            <!--/* [patient] é preenchido apenas se o usuário tiver permissão para
                   ver esse nome (ADMIN, DOCTOR, ou o paciente para SUA
                   consulta) - caso contrário, simplesmente "Booked" */-->
            <span th:if="${row.free}" class="badge text-bg-success" th:text="#{SCHEDULE.FREE}">Free</span>
            <span th:if="${!row.free and row.patient != null}" class="badge"
                  th:classappend="${row.mine} ? 'text-bg-primary' : 'text-bg-secondary'"
                  th:text="${row.patient}">Mme Alice DURAND</span>
            <span th:if="${!row.free and row.patient == null}" class="badge text-bg-secondary"
                  th:text="#{SCHEDULE.BOOKED_BY_OTHER}">Booked</span>
          </td>
          <td>
            <!--/* os botões exibidos foram decididos pelo controller
                   (bookable, appointmentId) conforme o papel do usuário */-->
            <!--/* "Book" é um simples link: ele reabre esta página
                   com o diálogo de reserva desse horário */-->
            <a th:if="${row.bookable}" class="btn btn-sm btn-outline-success"
               th:href="${row.bookUrl}" th:text="#{SCHEDULE.BOOK}">Book</a>
            <!--/* "Cancel" MODIFICA dados: é, portanto, um POST */-->
            <form th:if="${row.appointmentId != null}" method="post" action="/schedule/cancel" class="m-0"
                  th:attr="data-confirmation=#{SCHEDULE.CANCEL_CONFIRM}">
              <input type="hidden" name="appointmentId" th:value="${row.appointmentId}">
              <input type="hidden" name="doctorId" th:value="${model.doctorId}">
              <input type="hidden" name="day" th:value="${model.day}">
              <button type="submit" class="btn btn-sm btn-outline-danger" th:text="#{SCHEDULE.CANCEL_APPOINTMENT}">Cancel</button>
            </form>
          </td>
        </tr>
      </tbody>
    </table>
    <p class="text-muted mb-0" th:if="*{rows.isEmpty()}" th:text="#{SCHEDULE.NO_SLOTS}">No slots.</p>
  </div>
  <p class="text-muted" th:if="${model.schedule == null}" th:text="#{SCHEDULE.EMPTY_STATE}">Choose a doctor...</p>

  <!--/* 3. o diálogo de reserva, somente se a URL contiver &book=... */-->
  <th:block th:if="${model.booking != null}">
    <div th:replace="~{fragments/booking :: booking}"></div>
  </th:block>

</main>
</body>
</html>

Vamos analisar este código:

  • Linhas 17–35: seleção do médico e do dia: um formulário GET (veja o Exemplo 17), que recarrega a página com [?doctorId=...&day=...] na URL. Cada médico é um [OptionView] que indica se ele está selecionado ([th:selected]). Um campo [type="date"] envia a data no formato [yyyy-MM-dd] (veja o Exemplo 18);
  • Linhas 38–41: a mensagem para um paciente que já tem uma consulta futura: ela explica por que os botões “Agendar” estão ausentes e fornece um link para “Minha área”. O controller não envia essa mensagem quando a consulta do paciente aparece na agenda exibida (veja [patientInfo]). [#{${model.info}}]: a chave da mensagem é fornecida pelo controller;
  • linha 44: a agenda, se solicitada. [th:object] refere-se a um objeto de seleção: dentro do elemento, [*{day}] equivale a [${model.schedule.day}];
  • linha 45: o título: “Agenda de sexta-feira, 25 de setembro de 2026 - Mme Marie PELISSIER”, por meio de uma substituição literal;
  • linha 47: a tabela só é escrita se a agenda tiver linhas ([th:unless]: a menos que...);
  • linha 56: uma linha por horário. Um horário disponível para agendamento muda de cor ao passar o mouse (classe [free-slot], veja [styles.css]);
  • Linhas 62–67: três casos: disponível; reservado, com o nome do paciente (em azul se for a consulta do paciente logado, [mine]; em cinza caso contrário); reservado sem nome visível, “Reservado”. O controller só preenche [patient] se o usuário tiver permissão para ver esse nome;
  • linhas 74–75: “Agendar” é um link: ele reabre esta página, exibindo a janela de reserva para esse horário ([bookUrl], preparado pelo controller);
  • linhas 77–83: “Cancelar” modifica dados: é um formulário (POST) com confirmação. [th:attr] define o atributo [data-confirmation], que contém a pergunta traduzida; o script [app.js] intercepta o envio dos formulários que têm esse atributo (veja o Exemplo 21). Os campos ocultos [doctorId] e [day] permitem que o controller redirecione para a mesma agenda. Dentro do laço, [model] sempre se refere ao modelo da página;
  • linhas 88 e 90: um médico sem horários disponíveis, ou nenhuma agenda solicitada ainda;
  • linhas 93–95: a janela de reserva, se o controller a tiver preparado. A condição é definida em um [th:block] que inclui o fragmento, o qual lê [model.booking], e que só é inserido se essa janela existir.

11.17.2.3. templates/persons/list.html

<!doctype html>
<!--/* =========================================================================
   templates/persons/list.html - a lista dos médicos OU dos clientes (ADMIN).
   Uma única view para ambos: os rótulos específicos de cada um chegam em
   model.keys (veja DoctorsController / ClientsController).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0" th:text="#{${model.keys.title}}">Doctors</h4>
    <a class="btn btn-primary" th:href="${model.addUrl}" th:text="#{${model.keys.add}}">Add</a>
  </div>

  <div class="card p-3">
    <table class="table table-hover align-middle mb-0" th:unless="${model.persons.isEmpty()}">
      <thead>
        <tr>
          <th th:text="#{PERSONS.COLUMN_TITLE}">Title</th>
          <th th:text="#{PERSONS.COLUMN_FIRSTNAME}">First name</th>
          <th th:text="#{PERSONS.COLUMN_LASTNAME}">Last name</th>
          <th th:text="#{PERSONS.COLUMN_LOGIN}">Login</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr th:each="person : ${model.persons}">
          <td th:text="${person.title}">Mme</td>
          <td th:text="${person.firstName}">Marie</td>
          <td th:text="${person.lastName}">PELISSIER</td>
          <td><code th:text="${person.login}">pelissier</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              <a class="btn btn-sm btn-outline-primary" th:href="${person.editUrl}"
                 th:text="#{PERSONS.EDIT}">Edit</a>
              <!--/* data-confirmation: um diálogo de confirmação será aberto
                     antes do envio do formulário (veja static/js/app.js) */-->
              <form method="post" th:action="${person.deleteUrl}" class="m-0"
                    th:attr="data-confirmation=#{${model.keys.confirmDelete}}">
                <button type="submit" class="btn btn-sm btn-outline-danger" th:text="#{PERSONS.DELETE}">Delete</button>
              </form>
            </div>
          </td>
        </tr>
      </tbody>
    </table>
    <p class="text-muted mb-0" th:if="${model.persons.isEmpty()}" th:text="#{${model.keys.empty}}">None.</p>
  </div>
</main>
</body>
</html>
  • linhas 11–12: o título e o rótulo do botão de adicionar: chaves de tradução fornecidas pelo controller ([model.keys]), que diferem para médicos e para clientes;
  • Linhas 16 e 47: a tabela, ou a mensagem “Nenhum médico.” (“Nenhum paciente.”) se a lista estiver vazia;
  • linha 27: uma linha por pessoa;
  • linha 31: o login, em fonte monoespaçada ([<code>]);
  • linhas 34–35: “Editar” é um link para o formulário de edição;
  • linhas 38–41: “Excluir” modifica dados: é um formulário POST, com confirmação. A pergunta de confirmação é uma chave fornecida pelo controller: [#{${model.keys.confirmDelete}}]; seu endereço ([th:action]) também.

11.17.2.4. templates/persons/form.html

<!doctype html>
<!--/* =========================================================================
   templates/persons/form.html - criação OU edição de um
   médico ou de um cliente (ADMIN). model.creating distingue os dois casos.

   Quando a entrada é recusada (campo vazio, login já utilizado...), o
   controller devolve ESTA view com:
     - os valores já digitados (model.values);
     - os campos defeituosos destacados em vermelho (classe Bootstrap "is-invalid");
     - sob um campo recusado pela validação, sua mensagem;
     - a mensagem de erro da página, exibida NO RODAPÉ da página pelo
       layout (veja fragments/errors.html).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-3" th:text="#{${model.pageTitle}}">Add a doctor</h5>

      <!--/* novalidate: deixamos o SERVIDOR validar (é ele quem tem a palavra final);
             as verificações do navegador (required...) são apenas uma comodidade,
             que um usuário sempre pode contornar */-->
      <form method="post" th:action="${model.action}" novalidate>
        <input type="hidden" name="version" th:unless="${model.creating}" th:value="${model.values.version}">

        <!--/* título, nome, sobrenome: fragmento comum a três formulários */-->
        <th:block th:replace="~{fragments/person-fields :: fields}"></th:block>

        <h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>

        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="off"
                 class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
          <div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
               th:text="#{${state.errorOf('login')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('login') == null}"
               th:text="${model.creating} ? #{PERSONS.LOGIN_HELP_CREATE} : #{PERSONS.LOGIN_HELP_EDIT}">help</div>
        </div>

        <div class="mb-4">
          <label class="form-label" for="password" th:text="#{PERSONS.PASSWORD_LABEL}">Password</label>
          <!--/* nunca pré-preenchida: a senha nunca volta ao navegador */-->
          <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                 class="form-control" th:classappend="${state.invalidClass('password')}">
          <div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
               th:text="#{${state.errorOf('password')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('password') == null}"
               th:text="${model.creating} ? #{PERSONS.PASSWORD_HELP_CREATE} : #{PERSONS.PASSWORD_HELP_EDIT}">help</div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" th:text="#{PERSONS.SAVE}">Save</button>
          <a class="btn btn-secondary" th:href="${model.listUrl}" th:text="#{PERSONS.BACK}">Back</a>
        </div>
      </form>
    </div>
  </div>
</main>
</body>
</html>
  • linha 16: [state]: o estado do formulário, para a parte não incluída no fragmento comum;
  • linha 19: o título: “Adicionar um médico”, “Editar um paciente” etc.;
  • Linha 24: o endereço de envio, fornecido pelo controller. [novalidate]: o navegador não verifica esses campos por conta própria ([required], [maxlength]); o servidor os valida e é a fonte de autoridade (veja o Exemplo 19);
  • linha 25: a versão do registro (bloqueio otimista), somente para uma modificação;
  • linha 28: os campos de título, nome e sobrenome, por meio do fragmento comum. [th:replace] em um [th:block]: o fragmento substitui o bloco;
  • linhas 34–39: o login, com sua mensagem de erro ou, na falta dela, seu texto de ajuda, que depende do modo: [${model.creating} ? #{...} : #{...}] escolhe entre duas mensagens;
  • linhas 45–50: a senha, que nunca é preenchida previamente; ela nunca é enviada de volta ao navegador;
  • linha 55: retorno à lista.

11.17.2.5. templates/registration.html

<!doctype html>
<!--/* =========================================================================
   templates/registration.html - "Create a client account" (página pública,
   veja RegistrationController). Mesmos campos de identidade do formulário
   do ADMIN (fragmento person-fields), mas o login e a senha
   são obrigatórios, com confirmação.
   Nenhum CAPTCHA AQUI: só se chega a esta página depois de ter copiado
   o da página de autenticação (botão "Create a client account").

   #{${key}('min', ${model.passwordMin()})}: a mensagem cuja chave é
   o valor de [key], com o parâmetro {min} (veja web/Translator.java).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-1" th:text="#{REGISTRATION.TITLE}">Create a client account</h5>
      <p class="text-muted small mb-3" th:text="#{REGISTRATION.INTRO}">intro</p>

      <form method="post" action="/register" novalidate>
        <th:block th:replace="~{fragments/person-fields :: fields}"></th:block>

        <h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>

        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
          <div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
               th:text="#{${state.errorOf('login')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('login') == null}" th:text="#{REGISTRATION.LOGIN_HELP}">help</div>
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password" th:text="#{PERSONS.PASSWORD_LABEL}">Password</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control" th:classappend="${state.invalidClass('password')}">
            <div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
                 th:text="#{${state.errorOf('password')}('min', ${model.passwordMin()})}">error</div>
            <div class="form-text" th:if="${state.errorOf('password') == null}"
                 th:text="#{REGISTRATION.PASSWORD_HELP('min', ${model.passwordMin()})}">help</div>
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation" th:text="#{ACCOUNT.CONFIRMATION_LABEL}">Confirmation</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password" required
                   class="form-control" th:classappend="${state.invalidClass('confirmation')}">
            <div class="invalid-feedback" th:if="${state.errorOf('confirmation') != null}"
                 th:text="#{${state.errorOf('confirmation')}}">error</div>
          </div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" th:text="#{REGISTRATION.SUBMIT}">Create my account</button>
          <a class="btn btn-secondary" href="/login" th:text="#{REGISTRATION.BACK_TO_LOGIN}">Back</a>
        </div>
      </form>
    </div>
  </div>
</main>
</body>
</html>
  • linha 21: o formulário, enviado por POST para [/register], validado pelo servidor ([novalidate]);
  • linha 22: os campos de identidade, que são os mesmos do formulário de ADMIN;
  • linhas 26–33: o login, que aqui é obrigatório;
  • linhas 37–43: a senha. A mensagem de erro “A senha deve ter pelo menos {min} caracteres” tem um parâmetro: [#{${key}('min', ${model.passwordMin()})}] passa ao mesmo tempo uma chave calculada e um parâmetro — o tamanho mínimo definido em [models/InputRules.java] — que é lido por um método do modelo;
  • linhas 46–50: confirmação da senha, comparada pelo validador;
  • linha 56: o usuário é redirecionado de volta para a página de login.

11.17.2.6. templates/area.html

<!doctype html>
<!--/* =========================================================================
   templates/area.html - "My area": a página inicial do paciente
   (papel USER), exibida logo após o login.
     - duas opções: [Manage my account] e [View a schedule];
     - sua consulta futura, se tiver uma, com o meio de cancelá-la.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h4 class="mb-3" th:text="#{AREA.HELLO('name', ${model.patient})}">Hello Mme Alice DURAND</h4>

  <div class="row g-3 mb-4">
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="/my-account">
        <h5 class="mb-1" th:text="#{AREA.MANAGE_ACCOUNT}">Manage my account</h5>
        <span class="text-muted" th:text="#{AREA.MANAGE_ACCOUNT_HELP}">help</span>
      </a>
    </div>
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="/schedule">
        <h5 class="mb-1" th:text="#{AREA.VIEW_SCHEDULE}">View a schedule</h5>
        <span class="text-muted" th:text="#{AREA.VIEW_SCHEDULE_HELP}">help</span>
      </a>
    </div>
  </div>

  <div class="card p-3">
    <h5 th:text="#{AREA.MY_APPOINTMENT}">My appointment</h5>
    <!--/* normalmente apenas uma (regra "uma consulta futura por vez"),
           mas a página pode exibir várias. [status]: uma variável de
           iteração fornecida por th:each (status.last: último elemento?) */-->
    <div th:each="appointment, status : ${model.appointments}"
         class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2"
         th:classappend="${status.last} ? '' : 'border-bottom'">
      <div>
        <div class="fw-semibold" th:text="|${appointment.day}, ${appointment.time}|">Wednesday 23 September 2026, 8:00 - 8:20</div>
        <div class="text-muted">
          <span th:text="${appointment.doctor}">Mme Marie PELISSIER</span> -
          <a th:href="${appointment.scheduleUrl}" th:text="#{AREA.SEE_IN_SCHEDULE}">see in the schedule</a>
        </div>
      </div>
      <form method="post" action="/my-area/cancel" class="m-0"
            th:attr="data-confirmation=#{SCHEDULE.CANCEL_CONFIRM}">
        <input type="hidden" name="appointmentId" th:value="${appointment.id}">
        <button type="submit" class="btn btn-outline-danger" th:text="#{AREA.CANCEL_APPOINTMENT}">Cancel</button>
      </form>
    </div>
    <p class="text-muted mb-0" th:if="${model.appointments.isEmpty()}" th:text="#{AREA.NO_APPOINTMENT}">No appointment.</p>
  </div>
</main>
</body>
</html>
  • linha 11: “Olá, Mr Jean MARTIN”: uma mensagem com um parâmetro [{name}];
  • linhas 13–26: as duas opções da página, grandes cartões clicáveis (links) que reagem à passagem do mouse (classe [option-card], veja [styles.css]);
  • linhas 33–35: a consulta futura. Normalmente há apenas uma (uma consulta futura por paciente), mas a página pode exibir várias. [th:each="appointment, status : ..."] declara, após a variável do laço, uma variável de estado fornecida pelo [Thymeleaf]: [status.last] indica se o elemento é o último da lista; todos os outros são separados por um separador ([border-bottom]);
  • linha 37: a data e a hora, já formatadas pelo controller;
  • linha 40: o link para a agenda do médico naquele dia, onde o paciente vê o seu nome;
  • linhas 43–47: o cancelamento, um formulário POST com confirmação;
  • linha 49: nenhuma consulta futura.

11.17.2.7. templates/account.html

<!doctype html>
<!--/* =========================================================================
   templates/account.html - "Manage my account" (papel USER).
   Dois formulários independentes na mesma página:
     1. a edição (identidade, login, nova senha opcional);
     2. a exclusão da conta - que também cancela suas consultas.
   Ambos exigem a senha ATUAL.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center" th:with="state=${model.state}">
  <div class="col-md-8 col-lg-6">

    <!--/* 1. edição */-->
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3" th:text="#{MY_ACCOUNT.TITLE}">Manage my account</h5>

      <form method="post" action="/my-account" novalidate>
        <input type="hidden" name="version" th:value="${model.values.version}">

        <th:block th:replace="~{fragments/person-fields :: fields}"></th:block>

        <h6 class="mt-4 text-muted" th:text="#{PERSONS.ACCOUNT_SECTION}">User account</h6>

        <div class="mb-3">
          <label class="form-label" for="login" th:text="#{PERSONS.LOGIN_LABEL}">Login</label>
          <input id="login" name="login" type="text" maxlength="30" autocomplete="username" required
                 class="form-control" th:classappend="${state.invalidClass('login')}" th:value="${model.values.login}">
          <div class="invalid-feedback" th:if="${state.errorOf('login') != null}"
               th:text="#{${state.errorOf('login')}}">error</div>
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <label class="form-label" for="password" th:text="#{MY_ACCOUNT.NEW_PASSWORD_LABEL}">New password</label>
            <input id="password" name="password" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control" th:classappend="${state.invalidClass('password')}">
            <div class="invalid-feedback" th:if="${state.errorOf('password') != null}"
                 th:text="#{${state.errorOf('password')}('min', ${model.passwordMin()})}">error</div>
            <div class="form-text" th:if="${state.errorOf('password') == null}"
                 th:text="#{PERSONS.PASSWORD_HELP_EDIT}">help</div>
          </div>
          <div class="col-sm-6">
            <label class="form-label" for="confirmation" th:text="#{ACCOUNT.CONFIRMATION_LABEL}">Confirmation</label>
            <input id="confirmation" name="confirmation" type="password" maxlength="72" autocomplete="new-password"
                   class="form-control" th:classappend="${state.invalidClass('confirmation')}">
            <div class="invalid-feedback" th:if="${state.errorOf('confirmation') != null}"
                 th:text="#{${state.errorOf('confirmation')}}">error</div>
          </div>
        </div>

        <div class="mb-4">
          <label class="form-label" for="currentPassword" th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_LABEL}">Current password</label>
          <input id="currentPassword" name="currentPassword" type="password" maxlength="72"
                 autocomplete="current-password" required
                 class="form-control" th:classappend="${state.invalidClass('currentPassword')}">
          <div class="invalid-feedback" th:if="${state.errorOf('currentPassword') != null}"
               th:text="#{${state.errorOf('currentPassword')}}">error</div>
          <div class="form-text" th:if="${state.errorOf('currentPassword') == null}"
               th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_HELP}">help</div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary" th:text="#{PERSONS.SAVE}">Save</button>
          <a class="btn btn-secondary" href="/my-area" th:text="#{MY_ACCOUNT.BACK}">Back</a>
        </div>
      </form>
    </div>

    <!--/* 2. exclusão */-->
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1" th:text="#{MY_ACCOUNT.DELETE_TITLE}">Delete my account</h5>
      <p class="text-muted small" th:text="#{MY_ACCOUNT.DELETE_HELP}">help</p>
      <form method="post" action="/my-account/delete" class="d-flex flex-wrap gap-2 align-items-end"
            th:attr="data-confirmation=#{MY_ACCOUNT.DELETE_CONFIRM}">
        <div class="flex-grow-1">
          <label class="form-label" for="deletePassword" th:text="#{MY_ACCOUNT.CURRENT_PASSWORD_LABEL}">Current password</label>
          <input id="deletePassword" name="deletePassword" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger" th:text="#{MY_ACCOUNT.DELETE_SUBMIT}">Delete my account</button>
      </form>
    </div>

  </div>
</main>
</body>
</html>
  • linhas 15–68: modificação da conta: identidade, login, nova senha (opcional) e sua confirmação;
  • linha 19: a versão do registro do cliente (bloqueio otimista);
  • linhas 52–61: senha atual, obrigatória para qualquer alteração;
  • linhas 71–83: exclusão, com confirmação. Dois formulários independentes na mesma página: cada um envia apenas os seus próprios campos. O campo de senha tem, portanto, um nome diferente aqui ([deletePassword]) e um identificador diferente. Este formulário não tem o atributo [novalidate]: o navegador exige a senha ([required]) mesmo antes de disparar o evento [submit] — ou seja, antes de pedir a confirmação.

11.17.2.8. templates/error.html

<!doctype html>
<!--/* =========================================================================
   templates/error.html - a página de erro (400, 403, 404, 500...),
   construída por ErrorController.
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger" th:text="${model.code}">404</h1>
      <p class="lead" th:text="#{${model.message}}">This page does not exist.</p>
      <div><a class="btn btn-primary" href="/" th:text="#{ERROR_PAGE.BACK}">Back to home</a></div>
    </div>
  </div>
</main>
</body>
</html>
  • Linhas 11–12: a página de erro gerada por [ErrorController] (400, 403, 404, 500): o código HTTP e a mensagem traduzida. Ela usa o mesmo template das outras páginas: o usuário mantém sua barra de navegação.

11.18. Os dicionários

Os dicionários são os da versão [ASP.NET Core MVC], sem alterações: eles ficam em [src/main/resources/i18n] e são lidos na inicialização pelo serviço [Translator] (veja “A camada web: serviços comuns”). Esse serviço “achata” sua estrutura: o texto ["TITLE"] da seção ["LOGIN"] torna-se a chave de mensagem [LOGIN.TITLE], que é usada pelas views ([#{LOGIN.TITLE}]) e pelos controllers.

11.18.1. i18n/fr.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Se déconnecter",
    "MENU_SCHEDULE": "Agenda",
    "MENU_DOCTORS": "Médecins",
    "MENU_PATIENTS": "Clients",
    "MENU_MY_AREA": "Mon espace"
  },
  "LOGIN": {
    "TITLE": "Connexion",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "SUBMIT": "Se connecter",
    "ERROR": "Login ou mot de passe incorrect.",
    "DEMO_ACCOUNTS": "Comptes de démonstration (mot de passe = login) :",
    "DEMO_ADMIN": "rôle ADMIN : rendez-vous + gestion des médecins et des clients",
    "DEMO_DOCTOR": "rôle DOCTOR : prise et annulation de rendez-vous",
    "DEMO_USER": "rôle USER (patients) : réservation pour eux-mêmes, gestion de leur compte",
    "CREATE_ACCOUNT": "Créer un compte client",
    "CREATE_ACCOUNT_HELP": "Pour créer un compte, recopiez d'abord les caractères de l'image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Médecin",
    "CHOOSE_DOCTOR": "-- choisir un médecin --",
    "DAY_LABEL": "Jour",
    "VIEW_SCHEDULE": "Voir l'agenda"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Agenda",
    "TITLE_PREFIX": "Agenda du",
    "COLUMN_SLOT": "Créneau",
    "COLUMN_STATUS": "Statut",
    "FREE": "Libre",
    "BOOK": "Réserver",
    "CANCEL_APPOINTMENT": "Annuler",
    "CANCEL_CONFIRM": "Annuler ce rendez-vous ?",
    "EMPTY_STATE": "Choisissez un médecin et un jour, puis cliquez sur « Voir l'agenda ».",
    "NO_SLOTS": "Ce médecin n'a aucun créneau horaire.",
    "BOOKED": "Rendez-vous enregistré.",
    "CANCELLED": "Rendez-vous annulé.",
    "BOOKED_BY_OTHER": "Réservé",
    "ALREADY_BOOKED_INFO": "Vous avez déjà un rendez-vous à venir : annulez-le pour en prendre un autre."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Réserver ce créneau",
    "CLOSE_ARIA": "Fermer",
    "SLOT": "Créneau de {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choisir un patient --",
    "CANCEL": "Annuler",
    "CONFIRM": "Confirmer"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Titre",
    "COLUMN_FIRSTNAME": "Prénom",
    "COLUMN_LASTNAME": "Nom",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "SAVE": "Enregistrer",
    "BACK": "Retour à la liste",
    "TITLE_LABEL": "Titre",
    "FIRSTNAME_LABEL": "Prénom",
    "LASTNAME_LABEL": "Nom",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Mot de passe",
    "LOGIN_HELP_CREATE": "Facultatif : par défaut, le nom en minuscules.",
    "LOGIN_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "PASSWORD_HELP_CREATE": "Facultatif : par défaut, identique au login.",
    "PASSWORD_HELP_EDIT": "Laisser vide pour ne pas le changer.",
    "ACCOUNT_SECTION": "Compte utilisateur"
  },
  "DOCTORS": {
    "TITLE": "Médecins",
    "ADD": "Ajouter un médecin",
    "EDIT": "Modifier un médecin",
    "EMPTY": "Aucun médecin.",
    "DELETE_CONFIRM": "Supprimer ce médecin, ses créneaux horaires et son compte utilisateur ?",
    "ADDED": "Le médecin {name} a été ajouté (login : {login}).",
    "UPDATED": "Le médecin {name} a été modifié.",
    "DELETED": "Le médecin {name} a été supprimé."
  },
  "CLIENTS": {
    "TITLE": "Clients",
    "ADD": "Ajouter un client",
    "EDIT": "Modifier un client",
    "EMPTY": "Aucun client.",
    "DELETE_CONFIRM": "Supprimer ce client, son compte utilisateur et tous ses rendez-vous ?",
    "ADDED": "Le client {name} a été ajouté (login : {login}).",
    "UPDATED": "Le client {name} a été modifié.",
    "DELETED": "Le client {name} a été supprimé."
  },
  "ERROR_PAGE": {
    "TITLE": "Erreur",
    "BACK": "Retour à l'accueil"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "DOCTOR_ALREADY_EXISTS": "Un médecin portant ce prénom et ce nom existe déjà.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "DOCTOR_HAS_APPOINTMENTS": "Ce médecin a des rendez-vous : annulez-les avant de le supprimer.",
    "SLOT_ALREADY_BOOKED": "Ce créneau vient d'être réservé par quelqu'un d'autre.",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Revenez à la liste et rouvrez-la avant de recommencer.",
    "DOCTOR_NOT_FOUND": "Ce médecin n'existe pas (ou plus).",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "SLOT_NOT_FOUND": "Ce créneau n'existe pas (ou plus).",
    "APPOINTMENT_NOT_FOUND": "Ce rendez-vous n'existe pas (ou plus).",
    "INVALID_DATE": "La date demandée n'est pas valide.",
    "CHOOSE_PATIENT": "Choisissez un patient.",
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "BAD_REQUEST": "La requête est invalide.",
    "FORBIDDEN": "Votre rôle ne vous permet pas d'accéder à cette page.",
    "NOT_FOUND": "Cette page n'existe pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite. Réessayez plus tard.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {minutes} minute(s).",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image. Une nouvelle image vous est proposée.",
    "TOO_MANY_ACCOUNTS": "Trop de comptes ont été créés depuis votre connexion. Réessayez dans {minutes} minute(s).",
    "LOGIN_REQUIRED": "Le login est obligatoire.",
    "PASSWORD_REQUIRED": "Le mot de passe est obligatoire.",
    "PASSWORD_TOO_SHORT": "Le mot de passe doit comporter au moins {min} caractères.",
    "CONFIRMATION_REQUIRED": "Confirmez le mot de passe.",
    "PASSWORDS_DIFFER": "La confirmation ne correspond pas au mot de passe.",
    "CURRENT_PASSWORD_REQUIRED": "Saisissez votre mot de passe actuel.",
    "WRONG_CURRENT_PASSWORD": "Mot de passe actuel incorrect.",
    "PAST_DATE": "On ne peut pas prendre de rendez-vous à une date passée.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "Ce patient a déjà un rendez-vous à venir : il faut l'annuler avant d'en prendre un autre.",
    "CAPTCHA_BEFORE_ACCOUNT": "Pour créer un compte, recopiez d'abord correctement les caractères de l'image, puis cliquez sur « Créer un compte client »."
  },
  "CAPTCHA": {
    "LABEL": "Recopiez les caractères de l'image",
    "IMAGE_ALT": "Image de vérification anti-robots",
    "NEW_IMAGE": "Autre image",
    "HELP": "Majuscules ou minuscules, peu importe."
  },
  "REGISTRATION": {
    "TITLE": "Créer un compte client",
    "INTRO": "Ce compte vous permettra de prendre vous-même vos rendez-vous.",
    "LOGIN_HELP": "Lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_HELP": "Au moins {min} caractères.",
    "SUBMIT": "Créer mon compte",
    "BACK_TO_LOGIN": "Retour à la connexion",
    "DONE": "Votre compte a été créé. Vous pouvez vous connecter avec le login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirmation du mot de passe"
  },
  "AREA": {
    "TITLE": "Mon espace",
    "HELLO": "Bonjour {name}",
    "MANAGE_ACCOUNT": "Gérer mon compte",
    "MANAGE_ACCOUNT_HELP": "Modifier mes informations, mon mot de passe, ou supprimer mon compte.",
    "VIEW_SCHEDULE": "Voir un agenda",
    "VIEW_SCHEDULE_HELP": "Consulter l'agenda d'un médecin et réserver un créneau.",
    "MY_APPOINTMENT": "Mon rendez-vous",
    "SEE_IN_SCHEDULE": "voir dans l'agenda",
    "CANCEL_APPOINTMENT": "Annuler ce rendez-vous",
    "NO_APPOINTMENT": "Vous n'avez aucun rendez-vous à venir."
  },
  "MY_ACCOUNT": {
    "TITLE": "Gérer mon compte",
    "NEW_PASSWORD_LABEL": "Nouveau mot de passe",
    "CURRENT_PASSWORD_LABEL": "Mot de passe actuel",
    "CURRENT_PASSWORD_HELP": "Obligatoire pour enregistrer une modification.",
    "BACK": "Retour à mon espace",
    "DELETE_TITLE": "Supprimer mon compte",
    "DELETE_HELP": "Votre compte sera définitivement supprimé, ainsi que tous vos rendez-vous.",
    "DELETE_CONFIRM": "Supprimer définitivement votre compte ? Votre rendez-vous éventuel sera annulé.",
    "DELETE_SUBMIT": "Supprimer mon compte",
    "UPDATED": "Votre compte a été modifié.",
    "DELETED": "Votre compte a été supprimé."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "Non, revenir",
    "YES": "Oui, confirmer"
  }
}
  • As seções agrupam os textos por página ([LOGIN], [SCHEDULE], [AREA]...) ou por tema ([ERRORS], [CONFIRMATION]). Alguns nomes ([DOCTOR_DAY_PICKER], [BOOKING_DIALOG]) vêm das primeiras versões da aplicação, cujo cliente era escrito com [Angular];
  • linha 80: texto com dois parâmetros, [{name}] e [{login}], que são substituídos durante a tradução;
  • Linhas 98–137: mensagens de erro. Essas são as chaves usadas pela [BusinessException] na camada de negócio, pelas anotações de validação dos formulários ([@NotBlank(message = "ERRORS.FIRSTNAME_REQUIRED")]), pelos controllers e pela página de erro. Três delas têm um parâmetro: [{minutes}] (linhas 124 e 126) e [{min}] (linha 129).

11.18.2. i18n/en.json

{
  "APP": {
    "TITLE": "RdvMedecins",
    "LOGOUT": "Log out",
    "MENU_SCHEDULE": "Schedule",
    "MENU_DOCTORS": "Doctors",
    "MENU_PATIENTS": "Patients",
    "MENU_MY_AREA": "My area"
  },
  "LOGIN": {
    "TITLE": "Login",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "SUBMIT": "Log in",
    "ERROR": "Incorrect login or password.",
    "DEMO_ACCOUNTS": "Demo accounts (password = login):",
    "DEMO_ADMIN": "ADMIN role: appointments + doctor and patient management",
    "DEMO_DOCTOR": "DOCTOR role: booking and cancelling appointments",
    "DEMO_USER": "USER role (patients): booking for themselves, managing their account",
    "CREATE_ACCOUNT": "Create a patient account",
    "CREATE_ACCOUNT_HELP": "To create an account, first type the characters shown in the image."
  },
  "DOCTOR_DAY_PICKER": {
    "DOCTOR_LABEL": "Doctor",
    "CHOOSE_DOCTOR": "-- choose a doctor --",
    "DAY_LABEL": "Day",
    "VIEW_SCHEDULE": "View schedule"
  },
  "SCHEDULE": {
    "PAGE_TITLE": "Schedule",
    "TITLE_PREFIX": "Schedule for",
    "COLUMN_SLOT": "Slot",
    "COLUMN_STATUS": "Status",
    "FREE": "Free",
    "BOOK": "Book",
    "CANCEL_APPOINTMENT": "Cancel",
    "CANCEL_CONFIRM": "Cancel this appointment?",
    "EMPTY_STATE": "Choose a doctor and a day, then click \"View schedule\".",
    "NO_SLOTS": "This doctor has no time slots.",
    "BOOKED": "Appointment booked.",
    "CANCELLED": "Appointment cancelled.",
    "BOOKED_BY_OTHER": "Booked",
    "ALREADY_BOOKED_INFO": "You already have an upcoming appointment: cancel it to book another one."
  },
  "BOOKING_DIALOG": {
    "TITLE": "Book this slot",
    "CLOSE_ARIA": "Close",
    "SLOT": "Slot {time}",
    "PATIENT_LABEL": "Patient",
    "CHOOSE_PATIENT": "-- choose a patient --",
    "CANCEL": "Cancel",
    "CONFIRM": "Confirm"
  },
  "PERSONS": {
    "COLUMN_TITLE": "Title",
    "COLUMN_FIRSTNAME": "First name",
    "COLUMN_LASTNAME": "Last name",
    "COLUMN_LOGIN": "Login",
    "EDIT": "Edit",
    "DELETE": "Delete",
    "SAVE": "Save",
    "BACK": "Back to the list",
    "TITLE_LABEL": "Title",
    "FIRSTNAME_LABEL": "First name",
    "LASTNAME_LABEL": "Last name",
    "LOGIN_LABEL": "Login",
    "PASSWORD_LABEL": "Password",
    "LOGIN_HELP_CREATE": "Optional: defaults to the last name in lower case.",
    "LOGIN_HELP_EDIT": "Leave empty to keep it unchanged.",
    "PASSWORD_HELP_CREATE": "Optional: defaults to the login.",
    "PASSWORD_HELP_EDIT": "Leave empty to keep it unchanged.",
    "ACCOUNT_SECTION": "User account"
  },
  "DOCTORS": {
    "TITLE": "Doctors",
    "ADD": "Add a doctor",
    "EDIT": "Edit a doctor",
    "EMPTY": "No doctors.",
    "DELETE_CONFIRM": "Delete this doctor, their time slots and their user account?",
    "ADDED": "Doctor {name} has been added (login: {login}).",
    "UPDATED": "Doctor {name} has been updated.",
    "DELETED": "Doctor {name} has been deleted."
  },
  "CLIENTS": {
    "TITLE": "Patients",
    "ADD": "Add a patient",
    "EDIT": "Edit a patient",
    "EMPTY": "No patients.",
    "DELETE_CONFIRM": "Delete this patient, their user account and all their appointments?",
    "ADDED": "Patient {name} has been added (login: {login}).",
    "UPDATED": "Patient {name} has been updated.",
    "DELETED": "Patient {name} has been deleted."
  },
  "ERROR_PAGE": {
    "TITLE": "Error",
    "BACK": "Back to the home page"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "DOCTOR_ALREADY_EXISTS": "A doctor with this first and last name already exists.",
    "PATIENT_ALREADY_EXISTS": "A patient with this first and last name already exists.",
    "DOCTOR_HAS_APPOINTMENTS": "This doctor has appointments: cancel them before deleting the doctor.",
    "SLOT_ALREADY_BOOKED": "This slot has just been booked by someone else.",
    "CONCURRENT_UPDATE": "This record was changed by another user in the meantime. Go back to the list and reopen it before trying again.",
    "DOCTOR_NOT_FOUND": "This doctor does not exist (any more).",
    "PATIENT_NOT_FOUND": "This patient does not exist (any more).",
    "SLOT_NOT_FOUND": "This slot does not exist (any more).",
    "APPOINTMENT_NOT_FOUND": "This appointment does not exist (any more).",
    "INVALID_DATE": "The requested date is not valid.",
    "CHOOSE_PATIENT": "Choose a patient.",
    "INVALID_FORM": "The form contains errors.",
    "INVALID_TITLE": "Choose a title from the list.",
    "FIRSTNAME_REQUIRED": "The first name is required.",
    "FIRSTNAME_TOO_LONG": "The first name must not exceed 20 characters.",
    "LASTNAME_REQUIRED": "The last name is required.",
    "LASTNAME_TOO_LONG": "The last name must not exceed 20 characters.",
    "INVALID_LOGIN": "At most 30 characters: unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_TOO_LONG": "The password must not exceed 72 characters.",
    "SESSION_EXPIRED": "Your session has expired: please log in again.",
    "BAD_REQUEST": "The request is invalid.",
    "FORBIDDEN": "Your role does not allow you to access this page.",
    "NOT_FOUND": "This page does not exist.",
    "SERVER_ERROR": "An unexpected error occurred. Please try again later.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {minutes} minute(s).",
    "WRONG_CAPTCHA": "The characters you typed do not match the image. A new image is shown.",
    "TOO_MANY_ACCOUNTS": "Too many accounts have been created from your connection. Try again in {minutes} minute(s).",
    "LOGIN_REQUIRED": "The login is required.",
    "PASSWORD_REQUIRED": "The password is required.",
    "PASSWORD_TOO_SHORT": "The password must be at least {min} characters long.",
    "CONFIRMATION_REQUIRED": "Please confirm the password.",
    "PASSWORDS_DIFFER": "The confirmation does not match the password.",
    "CURRENT_PASSWORD_REQUIRED": "Enter your current password.",
    "WRONG_CURRENT_PASSWORD": "Incorrect current password.",
    "PAST_DATE": "Appointments cannot be booked for a past date.",
    "PATIENT_HAS_UPCOMING_APPOINTMENT": "This patient already has an upcoming appointment: it must be cancelled before booking another one.",
    "CAPTCHA_BEFORE_ACCOUNT": "To create an account, first type the characters shown in the image correctly, then click \"Create a patient account\"."
  },
  "CAPTCHA": {
    "LABEL": "Type the characters shown in the image",
    "IMAGE_ALT": "Anti-robot verification image",
    "NEW_IMAGE": "Another image",
    "HELP": "Upper or lower case, it does not matter."
  },
  "REGISTRATION": {
    "TITLE": "Create a patient account",
    "INTRO": "With this account you can book your own appointments.",
    "LOGIN_HELP": "Unaccented lower-case letters, digits, dot, hyphen, underscore.",
    "PASSWORD_HELP": "At least {min} characters.",
    "SUBMIT": "Create my account",
    "BACK_TO_LOGIN": "Back to login",
    "DONE": "Your account has been created. You can now log in with the login {login}."
  },
  "ACCOUNT": {
    "CONFIRMATION_LABEL": "Confirm password"
  },
  "AREA": {
    "TITLE": "My area",
    "HELLO": "Hello {name}",
    "MANAGE_ACCOUNT": "Manage my account",
    "MANAGE_ACCOUNT_HELP": "Change my details or password, or delete my account.",
    "VIEW_SCHEDULE": "View a schedule",
    "VIEW_SCHEDULE_HELP": "See a doctor's schedule and book a slot.",
    "MY_APPOINTMENT": "My appointment",
    "SEE_IN_SCHEDULE": "see in the schedule",
    "CANCEL_APPOINTMENT": "Cancel this appointment",
    "NO_APPOINTMENT": "You have no upcoming appointment."
  },
  "MY_ACCOUNT": {
    "TITLE": "Manage my account",
    "NEW_PASSWORD_LABEL": "New password",
    "CURRENT_PASSWORD_LABEL": "Current password",
    "CURRENT_PASSWORD_HELP": "Required to save any change.",
    "BACK": "Back to my area",
    "DELETE_TITLE": "Delete my account",
    "DELETE_HELP": "Your account will be permanently deleted, together with all your appointments.",
    "DELETE_CONFIRM": "Permanently delete your account? Any appointment you have will be cancelled.",
    "DELETE_SUBMIT": "Delete my account",
    "UPDATED": "Your account has been updated.",
    "DELETED": "Your account has been deleted."
  },
  "CONFIRMATION": {
    "TITLE": "Confirmation",
    "NO": "No, go back",
    "YES": "Yes, confirm"
  }
}

O dicionário em inglês tem exatamente as mesmas chaves nas mesmas linhas.

11.19. Os arquivos estáticos

[Spring Boot] serve os arquivos da pasta [src/main/resources/static] tal como estão (veja o Exemplo 15): [static/css/styles.css] é servido no endereço [/css/styles.css]. Esses endereços são declarados públicos em [SecurityConfig], para que a página de login tenha seus estilos. A pasta [static/lib/bootstrap] contém o [Bootstrap] (sua folha de estilo [css/bootstrap.min.css] e sua licença), que não é exibido.

11.19.1. static/css/styles.css

/* =========================================================================
   static/css/styles.css - alguns ajustes sobre o Bootstrap
   (os mesmos da versão ASP.NET Core MVC desta aplicação).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-zone: as mensagens de erro, no rodapé da página, sobre um fundo rosa claro
   (veja templates/fragments/errors.html).
   position: sticky + bottom: se a página for mais alta que a janela (uma
   agenda de 12 horários, por exemplo), a zona permanece colada no rodapé da
   janela em vez de desaparecer abaixo da dobra - sem jamais
   cobrir o conteúdo quando a página é curta.
   z-index: acima do fundo cinza do diálogo de reserva (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* rosa claro */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* as duas grandes opções da página "My area" do paciente */
.option-card {
  transition: border-color 0.15s, box-shadow 0.15s;
}

.option-card:hover {
  border-color: #0d6efd;
  box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}

/* a imagem do CAPTCHA (SVG de 150 x 50 pixels) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • linhas 10–12: um horário disponível para agendamento muda de cor ao passar o mouse;
  • linhas 23–33: a área de erros, sobre um fundo rosa claro. [position: sticky] e [bottom: 1rem]: se a página for mais alta que a janela, a área permanece na parte inferior da janela em vez de sumir da tela; [z-index] a coloca acima do fundo acinzentado da janela de reserva;
  • linhas 36–43: as duas opções de “Minha área” reagem à passagem do mouse;
  • linhas 46–50: a moldura da imagem do CAPTCHA.

11.19.2. static/js/app.js

// =========================================================================
// static/js/app.js - o ÚNICO JavaScript da aplicação.
// -------------------------------------------------------------------------
// Toda a aplicação funciona sem JavaScript. Este script acrescenta uma
// comodidade: antes de enviar um formulário que traga o atributo
// data-confirmation="...", um diálogo modal pergunta "Are you sure?"
// (o diálogo em si está na página: templates/fragments/confirmation.html).
// Se o JavaScript estiver desativado, o formulário é simplesmente enviado sem
// confirmação - nada quebra (princípio de "progressive enhancement").
//
// Por que não window.confirm()? Sua caixa não pode ser estilizada, e seus
// botões ficam no idioma do navegador, não no da página.
// =========================================================================

(() => {
  const modal = document.getElementById('confirmation-modal');
  if (!modal) {
    return;
  }
  const message = document.getElementById('confirmation-modal-message');
  const noButton = modal.querySelector('.modal-footer [data-action="no"]');

  let pendingForm = null; // o formulário a enviar se o usuário confirmar
  let previousFocus = null; // o elemento ao qual devolver o foco ao fechar

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (e não innerHTML): a mensagem é exibida como TEXTO,
    // nunca interpretada como HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // o foco vai para "No": um Enter pressionado por distração não exclui nada
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. os botões do diálogo (Yes / No / cruz de fechar)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() envia o formulário SEM disparar novamente o evento
      // 'submit': nenhum novo pedido de confirmação
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // clique no fundo cinza, fora do diálogo
    }
  });

  // 3. teclado: Escape fecha o diálogo; Tab permanece DENTRO do diálogo
  //    (senão o foco iria para a página acinzentada, atrás)
  modal.addEventListener('keydown', (event) => {
    if (event.key === 'Escape') {
      close();
    } else if (event.key === 'Tab') {
      const buttons = [...modal.querySelectorAll('button')];
      const first = buttons[0];
      const last = buttons[buttons.length - 1];
      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  });
})();

O script da janela de confirmação do Exemplo 21, aprimorado com tratamento do teclado. Ele segue o mesmo princípio de aprimoramento progressivo: sem [JavaScript], os formulários são enviados sem confirmação e a aplicação continua funcionando.

  • Linha 15: o script inteiro está envolvido em uma função, que é chamada imediatamente ([(() => { ... })()]): suas variáveis não ficam visíveis para outros scripts da página;
  • Linhas 16–19: uma página sem janela de confirmação não tem nada a fazer;
  • Linha 24: o elemento que tinha o foco do teclado (aquele que recebe as teclas digitadas) antes de a janela abrir: o foco volta a ele quando a janela fecha;
  • linhas 26–35: a janela abre com a mensagem específica do formulário ([form.dataset.confirmation] é o valor de seu atributo [data-confirmation]); o foco é colocado em “Não, voltar”: pressionar Enter acidentalmente não exclui nada;
  • linhas 37–43: a janela é ocultada e o foco é restaurado;
  • linhas 46–51: os envios de formulários com o atributo [data-confirmation] são interceptados, como no Exemplo 21;
  • linhas 54–67: “Sim”, “Não”, o botão de fechar e o clique fora da janela. [closest('[data-action]')] encontra o elemento com o atributo, mesmo que você tenha clicado em um elemento dentro dele. O operador [?.] retorna [undefined] em vez de falhar quando nenhum elemento é encontrado;
  • linhas 71–86: a tecla Esc fecha a janela; a tecla Tab (e Shift+Tab) alterna o foco entre os botões da janela, em vez de deixá-lo passar para a página acinzentada por trás.