Skip to content

11. 案例研究:RdvMedecins 应用程序

11.1. 问题描述

RdvMedecins 应用程序管理一家医疗诊所的预约。每位医生都有时间段(例如从上午 8:00 到中午 12:00,每 20 分钟一个);一次预约由一个日期、一个时间段、以及一位客户(患者)组成。这是上一课中 [ASP.NET Core MVC] 应用程序在 [Spring MVC] 中的精确实现:相同的数据库、相同的业务规则、相同的页面、相同的 URL、相同的翻译字典。HTML 页面由服务器使用 [Thymeleaf] 视图生成;数据库访问由 [Spring Data JPA] 和 [Hibernate] 负责处理。

三种用户角色共用该应用程序:

角色
对象
可以做什么
ADMIN
管理员([admin])
查看日程,为任何患者预约和取消预约;管理(列出、添加、编辑、删除)医生和客户
DOCTOR
医生
查看日程,为任何患者预约和取消预约
USER
客户(患者)
查看日程但看不到其他患者的姓名;为自己预约;取消自己的预约;管理自己的账户;创建账户

主要管理规则:

  • 不能预约过去的时间;
  • 同一时间段每天只能被预约一次;
  • 一位患者同一时间只能有一个即将到来的预约;
  • 两位医生(或两位客户)不能有相同的名和姓,并且一个登录名只属于一个账户;
  • 有预约的医生不能被删除;删除客户时会连同其预约一并删除;
  • 登录页面受到防机器人保护(验证码、限制尝试次数),创建客户账户需要先在该页面上通过验证码。

11.2. 使用应用程序

11.2.1. 登录页面

Image

页面有两个按钮:登录和创建患者账户。两者都要求你输入图像中显示的字符。FR / EN 按钮用于切换语言:

Image

错误(这里是验证码输入错误)显示在页面底部的浅粉色背景上:

Image

11.2.2. 管理员和医生看到的日历

登录后,管理员会进入日历页面。他们选择一位医生和一天:

Image

Image

每个时间段要么可预约(“预约”按钮),要么已被占用(显示患者姓名和“取消”按钮)。点击“预约”会打开一个窗口,询问患者的信息。该窗口与页面的其余部分一样由服务器生成:URL 现在包含参数 [book=4],即所选时间段的编号:

Image

点击“取消”会提示确认(这里是由 Pélissier 医生操作,其导航栏中不包含管理菜单):

Image

11.2.3. 患者门户

患者(角色 USER)进入“我的专区”:显示其即将到来的预约(可以取消),以及指向账户管理和日历的链接:

Image

在日历中,他们能看到自己的预约(蓝色),但看不到其他患者的姓名,这些姓名被“已预约”所取代:这个姓名甚至不会出现在页面的源代码中。由于他们已经有一个即将到来的预约,因此不能再预约另一个:不显示“预约”按钮(在另一天或另一位医生的日历上——那里不显示他们的预约——会有一条消息解释原因):

Image

没有预约的患者可以为自己预约一个可用的时间段:预约窗口不会提示用户选择患者。

Image

账户管理:编辑个人信息、修改密码,或者删除账户(及其预约)。任何修改都需要输入当前密码:

Image

试图打开管理员专用页面的患者(这里是手动输入的 [/doctors])会收到一个错误页面:

Image

11.2.4. 管理医生和患者

管理员多出两个菜单:医生和患者:

Image

Image

添加医生的表单,带着错误提交:

Image

与现有医生同名的姓名会被拒绝,即使是用小写写的(我们将看到,对姓名进行不区分大小写和重音的比较的是数据库本身):

Image

删除患者需要确认:

Image

11.2.5. 创建患者账户

在登录页面上,“创建患者账户”按钮只有在验证码输入正确时才会打开表单:

Image

Image

11.3. 安装与运行

该应用程序位于 [rdvmedecins2-spring-mvc] 文件夹中,紧挨着 [examples] 文件夹。它是一个独立的 [Maven] 项目:它不依赖包含各示例的父项目,并且有自己的 Maven Wrapper(见下文)。该文件夹中的 [README.md] 文件包含以下所有内容。

11.3.1. 所需软件

有两个软件就足够了:

  • JDK 21 ([Java Development Kit]),其中包含 [javac] 编译器和 [java] 虚拟机。[Java] 21 是长期支持(LTS)版本。任何免费发行版都适用,例如 [Eclipse Temurin] (https://adoptium.net);在 [Linux] 下,则是 [openjdk-21-jdk] 包。在终端中验证安装:
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)
  • 一个 [MySQL] 8 服务器,例如 [Laragon] 在 [Windows] 下附带的那个(参见示例 28)。[MariaDB] 同样适用:该应用程序已用它测试过。

[Maven] 无需安装:[mvnw] 脚本(Maven Wrapper)会在首次启动时自动下载它,然后 [Maven] 从 [Maven Central] 仓库下载项目所需的库。因此首次编译期间必须连接互联网。推荐的编辑器是 [Visual Studio Code],并安装“Extension Pack for Java”和“Spring Boot Extension Pack”;不过,所有操作也都可以通过命令行完成。

11.3.2. 创建数据库

数据库 [dbrdvmedecins2] 由脚本 [database/dbrdvmedecins2.sql] 创建。使用 [Laragon] 时,打开 [HeidiSQL] 工具(“数据库”按钮),然后通过“文件 / 运行 SQL”菜单运行该脚本。在命令行中,在应用程序文件夹下:

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

[-p] 选项会提示输入 [root] 的密码;如果该账户没有密码(如 [Laragon] 的情况),则省略它。这与 [ASP.NET Core] 版本使用的是同一个数据库:如果它已经存在,这一步是可选的。该脚本可以随时运行,以恢复到原始数据。

11.3.3. 配置数据库访问

所有配置设置都在文件 [src/main/resources/application.properties] 中(下文讨论)。默认情况下,应用程序连接到 [MySQL] ,位于 [localhost],端口 3306,使用用户 [root] 且没有密码:这是 [Laragon] 的默认设置。如果你的 [root] 账户有密码,最简单的方法是把它写在这个文件中,键为 [spring.datasource.password]。为了避免在项目文件中写入密码,你也可以通过环境变量来指定它,环境变量的优先级高于文件。它的名称由键名派生而来:大写字母,并把 [.] 和 [-] 替换为 [_]:

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

该变量只在定义它的终端中有效:然后在那里启动应用程序。

11.3.4. 启动应用程序

在 [rdvmedecins2-spring-mvc] 文件夹中用 [Visual Studio Code] 打开(文件菜单 / 打开文件夹),然后打开一个终端(终端菜单 / 新建终端),输入:

./mvnw spring-boot:run

在 [Windows] 下,在命令提示符中输入 [mvnw spring-boot:run] ,或者在 [.\mvnw spring-boot:run] 中输入 [PowerShell]。首次运行时,[mvnw] 会下载 [Maven],后者再下载所需的库、编译应用程序,然后启动它。在 [Maven] 的消息之后,控制台会显示应用程序的消息:

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

 :: 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

我们将在“启动应用程序”一节中再回到这个控制台。现在请注意这一行 [Tomcat started on port 8081]:应用程序已在地址 [http://localhost:8081] 就绪。使用 8081 端口可以让你同时运行一个课程示例(端口 5000)。应用程序的 [ASP.NET Core] 版本同样监听 8081 端口:不要同时运行两者。

在终端中输入 [Ctrl-C] 即可停止应用程序。

11.3.5. 演示账户

每个账户的密码就是它的用户名;你还必须输入图像中的字符,大写或小写均可:

用户名
角色
[admin]
ADMIN(管理员)
[pelissier]、[tatou]、[dupont]
DOCTOR(医生)
[martin]、[durand]、[bistrou]、[german]
USER(患者)

探索应用程序的指南:

  • [admin]:日程,Marie PELISSIER 女士,今天:有一个时间段已被 Brigitte BISTROU 女士预约。为 Jean MARTIN 先生预约一个时间段,然后尝试再为他预约第二次 (被拒绝)。“医生”和“患者”菜单:添加、编辑、删除(有预约的 PELISSIER 医生不能被删除);
  • [pelissier]:直接显示他的每日日程;手动输入的地址 [/doctors]会返回 403 错误页面;
  • [martin]:我的专区,他的预约,其他患者显示为“已预约”的日历;管理我的账户;
  • 登录页面:创建患者账户,然后用新账户登录;
  • FR / EN 按钮:整个界面切换语言,包括日期。

11.3.6. 开发模式

命令 [./mvnw spring-boot:run] 使用 配置文件 [dev] (参见下文的 [pom.xml])启动应用程序:此时控制台会显示由 [Hibernate] 发送给数据库的每条 SQL 命令(即上面控制台中的两行 [Hibernate: select ...])。另外两个工具有助于开发:

  • [Spring Boot DevTools] 库(参见 [pom.xml])会在 [target/classes] 文件夹中的某个类被重新编译时自动重启应用程序。[Visual Studio Code] 在每次保存时重新编译 [.java] 文件;否则,你就必须在第二个终端中输入 [./mvnw compile] 。重启只需几秒钟:只重新加载应用程序的类,而不重新加载库。另一方面,修改过的 [templates/*.html] 视图会在下次显示页面时被重新加载,只要它已以同样的方式被复制到 [target/classes] ;
  • 调试器:安装“Extension Pack for Java”后,“Run”和“Debug”链接会出现在 [main] 方法上方,位于 [RdvMedecinsApplication.java] 中;“Debug”会在调试器的控制下启动应用程序。点击代码行的边距即可设置断点。“Spring Boot Extension Pack”中的 Spring Boot Dashboard 视图提供相同的命令。

11.3.7. 可执行归档文件

要把应用程序安装到服务器上,请将其打包成一个单独的归档文件:

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

第一条命令编译应用程序并创建 [target/rdvmedecins-1.0.jar] 归档文件(约 60 MB):它包含应用程序、它的所有库,以及 [Tomcat] 服务器本身。第二条命令启动它:机器上只需要一个 JDK(或 JRE)21。以这种方式启动时,应用程序不带有 [dev] 配置文件(控制台不会显示 SQL 命令),归档文件中也没有 [Spring Boot DevTools] 。[application.properties] 中的每个键都可以在命令行上被替换,例如使用 [java -jar target/rdvmedecins-1.0.jar --server.port=9000]。

11.3.8. 常见问题

启动时,[Hibernate] 会查询数据库以确定其版本,然后应用程序从中读取医生和客户的列表:如果数据库无法访问,应用程序会立即停止,并在控制台中显示错误。这个错误往往淹没在很长的调用栈中,最后一行 [Caused by: ...] 的描述性不强([Unable to determine Dialect without JDBC metadata]:[Hibernate] 无法查询数据库)。相反,要寻找来自数据库本身的消息,[Hibernate] 也会在错误开头的一条警告中写出它。例如,对于一个不存在的数据库:

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)

最常见的消息:

消息
可能的原因
[Communications link failure] 或 [Connection refused]
[MySQL] 尚未启动,或者没有在 [localhost:3306] 上监听
[Access denied for user 'root'@'localhost']
必须输入 [MySQL] 的密码(参见“配置数据库访问”)
[Unknown database 'dbrdvmedecins2']
脚本 [database/dbrdvmedecins2.sql] 尚未运行
[rdvmedecins.auth.jwt-secret must be at least 32 characters long]
令牌的密钥在 [application.properties] 中太短
[Port 8081 was already in use]
8081 端口已被占用([ASP.NET Core] 版本是否在运行?):停止它,或者更改 [server.port]
[JAVA_HOME is not set] 或 [release version 21 not supported]
缺少 JDK,或者 JDK 版本低于 21
[Could not transfer artifact] 在 [mvnw] 运行时
无法访问 [Maven Central] 仓库(没有互联网连接、代理)

使用 [MariaDB] 时,[Hibernate] 在启动时还会显示一条无害的警告:[HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported]。[MariaDB] 实际上向 [MySQL] 驱动程序表明自己的版本号为“5.5.5”,[Hibernate] 把它理解为一个非常古老的 [MySQL]。

11.4. 应用程序架构

Image

  • 浏览器把请求发送给 [Tomcat] 服务器,该服务器集成在应用程序中。每个请求首先经过 [Spring Security] 的过滤器链(由 [config/SecurityConfig.java] 配置),它根据 Cookie 中的 JWT 令牌识别用户,并拒绝其访问受保护的页面;
  • [controllers]:Web 层控制器。它们都经由唯一的一个 Bean [ApplicationModel] (位于文件夹 [web]),该 Bean 把医生和客户的列表存储在内存中,并把其他请求转发给业务层;
  • [auth]:登录、JWT 令牌、验证码、尝试次数限制,以及账户创建的通行证;
  • [web]:Web 层的公共元素:缓存和 [ApplicationModel] 外观、翻译、闪现消息、验证、所有视图共有的属性,以及异常处理;[models]:表单和视图模型;
  • [business]:业务规则和事务;
  • [repositories]:DAO 层,每个表对应一个 [Spring Data JPA] 接口;
  • [entities]:[JPA] 实体,由 [Hibernate] 在数据库中读取和写入;[domain]:日历对象,由业务层计算得出;
  • [templates]:[Thymeleaf] 视图,生成 HTML 页面;[i18n]:字典,由翻译器使用;[static]:样式表、页面脚本和 [Bootstrap];
  • [config]:用 [Java] 编写的配置(安全、语言、闪现消息、类型化属性);[RdvMedecinsApplication.java] 启动整个流程。

应用程序文件夹:

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

这是 [Maven] 项目的标准组织方式,正如示例中所见:[Java] 代码位于 [src/main/java] 中,组织成包 ([Java] 包是一个类的文件夹,其名称——例如这里的 [rdvmedecins.web]——反映其路径);其他所有内容(配置、视图、字典、静态文件)位于 [src/main/resources] 中。编译期间,[Maven] 会把 [src/main/resources] 的内容复制到 [target/classes] 中,与编译后的类放在一起:它们共同构成应用程序的类路径——即虚拟机搜索类和文件所在的文件夹和归档文件的集合。这就是为什么代码把字典引用为 [i18n/fr.json],而不带前缀 [src/main/resources]。文件夹 [target] 由 [Maven] 创建,未在图中显示。

每个主要文件夹都包含一个名为 [README.md] 的文件,列出其中的文件。下表比较了应用程序两个版本中的文件夹:

ASP.NET Core MVC
Spring MVC
内容
[Program.cs]
[RdvMedecinsApplication.java]、[config/]
启动、配置
[Config/]
[config/]
类型化属性
[Auth/]
[auth/]
身份验证
[Controllers/]
[controllers/]
控制器
[Web/]、[Models/]
[web/]、[models/]
Web 层公共服务、模板
[Business/]
[business/]
业务层
[Repositories/], [Data/]
[repositories/]
DAO 层
[Entities/], [Domain/]
[entities/], [domain/]
实体、日历项
[Views/]
[templates/]
视图
[i18n/]
[i18n/]
字典
[wwwroot/]
[static/]
静态文件
[appsettings.json]
[application.properties]
配置
[RdvMedecins.csproj]
[pom.xml]
项目文件

下面按从底层(数据库)到上层(视图)的顺序,对所有文件逐一进行说明。

11.5. 数据库

数据库 [dbrdvmedecins2] 由脚本 [database/dbrdvmedecins2.sql] 创建(参见“创建数据库”)。它与 [ASP.NET Core] 版本的脚本一字不差,只是前面多了一行 [SET NAMES]:两个应用程序可以使用同一个数据库,且可以互相替换而无需任何修改。我们用两段摘录来说明:先是结构,然后是数据。

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Database [dbrdvmedecins2] - MySQL 8
--
-- Evolution of [dbrdvmedecins]:
--   1. the [doctors] and [clients] tables get a [user] column,
--      foreign key to users(id): every doctor and every client is
--      now also a user able to log in;
--   2. a third role appears: DOCTOR (in addition to ADMIN and USER);
--   3. the script creates a [users] row for each doctor (role DOCTOR)
--      and for each client (role USER):
--        - login        = last name in lower case
--        - password     = last name in lower case, hashed with bcrypt (10 rounds)
--        - display name = first name + last name
--
--   4. uniqueness constraints, all NAMED (the application recognizes
--      the name of the violated constraint in the MySQL error message):
--        - unq_users_login                   : a login belongs to one account only;
--        - unq_doctors_first_name_last_name  : two doctors cannot have the
--                                              same first and last names;
--        - unq_clients_first_name_last_name  : same for the clients.
--      Beware: the utf8mb4_unicode_ci collation compares regardless of
--      case and accents - "Hélène DUPONT" and "helene dupont"
--      are therefore considered identical.
--
-- The [users] table must now be created BEFORE [doctors] and [clients]
-- (they reference it), and dropped AFTER them.
-- =========================================================================

-- the script is written in UTF-8
SET NAMES utf8mb4;

-- we start again from an empty database on each run of the script (handy in development)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- drop order: from the "child" tables to the "parent" tables
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;

-- -------------------------------------------------------------------------
-- table [users]: the users allowed to log in to the application
-- -------------------------------------------------------------------------
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'
  -- a login can belong to one account only
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- table [doctors]: the doctors of the practice
-- -------------------------------------------------------------------------
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),
  -- one account per doctor, and one doctor per account
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- two doctors cannot have the same first and last names
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- table [clients]: the doctors' patients
-- -------------------------------------------------------------------------
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),
  -- one account per client, and one client per account
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- two clients cannot have the same first and last names
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- table [slots]: the time slots of each doctor
-- -------------------------------------------------------------------------
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)
);

-- -------------------------------------------------------------------------
-- table [appointments]: the appointments booked by the clients
-- -------------------------------------------------------------------------
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),
  -- the same slot, on the same day, can be booked only once
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

我们来说明这第一部分:

  • 第 30 行:脚本告知服务器它是用 UTF-8 编写的。如果没有这一行,在某些系统上 [mysql] 客户端会以另一种编码发送带重音的字符(“Hélène”),导致它们被错误地存储;
  • 第 33 行:如果数据库尚不存在则创建它,字符集为 [utf8mb4] ,排序规则为 [utf8mb4_unicode_ci],与示例 28 相同:字符串比较忽略大小写和重音。这同样适用于唯一性约束:对 [Hélène DUPONT] 和 [helene dupont] ,[MySQL] 认为它们是同一个人的两个实例,“Admin”与“admin”也是同一个登录名;
  • 第 37–41 行:脚本每次运行都从一个空数据库开始。表按照从“子”表到“父”表的顺序删除:被外键引用的表([users],例如被 [doctors] 和 [clients] 引用)只要还有其他表引用它,就无法删除。创建表时则按相反的顺序进行;
  • 第 46–55 行:用户账户。每个表都以由数据库分配的主键 [id]([AUTO_INCREMENT])开头,并有一个 [version] 列,创建行时该列设为 0;
  • 第 49–52 行:登录名、密码、登录后显示的名称以及角色([ADMIN]、[DOCTOR]或 [USER])。[password] 列从不包含密码本身,而是包含其哈希值,[bcrypt] (参见示例 25):60 个字符,该列(100 个字符)完全容纳得下;
  • 第 54 行:一个登录名只属于一个账户。与示例 28 中一样,该约束是有名称的:当 [MySQL] 拒绝一次写操作时,其错误消息会指明被违反的约束的名称,业务层据此选择要显示的消息(参见“业务层”);
  • 第 60–72 行:医生:称谓、姓、名;
  • 第 62 行:[version] 列用于乐观锁 (参见示例 28):每次修改该行时它都会递增,从而可以检测在读取与写入之间,是否有其他用户修改过该行。在这里,递增它的是 [Hibernate] ,这要归功于实体上的 [@Version] 注解(参见“实体”);
  • 第 66–67 行:每位医生都有一个账户:[user] 列是引用 [users(id)] 的外键。数据库会拒绝不指向任何账户的值,也拒绝删除仍被某位医生引用的账户。由于 [user] 是 [MySQL] 的保留字,列名用反引号括起来;
  • 第 69 行:一个账户只属于一位医生:[doctors] 与 [users] 之间是“一对一”关系;
  • 第 71 行:两位医生不能有相同的姓和名。该约束作用于这一对列:如果名不同,两位医生可以有相同的姓。但医生和客户可以有相同的姓:它们是两个不同的表;
  • 第 77–89 行:客户(患者)遵循相同的模型:每个客户一个账户(外键 [fk_clients_user],唯一性约束 [unq_clients_user]);任何两个客户都不能有相同的姓和名;
  • 第 94–103 行:每位医生的时间段(外键 [doctor_id]):起始小时和分钟、结束小时和分钟。时间段没有日期:它每天重复;
  • 第 108–118 行:预约:一个日期(类型 [DATE],不含时间)、一个时间段和一个客户,通过两个外键来标识;
  • 第 117 行:同一时间段每天只能被预订一次。这条规则由数据库自身强制执行:如果两个用户同时预订同一时间段,则第二个 [INSERT] 会被拒绝,无论应用程序在此之前验证了什么。

脚本的第二部分插入示例数据:

-- =========================================================================
-- Demo data
-- =========================================================================

-- the users: passwords hashed with bcrypt (10 salt rounds)
--   admin/admin (ADMIN)
--   one DOCTOR account per doctor, one USER account per client
--   (the user/user demo account is gone: a USER account is
--   now ALWAYS a client's account, who can book and manage the account)
--   (login = password = last name in lower case)
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');

-- the doctors: the [user] column is looked up from the login,
-- rather than assuming the values of the primary keys of [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'));

-- slots of doctor PELISSIER (doctor_id = 1): from 8:00 to 12:00 in 20-minute steps
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);

-- slots of doctor TATOU (doctor_id = 2): from 14:00 to 18:00 in 20-minute steps
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);

-- an appointment already booked, to see an occupied slot right away in the schedule
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • 第 5–21 行:演示账户:管理员、三位医生(角色 [DOCTOR])和四个客户(角色 [USER])。每个用户的密码就是其登录名([admin] / [admin],[pelissier] / [pelissier]……)。哈希值以 [$2b$10$] 开头:即 [bcrypt] 算法的 [2b] 版本,成本因子为 10(参见示例 25)。[Spring Security] 的 [BCryptPasswordEncoder] 编码器经配置后针对同一版本,可以验证它们(参见“身份验证”);
  • 第 25–28 行:每位医生的 [user] 列是通过基于登录名的子查询 获取的,而不是假定数据库分配给这些账户的凭据;
  • 第 30–34 行:客户的处理方式相同;
  • 第 36–41 行:为 PELISSIER 医生设置的十二个 20 分钟的时间段,从上午 8:00 到中午 12:00。这里医生的 ID(1)是硬编码的:[doctors] 表刚刚创建,因此其 ID 从 1 开始;
  • 第 43–48 行:为 TATOU 医生设置的十二个时间段,从下午 2:00 到 6:00。DUPONT 医生没有时间段:他的日程是空的;
  • 第 50–52 行:已为 Brigitte BISTROU(客户 3 号)在 PELISSIER 医生的第二个时间段(上午 8:20)预订了一次预约。[CURDATE()] 是脚本运行的日期:因此首次登录时,今天的日历会显示一个已被预订的时间段。

11.6. 项目配置

11.6.1. pom.xml

文件 [pom.xml] ([Project Object Model])在 [Maven] 中描述项目:其标识、[Java] 的版本、所用的库,以及如何启动应用程序。它相当于 [RdvMedecins.csproj] 文件,对应 [ASP.NET Core] 版本。各个示例都有自己的 [pom.xml] 文件,它们都派生自位于 [examples] 文件夹中的公共 [pom.xml] 文件;案例研究是一个独立的项目,所有内容都写在它自己的文件里。

<?xml version="1.0" encoding="UTF-8"?>
<!--
  =========================================================================
  pom.xml - the Maven project file: identity of the project, Java version,
  libraries used, and plugin that compiles and runs the application.

  The libraries (dependencies) are downloaded from Maven Central
  during the first build, and stored in the ~/.m2 folder of the
  user. Their versions are not written here: they are set,
  all compatible with each other, by the Spring Boot parent project.
  =========================================================================
-->
<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,LTS 版本(长期支持) -->
    <java.version>21</java.version>
  </properties>

  <dependencies>
    <!-- Spring MVC 以及嵌入在应用中的 Tomcat Web 服务器 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <!-- Thymeleaf 视图 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- 表单验证(Bean Validation、Hibernate Validator) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- Spring Security:JWT 令牌身份验证、角色、bcrypt 哈希 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security-oauth2-resource-server</artifactId>
    </dependency>
    <!-- Spring Data JPA:Hibernate ORM、事务、仓库 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <!-- MySQL JDBC 驱动程序(也适用于 MariaDB) -->
    <dependency>
      <groupId>com.mysql</groupId>
      <artifactId>mysql-connector-j</artifactId>
      <scope>runtime</scope>
    </dependency>
    <!-- 开发工具:修改后自动重启 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-devtools</artifactId>
      <optional>true</optional>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <!-- mvnw spring-boot:run runs the application, with the [dev] profile
           (see 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>

我们来说明这个文件:

  • 第 18–23 行:父项目 [spring-boot-starter-parent],版本为 [Spring Boot] 4.1.1。项目继承它的设置:源文件的 UTF-8 编码、编译器配置、插件配置,而最重要的是 [Spring Boot] 能够集成的所有库的版本 ——这些版本经过挑选,彼此兼容。这就是为什么下面列出的依赖都没有指定版本。要升级到更新版本的 [Spring Boot],只需修改第 21 行;
  • 第 22 行:空元素 [relativePath] 告诉 [Maven] 不要在项目的上级文件夹中查找父项目(示例的父项目就位于那里),而是到库仓库中查找;
  • 第 25–28 行:项目的标识:组(按惯例是反向域名)、构件名称、版本以及便于阅读的名称。由 [./mvnw package] 创建的归档文件名为 [artifact-version.jar],即 [rdvmedecins-1.0.jar]。由于没有提供 [packaging] 元素,它是 [jar] 归档,这是默认情况;
  • 第 30–33 行:[Java] 版本:编译器为 [Java] 21 生成代码,并拒绝使用更旧的 JDK 编译;
  • 第 35–73 行:依赖。其中几乎全部都是 [Spring Boot] 的启动器:启动器是一种本身不提供代码、而是为某项功能引入一组协调一致的库的依赖。每个启动器还会在启动时触发相应的自动配置(参见“应用程序启动”);
  • 第 37–40 行:[Spring MVC] 和 [Tomcat] Web 服务器,集成在应用程序中:无需安装任何服务器;应用程序本身就是一个 Web 服务器;
  • 第 42–45 行:[Thymeleaf] 视图引擎(参见示例 13);
  • 第 47–50 行:表单验证:[Bean Validation] API([@NotBlank]、[@Size]……)及其实现 [Hibernate Validator] (参见示例 19);
  • 第 52–55 行:[Spring Security]及其“资源服务器”模块 [OAuth2],它可以验证 JWT 令牌(参见示例 25)。它还提供密码哈希算法 [bcrypt] :无需单独的库;
  • 第 57–60 行:[Spring Data JPA],以及 ORM [Hibernate]、事务管理器和连接池 [HikariCP] (参见示例 28);
  • 第 62–66 行:[MySQL] 的 JDBC 驱动 [mysql-connector-j],它同样适用于 [MariaDB]。作用域 [runtime] (第 65 行)表示应用程序代码在编译时不需要它(它只与 JPA 和 JDBC 打交道);驱动只在运行时加载;
  • 第 68–72 行:[Spring Boot DevTools],开发工具(自动重启)。[optional] (第 71 行):该依赖不会传递给依赖本项目的其他项目,并且 [Spring Boot] 插件不会把它包含在可执行归档中:它只在开发期间使用;
  • 第 79–87 行:用于 [Maven] 的 [Spring Boot] 插件。该插件提供 [spring-boot:run] 命令,并且在执行 [./mvnw package] 时,把标准的 [jar] 归档转换为包含所有库的可执行归档;
  • 第 82–86 行:[spring-boot:run] 激活 [dev] 配置文件(profile),它会把 [application-dev.properties] 文件添加到配置中(见下文)。配置文件(profile)是指代一组设置的名称;这一个只适用于 [spring-boot:run]:由 [java -jar] 启动的应用程序没有激活的配置文件,除非显式指定([java -jar target/rdvmedecins-1.0.jar --spring.profiles.active=dev])。

11.6.2. Maven Wrapper

Maven Wrapper 使你无需安装 [Maven] 即可构建项目。它由三个文件组成:

  • [mvnw] (用于 [Linux] 和 [macOS])和 [mvnw.cmd] (用于 [Windows]):两个由 [Apache Maven] 项目提供的脚本,不应修改,此处也不再复述。它们读取下面的文件,如果尚未存在,就下载其中指定的 [Maven] 版本,将其放入用户主目录下的 [.m2/wrapper] 文件夹中,然后执行以下命令:[./mvnw spring-boot:run] 即以正确的 [Maven] 版本运行 [mvn spring-boot:run];
  • [.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
  • 第 1 行:Maven Wrapper 自身的版本;
  • 第 2 行:[only-script]:wrapper 仅由脚本 [mvnw] 和 [mvnw.cmd] 组成,不含其早期版本所使用的 [maven-wrapper.jar] 归档;
  • 第 3 行:[Maven] 发行版的下载链接:版本 3.9.11。这样,所有构建该项目的人都使用同一个 [Maven] 版本,而不管他们的机器上可能安装了哪个版本。

[Maven] 下载的库存放在主目录下的 [.m2/repository] 文件夹中:它们由所有项目共享,且只下载一次。

11.6.3. src/main/resources/application.properties

文件 [application.properties] 的作用与 [ASP.NET Core] 版本中的 [appsettings.json] 文件相同。每一行把一个值与一个键关联起来;键以句点分隔([spring.datasource.url])。[Spring Boot] 包含数百个用于配置其组件的键(以 [server.]、[spring.] 等开头的那些);应用程序可以添加自己的键(这里是以 [rdvmedecins.] 开头的那些)。以 [#] 开头的行是注释。

# =========================================================================
# application.properties - 应用的配置。
#
# 每个值都可以在不修改此文件的情况下,通过
# 环境变量来替换:此时 spring.datasource.password 写作
# SPRING_DATASOURCE_PASSWORD(大写,"." 和 "-" 替换为 "_")。
# =========================================================================

# 监听端口:既不是 8080(Spring Boot 的默认端口,常常已被
# 占用),也不是 5000(示例所用的端口)- 这样一切都可以同时运行
server.port=8081

# —— MySQL 数据库 [dbrdvmedecins2](脚本:database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# Hibernate 既不创建也不修改表:这是 SQL 脚本的职责
spring.jpa.hibernate.ddl-auto=none
# 在构建视图期间,不保持与数据库的连接处于打开状态
spring.jpa.open-in-view=false

# —— 请求由“虚拟”线程处理(Java 21):等待数据库的
# 线程不再阻塞系统线程
spring.threads.virtual.enabled=true

# —— 错误响应从不包含调用栈
spring.web.error.include-stacktrace=never

# —— 身份验证(参见 config/AuthProperties.java)
# JWT 令牌的密钥:至少 32 个字符(HMAC-SHA256)。
# 在生产环境中必须修改(使用较长的随机字符串)。
rdvmedecins.auth.jwt-secret=change-me-to-a-long-random-string
# 令牌的有效期,以秒为单位(7200 秒 = 2 小时);承载
# 令牌的 Cookie 具有相同的有效期
rdvmedecins.auth.jwt-expires-in-seconds=7200
# 在生产环境中为 true(站点通过 HTTPS 提供):身份验证 Cookie
# 这样就绝不会通过未加密的连接发送
rdvmedecins.auth.cookie-secure=false

# —— 防范机器人(参见 config/ProtectionProperties.java)
# 登录:同一 IP 地址上同一登录名允许的失败次数……
rdvmedecins.protection.login-max-failures=5
# ……超过后将封锁这段时长(如果同一 IP 地址累计的失败次数
# 达到其 5 倍,所有登录名合计,则整个 IP 地址也会被封锁)
rdvmedecins.protection.login-block-minutes=15
# 客户账户创建:每小时、每个 IP 地址允许创建的账户数上限。
# 在教室里,所有计算机常常通过同一个地址出去:
# 如有需要请调高。
rdvmedecins.protection.registration-max-per-hour=10

我们来说明这个文件:

  • 第 11 行:[Tomcat] 服务器的监听端口。[Spring Boot] 的默认端口是 8080;各个示例监听 5000 端口;本应用程序监听 8081 端口,与 [ASP.NET Core] 版本一致;
  • 第 14 行:数据库地址,采用 JDBC URL 的形式(参见示例 28):协议 [jdbc:mysql],后接服务器、端口和数据库名称。[Spring Boot] 据此确定要加载哪个驱动;
  • 第 15–16 行:[MySQL] 的用户名和密码;默认情况下,[Laragon] 的用户名是 [root],没有密码。如果 [root] 账户有密码,就要填写第 16 行;
  • 第 18 行:[Hibernate] 可以根据实体自行创建或修改表;在这里,它不修改表:数据库结构就是 SQL 脚本中的结构,与 [ASP.NET Core] 版本共享;
  • 第 20 行:默认情况下,[Spring Boot] 会让数据库连接一直保持打开直到请求结束,包括生成视图的期间(即“open in view”模式),并在启动时用一条警告提示这一选择。应用程序禁用了这一行为,如示例 28 所示:视图所需的全部数据都由业务层在其事务内读取,然后才渲染视图。这样,连接保持打开的时间绝不会超过必要的时长;
  • 第 24 行:请求由虚拟线程处理,这是 [Java] 21 中的新特性。Web 服务器在一个线程(执行线程)中处理每个请求;系统线程是一种昂贵的资源,而 [Tomcat] 只维护有限数量的线程(默认 200 个)。然而,一个等待数据库响应的线程什么也不做,却仍被占用。虚拟线程是由虚拟机管理的轻量级线程:当它在等待时,原本承载它的系统线程会去执行另一个线程。应用程序代码无需改动即可利用这一点;
  • 第 27 行:错误响应从不包含调用栈,否则会向攻击者暴露应用程序的内部运作(参见第 1 章);
  • 第 32–38 行:身份验证的密钥:用于对令牌签名的密钥(至少 32 个字符;在生产环境中必须替换为一个较长的随机字符串)、令牌的有效期(两小时),以及承载令牌的 Cookie 中的 [Secure] 选项。在生产环境中,站点以 HTTPS 提供服务,Cookie 绝不能通过未加密的连接传输:该选项设为 [true];
  • 第 42–49 行:防机器人保护的阈值(参见示例 27):允许的登录失败次数及由此产生的封锁时长;同一 IP 地址每小时可创建的客户账户数量。

键 [rdvmedecins.auth.*] 和 [rdvmedecins.protection.*] 被读取为类型化的 record(参见下面的 [config/AuthProperties.java])。在文件中,复合名称用以连字符分隔的小写字母书写([jwt-secret]):这是 [Spring Boot] 使用的约定,它会把这些名称映射到 [Java] 中的名称([jwtSecret])。

[Spring Boot] 从多个依次排列的来源读取配置,每个来源都可以覆盖前面来源的值:[application.properties],然后是每个激活的配置文件对应的 [application-{profile}.properties] (参见下一个文件),再是环境变量,最后是命令行参数([--server.port=9000])。环境变量的名称由键派生而来:大写字母,并把 [.] 和 [-] 替换为 [_]。因此 [spring.datasource.password] 变为 [SPRING_DATASOURCE_PASSWORD],而 [rdvmedecins.auth.jwt-secret] 变为 [RDVMEDECINS_AUTH_JWT_SECRET]:在生产环境中,就是这样向应用程序提供机密信息,而无需把它写入项目文件。

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

1
2
3
4
5
6
# =========================================================================
# application-dev.properties - 在 [dev] 配置文件处于激活状态时,
# 对 application.properties 进行补充(mvnw spring-boot:run 会激活它,参见 pom.xml):
# Hibernate 发送的 SQL 语句会显示在控制台中。
# =========================================================================
spring.jpa.show-sql=true
  • 第 6 行:当 [dev] 配置文件处于激活状态时,[Spring Boot] 会在 [application.properties] 之后读取 [application-dev.properties] 文件,并将两者合并:第二个文件中的键会替换第一个文件中的键;其余的键保留。因此,在开发期间会增加键 [spring.jpa.show-sql]:[Hibernate] 会把它发送给数据库的每条 SQL 命令输出到控制台,并以 [Hibernate:] 作为前缀。这相当于 [ASP.NET Core] 版本中的 [appsettings.Development.json] 文件,配置文件的作用相当于 [Development] 环境。我们已经看到,是 [pom.xml] 为 [spring-boot:run] 激活了这个配置文件。

11.6.5. config/AuthProperties.java

// =========================================================================
// config/AuthProperties.java
// -------------------------------------------------------------------------
// application.properties 中的 [rdvmedecins.auth.*] 属性,以
// 带类型的 record 形式给出。Spring Boot 会匹配名称:
//   rdvmedecins.auth.jwt-secret             -> jwtSecret
//   rdvmedecins.auth.jwt-expires-in-seconds -> jwtExpiresInSeconds
//   rdvmedecins.auth.cookie-secure          -> cookieSecure
// 并将值转换为各组件的类型(int、boolean)。
// 需要它的类通过依赖注入接收这个 record:
// 这样就避免了到处读取字符串。
// =========================================================================
package rdvmedecins.config;

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

@ConfigurationProperties("rdvmedecins.auth")
public record AuthProperties(
        // 用于签署 / 验证 JWT 令牌的密钥。HMAC-SHA256
        // 算法要求密钥至少为 256 位,即 32 字节。
        String jwtSecret,
        // 令牌的有效期,以秒为单位;承载它的 Cookie
        // 具有相同的有效期
        int jwtExpiresInSeconds,
        // 在生产环境(HTTPS)中为 true:身份验证 Cookie 绝不会
        // 通过未加密的连接发送
        boolean cookieSecure) {
}

我们来说明这段代码:

  • 第 18 行:[application.properties] 中的键 [rdvmedecins.auth.*],以 record 的形式呈现:这是一个类,其字段——在括号中声明(record 的“组件”)——由构造函数一次性设定。编译器会自动生成该构造函数,以及每个组件的同名 getter 方法:[jwtSecret()]、[jwtExpiresInSeconds()]、[cookieSecure()];
  • 第 17 行:注解 [@ConfigurationProperties] 指定键的前缀。启动时,[Spring Boot] 使用键 [rdvmedecins.auth.jwt-secret]、[rdvmedecins.auth.jwt-expires-in-seconds] 和 [rdvmedecins.auth.cookie-secure] 的值调用构造函数来创建该 record,并将这些值转换为每个组件的类型(["7200"] 变为整数 7200,[false] 变为布尔值 [false])。无法转换的值(在期望数字的地方写了文本)会导致应用程序在启动时崩溃,并给出指明出错的键的消息。缺失的键则得到该类型的默认值:[null]、0 或 [false];
  • 第 21–27 行:三个组件。该 record 成为一个 Bean,需要它的类通过构造函数接收它(依赖注入;参见示例 06):[config/SecurityConfig.java] 和 [auth/AuthService.java] 就是这样做的(参见“身份验证”)。这样就避免了到处读取字符串:名称由编译器验证,值也已经完成转换。

这正是示例 25 中使用的技术,该示例使用注解 [@EnableConfigurationProperties(JwtProperties.class)] 声明了它的 record。案例研究中有两个这样的 record,并借助主类上的 [@ConfigurationPropertiesScan] 注解让 [Spring Boot] 自行找到它们(参见“启动应用程序”)。

11.6.6. config/ProtectionProperties.java

// =========================================================================
// config/ProtectionProperties.java
// -------------------------------------------------------------------------
// [rdvmedecins.protection.*] 属性:防范机器人的
// 阈值(参见 auth/AttemptLimiterService.java)。
// =========================================================================
package rdvmedecins.config;

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

@ConfigurationProperties("rdvmedecins.protection")
public record ProtectionProperties(
        // 登录:同一 IP 地址上同一登录名允许的失败次数(验证码或密码错误),
        // 超过后这一组合将被封锁……
        int loginMaxFailures,
        // ……封锁这段时长(如果同一 IP 地址累计的失败次数
        // 达到其 5 倍,所有登录名合计,该 IP 地址也会被封锁)
        int loginBlockMinutes,
        // 客户账户创建:同一 IP 地址
        // 每小时允许创建的账户数上限
        int registrationMaxPerHour) {
}
  • 第 11–21 行:键 [rdvmedecins.protection.*],遵循相同的模式。该 record 被注入到 [auth/AttemptLimiterService.java] 中,后者从中读取其阈值(参见“身份验证”)。

11.7. 应用程序启动

[ASP.NET Core] 版本把所有与启动相关的功能都集中在 [Program.cs] 中:注册每个服务,然后按特定顺序构建中间件管道。而使用 [Spring Boot] 时,这项工作是分散的:主类只负责启动 [Spring Boot];由它根据可用的库和 [application.properties] 自行配置各项基本内容;而应用程序希望以不同方式配置的每个方面,都有自己的配置类,位于 [config] 文件夹中。

11.7.1. RdvMedecinsApplication.java

// =========================================================================
// RdvMedecinsApplication.java
// -------------------------------------------------------------------------
// 应用的入口点:main 方法启动 Spring Boot。
//
// @SpringBootApplication 汇集了三个注解:
//   - @Configuration:该类可以声明 Bean(@Bean);
//   - @EnableAutoConfiguration:Spring Boot 自行配置所存在的
//     库所需的内容(Spring MVC、Thymeleaf、JPA、Spring
//     Security 等),依据 application.properties;
//   - @ComponentScan:Spring 在 [rdvmedecins] 包及其
//     子包中查找带注解的类(@Controller、
//     @Service、@Component、@Repository 等),并将它们变为 Bean,
//     提供给需要它们的对象(依赖注入)。
//
// @ConfigurationPropertiesScan:带有 @ConfigurationProperties 注解的 record
// (config 包)会接收 application.properties 的值。
//
// 这里没有与 ASP.NET Core 的 Program.cs 中的“中间件管道”相对应的东西:
// 过滤器的顺序由 Spring Boot 和 Spring Security 设定,并且
// 每个方面都在各自的类中配置(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);
    }
}

我们来说明这段代码:

  • 第 34–36 行:[main] 方法,是任何 [Java] 程序的入口点,如各个示例中所示。[SpringApplication.run] 创建 [Spring] 的容器(即“应用上下文”,它创建并管理所有 Bean),启动服务器 [Tomcat],然后交还控制权;只要服务器仍在监听,程序就会继续运行。作为参数传入的类充当配置的起点;
  • 第 30 行:[@SpringBootApplication] 注解——所有示例中就已经出现过——综合了文件注释(第 6–14 行)中详细说明的三个注解。[@ComponentScan] 使 [Spring] 遍历 [rdvmedecins] 包及其所有子包:每个带注解的类——[@Controller]、[@Service]、[@Component] (或 [@Configuration]、[@ControllerAdvice]……)——都会在其中成为一个 Bean。[Spring Data JPA] 的仓库接口也以同样的方式在相同的包中被找到,这是通过 [Spring Data JPA] 的自动配置实现的(见下文)。因此,与 [Program.cs] 中不同,这里没有需要维护的服务列表:只需把一个带注解的类添加到这些包之一即可。这就是主类被放在根包中、位于所有其他类之上的原因;
  • 第 31 行:[@ConfigurationPropertiesScan] 对带有 [@ConfigurationProperties] 注解的 record 做同样的事情(参见 [config/AuthProperties.java])。

应用程序的 Bean 全都是单例:一个由所有请求共享的实例。[ASP.NET Core] 版本区分三种生命周期([Singleton]、[Scoped]、[Transient]),因为它的 DAO 层依赖于为每个请求创建的 [DbContext] 实例。而在 [Spring] 中,仓库和业务层不依赖任何请求:由 [Spring] 为每个处理任务提供一个取自连接池 (由已打开的连接组成的池,在查询之间复用)的连接,并且对于业务层的写操作,还提供其事务。这一点会在 DAO 层和业务层的章节中更详细地讨论。

11.7.2. Spring Boot 自动配置的内容

[@EnableAutoConfiguration](包含在 [@SpringBootApplication] 中)会触发自动配置:启动时,[Spring Boot] 会扫描类路径中存在的库以及应用程序已经声明的 Bean,并自行创建缺失的 Bean,按照 [application.properties] 进行配置。上面显示的启动控制台可以让你监视这一过程:

配置的内容
由何提供
控制台日志
[Tomcat] 服务器,端口为 [server.port]
[spring-boot-starter-webmvc]
[Tomcat initialized with port 8081],然后是 [Tomcat started on port 8081]
[DispatcherServlet] Servlet,即 [Spring MVC] 的前端控制器,它接收所有请求并将其分发给各个动作
[spring-boot-starter-webmvc]
[Initializing Servlet 'dispatcherServlet'],在第一次请求时
[static/] 文件夹中的静态文件,原样提供([/css/styles.css]……)
[spring-boot-starter-webmvc]
无
[Thymeleaf] 引擎:视图 [schedule] 就是文件 [templates/schedule.html]
[spring-boot-starter-thymeleaf]
无
表单验证器([Hibernate Validator])
[spring-boot-starter-validation]
无
数据源([DataSource]):指向 URL [spring.datasource.url] 的连接池 [HikariCP]
[spring-boot-starter-data-jpa]、[mysql-connector-j]
[HikariPool-1 - Start completed]
[Hibernate] ([EntityManager] 和 [JPA] 的“工厂”)、事务管理器,以及业务层使用的 [TransactionTemplate] Bean
[spring-boot-starter-data-jpa]
[Hibernate ORM core version 7.4.5.Final]、[Database info]、[Initialized JPA EntityManagerFactory]
[repositories/] 文件夹中五个仓库接口各自的实现(第六个 [PersonRepository] 是医生和客户共有的模型,被标记为 [@NoRepositoryBean]:[Spring Data JPA] 不会实现它)
[spring-boot-starter-data-jpa]
[Found 5 JPA repository interfaces]
自动重启,并禁用 [Thymeleaf] 视图缓存
[spring-boot-devtools]
[Devtools property defaults active!]、[restartedMain]

我们来说明这段控制台输出中的几行:

  • [The following 1 profile is active: "dev"]:由 [pom.xml] 激活的配置文件;因此会读取 [application-dev.properties] ;
  • [restartedMain] 是启动应用程序的线程的名称:它属于 [Spring Boot DevTools],每次重新编译后它都会重启应用程序。如果由 [java -jar] 启动,没有 DevTools,应用程序则在 [main] 线程中启动;
  • 警告 [HHH000511] 仅在使用 [MariaDB] 时出现(参见“常见问题”);
  • 这两行 [Hibernate: select ...] 是加载缓存的请求(见下文),通过 [dev] 配置文件显示。在这里我们可以看到 [Hibernate] 根据实体推导出的连接查询,用来获取每位医生及其账户 [users];
  • [Tomcat started on port 8081] 出现在这些请求之后:服务器只有在所有 Bean(包括缓存)都创建完毕后才接受请求;
  • 最后三行只在第一次请求时出现:[Spring Boot] 只在需要时才初始化 [DispatcherServlet]。它们所在的线程 [tomcat-handler-0] (控制台只显示名称的末尾部分)是一个虚拟线程(参见 [application.properties])。

自动配置对应用程序让位:只有当应用程序没有声明具有相同作用的 Bean 时,它才会创建该 Bean。应用程序正是这样覆盖不符合其需求的默认设置的:

  • 安全:如果不做配置,[Spring Boot] 会用一个登录表单和启动时生成的密码来保护所有页面;[config/SecurityConfig.java] 声明了它自己的过滤器链和它自己的 JWT 令牌解码器(参见“身份验证”);
  • 翻译:Bean [messageSource]([Thymeleaf] 在其表达式 [#{...}] 中使用它)是类 [web/Translator.java],它读取 JSON 字典(参见示例 22 和“Web 层:共享服务”);
  • 错误页面:错误(400、403、404、500……)由服务器在地址 [/error] 处理。[Spring Boot] 通常在那里放置它自己的控制器;[controllers/ErrorController.java] 取代了它的位置(参见示例 24 和“Web 层:控制器”);
  • 每个请求的语言和闪现属性:这是 [config/WebConfig.java] 中的两个 Bean,下文将进行讨论。

同样,也不像 [Program.cs] 中那样需要配置中间件管道:每个请求都会先经过 [Spring Security] 的过滤器链——其顺序由 [Spring Security] 自身决定——然后才到达 [DispatcherServlet],后者根据控制器上的注解选择动作(参见示例 24)。

11.7.3. config/WebConfig.java

// =========================================================================
// config/WebConfig.java
// -------------------------------------------------------------------------
// 对 Spring MVC 配置的补充:
//   - 每个请求的语言,从 Cookie 中读取(参见示例 22);
//   - 闪现属性,存放在 Cookie 中(参见 web/CookieFlashMapManager)。
// src/main/resources/static 文件夹中的静态文件(css/、js/、
// lib/bootstrap/)由 Spring Boot 提供,无需配置。
// =========================================================================
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 {

    // 每个请求的语言:取自 [rdvmedecins_language] Cookie,
    // 由 LanguageController 设置;否则为英语。该 Bean 必须命名为
    // [localeResolver]:Spring MVC 正是以这个名称查找它的。
    @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;
    }

    // 闪现属性存放在 Cookie 中,而不是 HTTP 会话中。该 Bean
    // 必须命名为 [flashMapManager]:这样它就会取代 Spring MVC 的那个。
    @Bean
    public FlashMapManager flashMapManager() {
        return new CookieFlashMapManager();
    }
}

我们来说明这段代码:

  • 第 23 行:带有 [@Configuration] 注解的类通过带有 [@Bean] 注解的方法来声明 Bean(参见示例 06)。启动时,[Spring] 会对这些方法各调用一次,并把得到的对象存储为 Bean。Bean 以方法名命名;
  • 第 30 行:[LocaleResolver] 确定每个请求的语言([Locale])。[Spring MVC] 按名称 [localeResolver] 查找它:正是这个方法名使它成为对 [Spring Boot] 默认实现(它会遵循浏览器的首选语言)的替代;
  • 第 31 行:语言从 [rdvmedecins_language] Cookie 中读取,与示例 22 中一样。当 [controllers/LanguageController.java] 向同一个对象发送所选语言(FR / EN 按钮)时,该 Cookie 就由它设置;
  • 第 32 行:没有 Cookie 时,语言为英语;
  • 第 33–35 行:该 Cookie 的有效期为一年;它是 [HttpOnly] (页面的脚本无法读取它),并且是 [SameSite=Lax] (浏览器不会在由其他站点发起的请求中发送它,单纯导航到本应用程序的情况除外);
  • 第 41–44 行:[FlashMapManager] 在 POST 与随后的重定向之间保留闪现属性(Post/Redirect/Get 模式;参见示例 20)。[Spring MVC] 的这个 Bean 把它们存储在 HTTP 会话中;然而,应用程序是无状态的:它不会在请求之间保留任何用户数据,因为用户是通过其 Cookie 中的 JWT 令牌来识别的。因此,名为 [flashMapManager] 的 Bean 取代了 [Spring MVC] 中同名的那个,换成类 [web/CookieFlashMapManager.java],它把闪现属性存储在 Cookie 中(参见“Web 层:共享服务”)。

11.7.4. 启动时加载缓存

医生和客户的列表几乎显示在每个页面上(日历中的下拉列表、管理页面)。应用程序没有在每次请求时都从数据库中获取它们,而是把它们保存在内存中的 [web/ApplicationModel.java] Bean 里,所有控制器都经由它。每当添加、修改或删除医生或客户之后,该 Bean 都会重新加载它们。

初始加载发生在启动时,在该 Bean 中一个带有 [@PostConstruct] 注解的方法里。该注解指示 [Spring] 在对象创建完毕并且其依赖(这里是业务层)注入之后调用该方法:因此是在启动期间,在服务器接受第一个请求之前。它们就是控制台中的那两个 [Hibernate: select ...] 请求。读取错误不会被捕获:应用程序会立即停止,错误显示在控制台中。数据库不可访问(URL 错误、[MySQL] 服务器已停止)实际上会让应用程序停止得更早,在 [Hibernate] 初始化时就会停止(参见“常见问题”)。

为了进行这次加载,[ASP.NET Core] 版本不得不在 [Program.cs] 中显式创建一个“作用域”,因为它的外观依赖于某个请求的 [DbContext]。这里则不是这样:[ApplicationModel] 是一个单例,就像它所使用的业务层一样。该文件在“Web 层:共享服务”一节中有说明。

11.7.5. 从 ASP.NET Core 的 Program.cs 到 Spring Boot

对于熟悉 [ASP.NET Core] 版本的读者,下面说明 [Program.cs] 的每个部分在哪里:

Program.cs(ASP.NET Core)
Spring Boot
[WebApplication.CreateBuilder(args)] …… [app.Run()]
[SpringApplication.run(...)] ([RdvMedecinsApplication.java])
[builder.Services.AddScoped<...>()],每个服务一次调用
[@ComponentScan]:带注解的类 [@Service]、[@Component]、[@Controller]……;注册接口([Spring Data JPA] 的自动配置);[@Bean] 方法,位于 [@Configuration] 类中
[Configure<AuthOptions>(...)] 和 [IOptions<AuthOptions>]
record [@ConfigurationProperties] 和 [@ConfigurationPropertiesScan]
[AddDbContext] 和 [UseMySql]
基于 [Hibernate] 对数据源和 [spring.datasource.*] 的自动配置
[AddControllersWithViews]
[DispatcherServlet] 和 [Thymeleaf] 的自动配置
[AddJwtAuthentication]、[UseAuthentication]、[UseAuthorization]
[config/SecurityConfig.java] (来自 [Spring Security] 的过滤器链)
[UseStaticFiles] (文件夹 [wwwroot])
自动(文件夹 [static])
[UseRequestLocalization] 和 [CookieRequestCultureProvider]
Bean [localeResolver] ([CookieLocaleResolver],[config/WebConfig.java])
[TempData] (Cookie)
Bean [flashMapManager] ([CookieFlashMapManager],[config/WebConfig.java])
[UseExceptionHandler]、[UseStatusCodePagesWithReExecute]
地址 [/error],由 [controllers/ErrorController.java] 处理
[CreateScope()], 然后是 [LoadAsync()], 在 [app.Run()] 之前
方法 [@PostConstruct] ,位于 [web/ApplicationModel.java]
[appsettings.Development.json] 和 [ASPNETCORE_ENVIRONMENT]
[application-dev.properties] 和 [dev] 配置文件
[dotnet watch]
[Spring Boot DevTools]

11.8. 实体

[JPA] 实体把数据库表和 [Java] 类对应起来(参见示例 28)。每个实体类都带有 [@Entity] 注解;它的字段通过来自 [@Column]、[@Id]、[@JoinColumn]…… 等注解(来自 [jakarta.persistence] 包)与列相关联。这些注解是 [JPA] 标准(Jakarta Persistence)中定义的;[Hibernate] 是 [Spring Boot] 所使用的该标准的实现,它在应用程序启动时读取这些注解,以确定哪个类对应哪个表、哪个字段对应哪一列。数据库不是由 [Hibernate] 创建的,而是由 SQL 脚本 [database/dbrdvmedecins2.sql] 创建的(参见“数据库”一节):实体只需准确描述已经存在的表。

应用程序的实体位于 [entities] 文件夹中:

文件
表
作用
[AbstractEntity.java]
-
公共字段 [id] 和 [version] (乐观锁)
[Person.java]
-
医生和客户共有的字段:[title], [lastName], [firstName],以及用户账户
[Doctor.java]
[doctors]
医生
[Client.java]
[clients]
患者
[Slot.java]
[slots]
医生的预约时间段
[Appointment.java]
[appointments]
预约
[User.java]
[users]
用户账户
[Role.java]
-
三种角色的列表

11.8.1. entities/AbstractEntity.java

// =========================================================================
// entities/AbstractEntity.java
// -------------------------------------------------------------------------
// 所有实体共有的两个字段:标识符 [id] 和
// 版本号 [version](乐观锁)。
//
// @MappedSuperclass:该类没有表;其字段会添加
// 到子类(Doctor、Client、Slot、Appointment、User)的表中。
//
// 注解 @Id、@Column、@Version 等来自 JPA 标准(Jakarta
// Persistence,包 jakarta.persistence):Hibernate 在启动时读取它们,
// 以了解哪个类对应哪张表、哪个字段对应哪一列。
// =========================================================================
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 {

    // 主键,由数据库生成(AUTO_INCREMENT 列):Hibernate
    // 在每次 INSERT 之后读回其值。使用 Integer(而不是 int):尚未
    // 保存的实体其 id 为 null。
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Integer id;

    // @Version:乐观锁。Hibernate 发送的每条 UPDATE 都带有
    // 条件 "WHERE id = ... AND version = <读取到的值>",并写入
    // 加 1 后的版本。如果在此期间有人修改了该行,
    // 就不会更新任何行:Hibernate 抛出异常
    // (OptimisticLockException,Spring 将其转换为
    // ObjectOptimisticLockingFailureException,参见 business/BusinessService.java)。
    @Version
    @Column(name = "version")
    private Integer version;

    public Integer getId() {
        return id;
    }

    public Integer getVersion() {
        return version;
    }
}
  • 第 23 行:[@MappedSuperclass] 表示一个没有表的父类:它不对应任何表,但其字段及其注解会被添加到其子类的字段之中。应用程序中的所有实体都继承自它,因此都有标识符和版本。该类同时也是 [abstract]:永远不会创建 [AbstractEntity] 对象;
  • 第 29–32 行:主键([@Id]),列 [id]。[@GeneratedValue(strategy = GenerationType.IDENTITY)] 表示该值由数据库生成(列 [AUTO_INCREMENT]):[Hibernate] 发送不带标识符的 [INSERT] ,然后读回数据库分配的标识符。以后要记住的关键一点:新实体的 [INSERT] 在调用 [save] 时会被立即发送,因为 [Hibernate] 马上就需要标识符。类型是 [Integer],而不是 [int]:[Integer] 可以等于 [null],尚未保存的实体就是这种情况;
  • 第 40–42 行:行版本,用于乐观锁(参见示例 28)。借助 [@Version],[Hibernate] 完成所有工作:它发送的每条 [UPDATE] 都带有条件 [WHERE id = ... AND version = <value read>] ,并写入加 1 之后的版本。如果该行在此期间被其他人修改,就不会更新任何行,[Hibernate] 会抛出异常,[Spring] 将其转换为 [ObjectOptimisticLockingFailureException] (参见“业务层”)。这与 [Entity Framework Core] 不同,在那里应用程序必须在每次保存之前自己递增版本;
  • 第 44–50 行:只读访问器。没有名为 [setId] 或 [setVersion] 的方法:这些值只由 [Hibernate] 写入。由于 [@Id] 注解放在字段 上(而不是放在 [getId] 方法上),[Hibernate] 会直接读写字段——即使是私有字段——而不经过访问器。这被称为字段访问。

11.8.2. entities/Person.java

// =========================================================================
// entities/Person.java
// -------------------------------------------------------------------------
// [Doctor] 和 [Client] 实体的父类(没有表):称谓、
// 姓、名——以及关联的用户账户([user] 列)。
//
// 在 @MappedSuperclass 中声明的关系会被子类
// 像列一样继承:因此 [user] 关系同时存在于
// [doctors] 表和 [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;

    // -----------------------------------------------------------------------
    // 与用户账户的关系:一位医生(一位客户)有一个
    // 账户,一个账户属于一个人员([user] 列具有唯一性)。
    //   - @OneToOne:“一对一”关系;
    //   - fetch = LAZY:只有在被请求时才从数据库读取 User(在
    //     查询中,参见 repositories/ 中的 @EntityGraph,或者在事务期间
    //     访问该字段);
    //   - @JoinColumn:外键所在的列。反引号
    //     (`user`) 让 Hibernate “保护”这个名称,它是
    //     MySQL 的保留字。
    // -----------------------------------------------------------------------
    @OneToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "`user`")
    private User user;

    // 同一列,作为简单数字读取:这样无需加载 User 就能知道
    // 账户的 id。insertable / updatable = false:写入该列的是
    // 上面的 [user] 字段,这个字段只读取它。
    @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; }
}
  • 第 19–20 行:[@MappedSuperclass] 是 [Doctor] 和 [Client] 的父类——它同样没有对应的表——本身又是 [AbstractEntity] 的子类。医生和客户有相同的列:它们只需录入一次;
  • 第 22–29 行:称谓(女士、先生等)、姓和名。[@Column] 的属性 [length] 指定列宽;实际上只有当 [Hibernate] 自己创建表时才会用到它,而这里并非如此(参见“JPA、Hibernate 和 Spring Data”一节):这不是验证规则,而只是对 SQL 脚本的准确记录;
  • 第 42–44 行:与用户账户的关系,表现为类型为 [User] 的字段(对象本身,而不是它的标识符)。[@OneToOne] 定义“一对一”关系:一位医生(或一个客户)有一个账户,而一个账户至多属于一个人(在 SQL 脚本中,列 [user] 为 [UNIQUE])。[@JoinColumn] 指定包含外键的列。[fetch = FetchType.LAZY] 指定懒加载:当 [Hibernate] 读取一个人时,并不读取其账户;而是让 [user] 字段接收一个代理,即一个冒充 [User] 的对象,它只有在第一次调用其某个方法时,并且仅当事务仍处于打开状态时,才会读取 [users] 表中的那一行。要在获取此人的同时获取其账户,查询必须明确提出这一要求(参见“DAO 层”);
  • 第 43 行:[user] 是 [MySQL] 中的保留字:如果在 SQL 查询中原样书写,会导致语法错误。[@JoinColumn] 中环绕该名称的反引号指示 [Hibernate]保护该名称:它会在每条 SQL 命令中用反引号把它括起来,就像 SQL 脚本所做的那样;
  • 第 49–50 行:同一列 [user],这次被读取为一个简单的数字。这使我们无需加载账户本身就能确定账户 ID:业务层用它来删除某个人的账户。一个列只能由一个字段写入:[insertable = false, updatable = false] 表示该字段只读取它,而写入它的是字段 [user] (在 [INSERT] 和 [UPDATE] 中);
  • 第 52–64 行:访问器。如果一个类的私有字段由名为 [getXxx] 的方法读取、由名为 [setXxx] 的方法写入,它就遵循 JavaBean 约定;[Thymeleaf] 视图就基于这一约定([${doctor.lastName}] 调用 [getLastName()])。没有 [setUserId]:[userId] 字段是只读的。

下面是在应用程序控制台中捕获的 SQL 查询,是 [Hibernate] 为获取一位医生及其账户而发送的(参见 DAO 层中的 [findWithUserById] )。在这里我们可以看到带有反引号的 [user] 列,以及与 [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=?

[user] 列位于 [doctors] 表中(也称为 [d1_0]),尽管有两个字段与它对应,它却只被读取一次:[Hibernate] 用它来填充 [userId] 字段,并把 [user] 字段链接到通过连接获取的记录。[?] 是一个查询参数(医生的 ID),它被单独发送给数据库。

11.8.3. entities/Doctor.java

// =========================================================================
// entities/Doctor.java
// -------------------------------------------------------------------------
// 诊所的一位医生(表 [doctors])。
//
// SQL 唯一性约束:unq_doctors_first_name_last_name(两位医生不能
// 有相同的名和姓)——由 SQL 脚本创建,
// 在业务层中通过其名称识别。
// =========================================================================
package rdvmedecins.entities;

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

// @Entity:其对象是表的行的类;
// @Table:该表的名称
@Entity
@Table(name = "doctors")
public class Doctor extends Person {
}
  • 第 17 行:[@Entity] 把该类定义为实体:它的对象就是表中的行;
  • 第 18 行:[@Table] 将此表命名为 [doctors]。如果没有它,[Hibernate] 会查找与类同名的表;
  • 第 19 行:该类从 [Person] 继承了所有字段,并从 [AbstractEntity] 继承了标识符和版本。它没有显式的构造函数:因此 [Java] 编译器会为它提供一个默认构造函数——公有且无参——这正是 [JPA] 所要求的(参见 [Appointment.java]),也是业务层将要使用的([Doctor::new])。注释中提到的唯一性约束 [unq_doctors_first_name_last_name] 由 SQL 脚本创建;业务层通过其名称来识别它。

与 [ASP.NET Core] 版本不同,[Doctor] 没有声明与其时间段之间的反向关系(一个 [@OneToMany] 列表):应用程序不会用到它;它通过 DAO 层读取医生的时间段。

11.8.4. entities/Client.java

// =========================================================================
// entities/Client.java
// -------------------------------------------------------------------------
// 注意:这里的 [Client] 指的是医疗诊所的患者,而不是
// HTTP 客户端!这是原始业务领域的词汇,保持
// 原样(表 [clients])。
//
// SQL 唯一性约束:unq_clients_first_name_last_name(参见 Doctor.java)。
// =========================================================================
package rdvmedecins.entities;

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

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

客户,即诊所的患者(不是 HTTP 客户端):来自 [clients] 表的一个 [Person] (第 15–17 行),没有额外的字段。

11.8.5. entities/Slot.java

// =========================================================================
// entities/Slot.java
// -------------------------------------------------------------------------
// 医生的一个时间段(表 [slots]):8:00 - 8:20,等等。
// =========================================================================
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; // 时间段的开始小时

    @Column(name = "start_minute")
    private int startMinute; // 时间段的开始分钟

    @Column(name = "end_hour")
    private int endHour; // 时间段的结束小时

    @Column(name = "end_minute")
    private int endMinute; // 时间段的结束分钟

    // 同一位医生的多个时间段:@ManyToOne(“多对一”),
    // 外键 [doctor_id]。与 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; }
}
  • 第 19–29 行:时间段的起止小时和分钟,类型为 [int]:这些列在数据库中被声明为 [NOT NULL] ;不可能为 [null] 的基本类型适合用于它们;
  • 第 33–35 行:与医生的“多对一”关系([@ManyToOne]):一位医生有多个时间段,外键在列 [doctor_id] 中;医生被懒加载([LAZY])。与个人账户采用同样的技术;
  • 第 37–38 行:同一个列 [doctor_id],只读,以数字形式表示。针对“2 号医生的预约时间段”的查询会以这个字段为目标,而无需加载医生;
  • 第 40–45 行:只读访问器:应用程序从不创建或修改预约时间段(它们由 SQL 脚本创建)。

默认情况下,[@ManyToOne] 关系会被立即加载([EAGER]):读取一个预约时间段时也会读取它的医生,然后再读取该医生的账户……因此,应用程序中的所有关系都被声明为 [LAZY],每个查询都显式地请求它所需的关系:这样,我们就能确切知道发送了哪些 SQL。

11.8.6. entities/Appointment.java

// =========================================================================
// entities/Appointment.java
// -------------------------------------------------------------------------
// 一个预约(表 [appointments]):某位客户,在某个时间段,在某一天。
//
// SQL 唯一性约束:unq1_appointments(day、slot_id)——一个时间段
// 每天只能被预订一次。由 SQL 脚本创建,在业务层中
// 通过其名称识别。
// =========================================================================
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:不带时间的日期,恰好对应 [day] 列的 SQL 类型
    // DATE
    @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;

    // JPA 需要一个无参数的构造函数(Hibernate 用它来创建
    // 从数据库读取的对象)
    protected Appointment() {
    }

    // 一个新的预约
    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; }
}
  • 第 22 行:预约表。它的唯一性约束 [unq1_appointments (day, slot_id)] 确保一个时间段每天只被预订一次;
  • 第 27–28 行:预约的日期。类型 [LocalDate] (包 [java.time])表示不含时间的日期:它与列 [day] 中的 SQL 类型 [DATE] 完全对应,与时区无关。[Hibernate] 负责双向转换;
  • 第 30–42 行:客户和预约时间段:两个“多对一”关系,每个都由一个对象字段(用于填充列)和一个只读的数字字段([clientId], [slotId])定义;
  • 第 46–47 行:[JPA] 要求每个实体都有一个无参构造函数:[Hibernate] 使用这个构造函数来创建它从数据库中读取的对象,然后再填充它们的字段。一旦类声明了构造函数(第 50–54 行),编译器就不再为它提供默认构造函数:因此必须显式编写它。它被声明为 [protected]:[Hibernate] 可以使用它,而应用程序的其余部分看不到它,只能使用完整的构造函数。[JPA] 接受 [public] 或 [protected] 的构造函数,但不接受 [private] 的:[Hibernate] 通过定义实体的子类来创建其代理,而子类必须能够调用其父类的构造函数(这也是实体类不得声明为 [final] 的原因);
  • 第 50–54 行:新预约的构造函数:一个日期、一个时间段、一个客户。它填充对象字段 [slot] 和 [client],这些字段设置外键;只读字段 [clientId] 和 [slotId] 只有在从数据库读取预约时才会被填充;
  • 第 56–60 行:只读访问器:预约永远不会被修改,只会被创建或删除。

11.8.7. entities/Role.java

// =========================================================================
// entities/Role.java
// -------------------------------------------------------------------------
// 用户的三种角色(users.role 列):
//   - ADMIN  :管理员——预约 + 医生和客户的管理;
//   - DOCTOR :医生——预订和取消预约;
//   - USER   :客户(患者)——为自己预订,管理自己的账户。
//
// 枚举(enum):编译器拒绝任何其他值。JPA
// 将其作为文本('ADMIN' 等)存入数据库,SQL 脚本也是这样做的
// (参见 User.java 中的 @Enumerated)。
// =========================================================================
package rdvmedecins.entities;

public enum Role {
    ADMIN,
    DOCTOR,
    USER
}
  • 第 15–19 行:三个角色,以枚举 ([enum])的形式表示:类型为 [Role] 的变量只能取值 [Role.ADMIN]、[Role.DOCTOR]、[Role.USER] (或 [null]),编译器会拒绝任何其他值。[Role] 不是实体:它是 [User] 某个字段的类型。每个值都有一个名称([name()] 返回 ["ADMIN"])和一个序号([ordinal()] 对 [ADMIN] 返回 0):对于数据库而言,在这两者之间做出选择的是 [@Enumerated],它位于 [User.java] 中。

11.8.8. entities/User.java

// =========================================================================
// entities/User.java
// -------------------------------------------------------------------------
// 允许登录应用的用户(表 [users])。
// 每位医生和每位客户都有各自的用户账户([doctors] 和 [clients]
// 表的 [user] 列,参见 Person.java)。
//
// SQL 唯一性约束:unq_users_login(一个登录名只属于一个
// 账户)。它由 database/dbrdvmedecins2.sql 脚本创建;
// 业务层通过其名称识别它(参见 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;

    // 哈希后的密码(bcrypt)——绝不保存明文
    @Column(name = "password", length = 100)
    private String password;

    // 登录后显示的名称——对医生或客户而言为:
    // "firstName LASTNAME"(例如 "Marie PELISSIER")
    @Column(name = "name", length = 40)
    private String name;

    // ADMIN、DOCTOR 或 USER,以文本(STRING)形式存入数据库,而不是
    // 序号(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; }
}
  • 第 20–22 行:被授权登录的用户的账户:管理员、每位医生和每个客户。约束 [unq_users_login] 禁止两个账户使用相同的登录名;
  • 第 24–25 行:用户名;
  • 第 28–29 行:密码的哈希值 [bcrypt] ,绝不是密码本身(参见示例 25);
  • 第 33–34 行:登录后显示在导航栏中的名称(“Marie PELISSIER”);
  • 第 38–40 行:角色。默认情况下,[JPA] 会按序号在数据库中存储枚举([EnumType.ORDINAL]:0、1、2),这有两个缺点:SQL 脚本中的 [role] 列包含的是文本,而且日后如果在枚举中间添加一个值,就会改变已记录的序号的顺序。[@Enumerated(EnumType.STRING)] 存储值的名称 (['ADMIN']……),并在读取时把它转换回 [Role] ;
  • 第 42–52 行:getter 方法。[User] 类没有声明与拥有它的医生或客户之间的关系:这种关系只在 [Person] 一侧可知,由它携带外键。

11.9. JPA、Hibernate 和 Spring Data

应用程序的 [ASP.NET Core] 版本包含一个名为 [DbContext] 的类,它是 [Entity Framework Core] 的核心组件:它维护连接、提供对表的访问、跟踪已加载的实体,并把更改发送到数据库。[Spring] 版本没有手写的对应物:这些职责被分配给由 [Spring Boot] 在启动时根据配置自行创建的对象。本节说明谁负责什么;它并不对应项目中的任何 [Java] 文件。

11.9.1. 三个层次

数据访问基于三个层次,它们由 [spring-boot-starter-data-jpa] 启动器一并提供(参见“项目配置”一节):

  • [JPA] (Jakarta Persistence)是一个标准:一组接口和注解([@Entity]、[EntityManager]……),本身没有让它们工作的代码;
  • [Hibernate] 是该标准的实现 :它读取实体注解,编写 SQL 命令,通过 JDBC([mysql-connector-j])把它们发送到数据库,并把得到的行转换为 [Java] 对象;
  • [Spring Data JPA] 在此基础上增加了仓库:你只需通过一个接口来描述 DAO,[Spring] 就会编写其实现(参见“DAO 层”)。

11.9.2. EntityManager 与持久化上下文

[JPA] 的核心对象是 [EntityManager] (“实体管理器”):它负责读取([find])、保存([persist])和删除([remove])实体,以及执行查询。它管理一个持久化上下文:即它读取或保存过的实体的集合,这些实体称为“受管”实体。对于每个受管实体,它都会保留一份从数据库读取时状态的副本。在与数据库同步 的时刻(即 *flush*),最迟发生在事务的 [COMMIT] 之前,它会把每个实体与其副本进行比较,并为每个发生了变化的实体自行发送一条 [UPDATE](*脏检查*)。因此,没有需要调用的“保存更改”方法:只需修改受管实体即可。持久化上下文还确保一行数据只由一个对象表示:在同一个事务中两次读取 1 号医生,会两次返回同一个 [Java] 对象。

这正是 [DbContext] 在 [Entity Framework Core] 中的“变更跟踪”,但有一个重要区别:在 [Spring] 中,持久化上下文与事务绑定。它在事务开始时创建,在事务结束时([COMMIT] 或 [ROLLBACK])关闭。它所管理的实体随后就变成游离状态:它们成为不再被任何人跟踪的普通 [Java] 对象。修改它们不再对数据库产生任何影响,而且它们尚未加载的 [LAZY] 关系也不能再被加载。

应用程序从不直接操作 [EntityManager]:这项工作由 [Spring Data JPA] 仓库代劳。当在事务进行期间(由业务层开启)调用某个仓库方法时,它使用该事务的 [EntityManager]:因此,事务期间调用的所有仓库共享同一个持久化上下文、同一个连接和同一个事务。当没有事务正在进行时,从 [JpaRepository] 继承的方法([findById]、[save]……)会在调用期间开启一个短暂的事务(读操作为只读事务);我们接口中声明的查询([findAllByOrderByLastNameAscFirstNameAsc]、[@Query] 方法等)则在没有事务的情况下执行:[Spring] 在调用期间创建一个 [EntityManager] ,然后关闭它。在这两种情况下,返回的实体都会立即变为游离状态。

11.9.3. 配置

[Hibernate] 所需的一切都由 [Spring Boot] 生成(这就是 自动配置),依据是文件 [application.properties] 中的键 [spring.datasource.*] 和 [spring.jpa.*] (参见“项目配置”一节):

1
2
3
4
5
6
7
8
# —— MySQL 数据库 [dbrdvmedecins2](脚本:database/dbrdvmedecins2.sql)
spring.datasource.url=jdbc:mysql://localhost:3306/dbrdvmedecins2
spring.datasource.username=root
spring.datasource.password=
# Hibernate 既不创建也不修改表:这是 SQL 脚本的职责
spring.jpa.hibernate.ddl-auto=none
# 在构建视图期间,不保持与数据库的连接处于打开状态
spring.jpa.open-in-view=false
  • 第 2–4 行:键 [spring.datasource.*] 描述连接:数据库的 URL (即 JDBC URL,包括 [jdbc:mysql:] 协议、机器、端口和数据库名称)、用户名和密码。[Spring Boot] 实际上会创建一个 [DataSource],即连接池。打开到数据库的连接是消耗资源的:这个 [DataSource] 是一个连接池 (使用 [HikariCP] 库),它保持几个连接处于打开状态,并轮流借出;
  • 第 6 行:[ddl-auto=none]:[Hibernate] 既不创建也不修改表(它可以使用值 [create] 根据实体创建表,或使用 [update] 来更新它们):数据库只由 SQL 脚本来描述,别无其他;
  • 第 8 行:[open-in-view=false] 使 [EntityManager] 在事务结束时就关闭,而不是一直保持打开到 HTTP 请求结束(见下文)。

基于 [DataSource] 和实体,[Spring Boot] 还会创建 [EntityManagerFactory] (它创建 [EntityManager])、一个事务管理器([JpaTransactionManager]),以及一个 [TransactionTemplate],业务层用它来开启事务。SQL 方言 ([MySQL] 的特有功能:[limit]、反引号等)会根据所连接的数据库自动推导出来。

当 [application-dev.properties] 文件所在的 [dev] 配置文件处于激活状态时(使用 [./mvnw spring-boot:run] 时就是如此),也会读取该文件,它添加了 [spring.jpa.show-sql=true] 键:[Hibernate] 随后会在控制台中显示它发送的每条 SQL 命令。本章中展示的所有请求都是以这种方式捕获的。

与 [DbContext] 在 [ASP.NET Core] 版本中的情况相比,缺少了两项内容,因为它们不再需要:表的列表(实体会被自动找到,因为它们位于应用程序包或其子包中),以及来自 [OnModelCreating] 的细节(“一对一”关系由 [@OneToOne] 指定,角色到文本的转换由 [@Enumerated] 完成,版本递增由 [@Version] 完成)。

11.9.4. open-in-view=false:显式加载关系

默认情况下([spring.jpa.open-in-view=true]),[Spring Boot] 会在每个 HTTP 请求开始时打开一个 [EntityManager] ,并且只在视图生成之后才关闭它:视图因此可以读取尚未加载的 [LAZY] 关系([${appointment.client.lastName}]),而 [Hibernate] 会在显示时发送所需的查询。这很方便,但这样一来,SQL 请求可以从任何地方发出,包括从 [Thymeleaf] 视图中发出,连接在整个页面渲染过程中一直被占用,而且一个包含 20 个事件的循环可能触发 20 个小请求而不是一个(即所谓的“N+1”问题)。当没有指定该键时,[Spring Boot] 还会在启动时显示一条警告。

应用程序选择 [open-in-view=false]:[EntityManager] 在每个事务结束时(或在事务之外对仓库的每次调用结束时)关闭,离开业务层的实体都是游离的。其结果是一条必须处处遵守的规则:每次读取都要显式加载页面所需的关系,使用 [@EntityGraph] 或 [join fetch] (参见“DAO 层”)。读取一个尚未加载的 [LAZY] 关系——例如,由一个没有请求账户的查询读出的医生的账户——会触发 [LazyInitializationException]:再也无法读取任何内容;[EntityManager] 已经关闭。另一方面,我们确切地知道发送了哪些请求以及何时发送:它们全都在 DAO 层中。

11.10. 领域:日历

[domain] 文件夹包含两个不对应任何表的类:它们描述医生一天的日程,由业务层计算([BusinessService.getDoctorDaySchedule]),并由日程控制器显示。

11.10.1. domain/DoctorDaySlot.java

// =========================================================================
// domain/DoctorDaySlot.java
// -------------------------------------------------------------------------
// 一个“业务”对象(没有表),它将一个时间段与该时间段在某一天
// 可能被预订的预约关联起来。
//
// Java record 是其字段由构造函数一次性
// 设定的类(不可变对象):这正是计算得出、
// 之后无人修改的对象所需要的。
// =========================================================================
package rdvmedecins.domain;

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

// appointment:如果该时间段当天空闲则为 null
public record DoctorDaySlot(Slot slot, Appointment appointment) {
}
  • 第 17 行:一个时间段,以及该日在该时间段安排的预约,如果该时间段空闲则为 [null] 。record (从 [Java] 16 开始)用一行声明一个类,其字段由构造函数一次性设定:编译器自己编写私有字段和 [final] (不可修改)、含两个参数的构造函数、访问器 [slot()] 和 [appointment()] (没有前缀 [get]),以及方法 [equals]、[hashCode] 和 [toString]。record 的主体,用花括号括起来,在这里是空的。我们已经见过用于向业务层传输数据的 record(参见示例 28)。

11.10.2. domain/DoctorDaySchedule.java

// =========================================================================
// domain/DoctorDaySchedule.java
// -------------------------------------------------------------------------
// 医生某一天的完整日程:其时间段的列表,
// 每个时间段要么空闲,要么被某个预约占用。由
// BusinessService.getDoctorDaySchedule 计算,由
// ScheduleController 转换为 HTML 表格。
// =========================================================================
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) {
}

日程(第 16 行):一位医生、一天,以及按时间顺序排列的该医生的时间段列表——可预约的或已被预订的。[Thymeleaf] 视图可以读取 record 的访问器:[${schedule.day}] 调用 [day()]。

11.11. DAO 层

每个表一个 DAO,与示例 28 中一样:这些方法不含业务逻辑,只是简单地查询或修改数据库。这里把它们称为仓库。在 [Spring Data JPA] 中,仓库就是一个简单的接口:应用程序启动时,[Spring] 会生成一个实现它的类,把它变成 Bean,并在需要的地方注入。该接口继承自 [JpaRepository<T, ID>] ([T]:实体类型;[ID]:其主键的类型),它提供标准方法:[findById]、[findAll]、[save]、[deleteById]、[getReferenceById]……应用程序特有的查询可以通过三种方式添加:

  • 按方法名:[Spring Data JPA] 分析方法名([find] …… [By] *条件* [OrderBy] *排序*),并据此推导出查询。字段名中的错误会在启动时被检测到,导致进程失败;
  • 用 JPQL,使用注解 [@Query]。[JPQL] (Jakarta Persistence Query Language)是 [JPA] 的查询语言:它类似于 SQL,但引用的是实体及其字段 ([Appointment], [a.client]),而不是表及其列。[Hibernate] 会把它翻译成 SQL;
  • 用 SQL,使用 [@Query(nativeQuery = true)],当 [JPQL] 不够用时。

可能不返回任何内容的方法返回 [Optional<T>] (包 [java.util]):一个要么包含对象、要么为空的盒子。调用者必须先检查结果是否存在,才能使用它([isPresent()]、[orElseThrow(...)]……):不会再有被遗忘的 [null]。

与实体一样,仓库不管理事务:事务由业务层开启。

11.11.1. repositories/PersonRepository.java

医生和客户的仓库是完全相同的:因此只需用一个泛型接口把它们写一次。

// =========================================================================
// repositories/PersonRepository.java
// -------------------------------------------------------------------------
// 医生和客户共用的 DAO 层。
//
// 使用 Spring Data JPA 时,DAO 只是一个接口:Spring 在启动时
// 自行编写其实现。JpaRepository<T, Integer> 已经
// 提供了 findById、findAll、save、delete 等;我们再向其中添加自己的查询:
//   - 要么通过方法的名称,Spring Data 会将其转换为查询
//     (findFirstByFirstNameAndLastName -> ... WHERE first_name = ? AND last_name = ? LIMIT 1);
//   - 要么通过写在 @Query 注解中的 JPQL 查询。JPQL
//     类似 SQL,但处理的是类及其字段,而不是
//     表及其列。
//
// 医生和客户的 DAO 本来是相同的:这个
// 泛型接口只需写一次,T 为 Doctor 或 Client。
// @NoRepositoryBean:Spring 不会为这个接口本身创建 DAO,
// 只为它的子接口 DoctorRepository 和
// ClientRepository 创建。在查询中,#{#entityName} 指代
// 子接口的实体(Doctor 或 Client)。
//
// 事务:同一个 HTTP 请求的所有 DAO 方法
// 都使用当前事务(如果有的话)(参见 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> {

    // 按姓再按名排序的列表,包含用户账户。
    // @EntityGraph(attributePaths = "user"):通过连接
    // 同时取回账户(SELECT ... FROM doctors LEFT JOIN users ...)。没有它,
    // 账户只会在首次访问时才读取——在事务之外这是不可能的:
    // 这些列表由缓存保存在内存中
    // (web/ApplicationModel.java),远在请求结束之后。
    @EntityGraph(attributePaths = "user")
    List<T> findAllByOrderByLastNameAscFirstNameAsc();

    // 一个人员及其账户
    @EntityGraph(attributePaths = "user")
    Optional<T> findWithUserById(int id);

    // 用户账户为 [userId] 的人员
    @EntityGraph(attributePaths = "user")
    Optional<T> findByUserId(int userId);

    // 具有这个名和姓的人员(如果存在)。比较
    // 由 MySQL 完成,因此采用数据库的排序规则
    // (utf8mb4_unicode_ci:忽略大小写和重音)——
    // 与 SQL 唯一性约束的规则完全相同。
    Optional<T> findFirstByFirstNameAndLastName(String firstName, String lastName);

    // 直接发送到数据库的 DELETE,无需先读取该人员。
    // @Modifying:该查询修改数据(它不是 SELECT)
    @Modifying
    @Query("delete from #{#entityName} p where p.id = :id")
    void remove(int id);
}

我们来说明这段代码:

  • 第 39 行:[PersonRepository<T extends Person>] 是一个泛型接口:[T] 是一个类型参数,在子接口中被替换为实际类型([Doctor] 或 [Client]),例如 [T] 在 [List<T>] 中。[extends Person] 只接受 [Person] 或其子类作为 [T]:因此在查询中,[T] 必然包含字段 [lastName], [firstName], [user], [userId]……该接口继承自 [JpaRepository<T, Integer>]:实体 [T],主键类型为 [Integer];
  • 第 38 行:[@NoRepositoryBean] 指示 [Spring Data JPA]不要为这个接口本身创建仓库(它不指向任何具体实体,[T] 是未知的),而只为它的子接口 [DoctorRepository] 和 [ClientRepository] 创建;
  • 第 47–48 行:所有人员,按姓再按名排序。方法名就是查询:[findAll] (单词 [All] 仅为提高可读性而加入)、[By] 不带条件(所有行)、[OrderByLastNameAscFirstNameAsc] (先按姓升序,再按名升序排序)。[@EntityGraph(attributePaths = "user")] 要求通过连接在同一个查询中[user] 关系也被加载;没有它,每个人的 [user] 字段就会是一个未加载的代理。这在这里至关重要:这些列表由缓存([web/ApplicationModel.java])保存在内存中,在事务结束很久之后仍然存在,并且视图会显示每个人的登录名;
  • 第 51–52 行:一个人及其账户,或者一个空的 [Optional]。[JpaRepository] 已经提供了 [findById],但不含账户;如果不修改它的所有用法,就无法给它添加 [@EntityGraph]。因此,我们声明另一个方法:在方法名中,[Spring Data JPA] 会忽略 [find] 和 [By] 之间的文本(这里是 [WithUser]),它仅用来告诉读者该方法返回什么。查询与 [findById] ([where id = ?])相同,而 [@EntityGraph] 为它添加了连接;
  • 第 55–56 行:账户为 [userId] 的人:条件作用于字段 [userId] (只读),因此直接作用于列 [user]。已登录的患者的令牌中包含账户 ID,就是这样获取其客户记录的;
  • 第 62 行:可能存在的同名者。[First] 把结果限制为单行(SQL 中的 [limit ?] ),[ByFirstNameAndLastName] 同时满足两个条件,用 [and] 连接。方法的参数按顺序与条件相对应。比较由 [MySQL] 按照数据库的排序规则执行,不区分大小写和重音,与唯一性约束完全一样;
  • 第 66–68 行:通过 [JPQL] [delete] 查询删除一个人,直接发送到数据库,而无需先读取这个人(相当于 [Entity Framework Core] 中的 [ExecuteDeleteAsync])。[@Modifying] 表示该请求会修改数据:没有它,[Spring Data JPA] 会把它当作 [select]。这样的查询必须在允许写入的事务中运行:该事务由业务层开启。它不经过持久化上下文,因此也不经过乐观锁;
  • 第 67 行:该接口是泛型的,但 [JPQL] 查询必须指定某个具体实体:[delete from Doctor] 或 [delete from Client]。[#{...}] 引入一个 SpEL 表达式(Spring Expression Language,[Spring] 的表达式语言),它在启动时求值;变量 [#entityName] 表示具体仓库中实体的名称。对于 [DoctorRepository],查询变为 [delete from Doctor p where p.id = :id];
  • 第 67–68 行:[:id] 是请求的一个命名参数 ,与方法的参数 [id] (按名称)相关联。它的值与查询文本分开发送到数据库:没有字符串拼接,因此不可能发生 SQL 注入。

下面是 [Hibernate] 针对客户列表(第 48 行)和在医生中查找同名者(第 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 ?

第一个请求在一次查询中获取客户及其账户([left join users]);第二个请求没有 [@EntityGraph],只获取 [doctors] 表。

11.11.2. repositories/DoctorRepository.java

// =========================================================================
// repositories/DoctorRepository.java
// -------------------------------------------------------------------------
// 医生的 DAO:一切都继承自 PersonRepository。
// Spring Data 在启动时构建其实现。
// =========================================================================
package rdvmedecins.repositories;

import rdvmedecins.entities.Doctor;

public interface DoctorRepository extends PersonRepository<Doctor> {
}

医生的仓库(第 11 行):[PersonRepository<Doctor>],别无其他。[Spring Data JPA] 实现的正是这个接口——而不是带 [@NoRepositoryBean] 的那个:其中所有继承的方法都与 [Doctor] 实体相关。

11.11.3. repositories/ClientRepository.java

// =========================================================================
// repositories/ClientRepository.java
// -------------------------------------------------------------------------
// 客户的 DAO:人员的 DAO,外加一个加锁方法。
// =========================================================================
package rdvmedecins.repositories;

import java.util.Optional;

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

import rdvmedecins.entities.Client;

public interface ClientRepository extends PersonRepository<Client> {

    // -----------------------------------------------------------------------
    // 对某位客户的行加锁,直到当前事务结束
    // (SELECT ... FOR UPDATE),并返回其 id
    // (如果该客户不存在,则返回空的 Optional)。请求同一把锁的
    // 第二个事务会等待,直到第一个事务结束。
    // 用于预订预约(参见 BusinessService.addAppointment):
    // 针对同一位患者的两次同时预订因此会
    // 一个接一个地处理,第二个事务能看到第一个创建的预约。
    //
    // nativeQuery = true:该查询是 SQL,原样发送给数据库,
    // 而不是由 Hibernate 转换的 JPQL。JPA 也可以施加这把锁
    // (在 JPQL 查询上使用 @Lock(LockModeType.PESSIMISTIC_WRITE)),但
    // 那样 Hibernate 会写出 "FOR UPDATE OF c1_0",这是 MySQL 8 的语法,
    // MariaDB(某些发行版中的“MySQL”)不接受。这条 SQL
    // 在两者上都能工作。
    // :id 是查询的参数(不做字符串拼接,
    // 因此不可能发生 SQL 注入)。
    // -----------------------------------------------------------------------
    @Query(value = "select id from clients where id = :id for update", nativeQuery = true)
    Optional<Integer> lock(int id);
}
  • 第 14 行:客户的仓库——针对个人的仓库,其中 [T = Client],外加一个方法;
  • 第 34–35 行:带锁读取客户。[SELECT ... FOR UPDATE] 会在该行上加锁,直到当前事务结束:请求同一把锁的另一个事务会等待,直到第一个事务完成。预约功能([BusinessService.addAppointment])利用这一点,把同一位患者的两个同时发生的预订依次处理:第二个预订会看到第一个预订所创建的预约,从而遵守“只能有一个即将到来的预约”的规则。该方法只返回客户 ID([select id]),如果客户不存在则返回空的 [Optional] :它仅用于获取锁并验证客户是否存在;
  • 第 34 行:[nativeQuery = true]:该查询是 SQL,原样发送到数据库,而不是 [JPQL]。不过,[JPA] 可以自行设置这把锁:注解 [@Lock(LockModeType.PESSIMISTIC_WRITE)],添加到 [JPQL] 请求上,会指示 [Hibernate] 向其添加加锁子句。但是对于 [MySQL] 8,[Hibernate] 随后会写出 [for update of c1_0] (该锁只作用于指定的表),这是 [MySQL] 8 特有的语法,[MariaDB]——常被安装来代替 [MySQL]——会拒绝它。手工编写的 SQL,即不带 [for update] 的 [of],则对两者都适用。[:id] 同样是一个查询参数。

预订期间控制台中显示的该查询如下:

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

11.11.4. repositories/SlotRepository.java

// =========================================================================
// repositories/SlotRepository.java
// -------------------------------------------------------------------------
// [Slot] 实体的 DAO 层。
// =========================================================================
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> {

    // 一个时间段及其医生
    @EntityGraph(attributePaths = "doctor")
    Optional<Slot> findWithDoctorById(int id);

    // 某位医生的时间段,按时间顺序排列
    List<Slot> findByDoctorIdOrderByStartHourAscStartMinuteAsc(int doctorId);

    // 删除某位医生的所有时间段(删除医生时):
    //   DELETE FROM slots WHERE doctor_id = ?
    @Modifying
    @Query("delete from Slot s where s.doctorId = :doctorId")
    void deleteByDoctor(int doctorId);
}
  • 第 18 行:一个常规仓库:实体 [Slot],主键 [Integer];
  • 第 21–22 行:一个预约时间段及其医生([@EntityGraph(attributePaths = "doctor")]),仿照 [findWithUserById];
  • 第 25 行:某位医生的时间段,按时间顺序排列:[ByDoctorId] 按字段 [doctorId](即列 [doctor_id])过滤,[OrderByStartHourAscStartMinuteAsc] 按小时再按起始分钟排序。[Hibernate] 发送 [select ... from slots s1_0 where s1_0.doctor_id=? order by s1_0.start_hour,s1_0.start_minute];
  • 第 29–31 行:用单条 [DELETE] 删除某位医生的时间段。业务层在删除医生之前调用这个方法;否则,外键 [slots.doctor_id] 会阻止删除。该方法没有命名为 [deleteByDoctorId]:这样的名称同样会被 [Spring Data JPA] 解释,但推导出的查询会先读取这些时间段,然后逐个删除;而 [@Query] 查询只发送一条命令,即 [DELETE]。

11.11.5. repositories/AppointmentRepository.java

// =========================================================================
// repositories/AppointmentRepository.java
// -------------------------------------------------------------------------
// [Appointment] 实体的 DAO 层。
//
// JPQL 查询通过关系字段从一个实体导航到另一个实体
// (a.slot.doctorId):Hibernate 自行写出必要的
// SQL 连接。"join fetch" 同样会取回被连接的实体
// (相当于 @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> {

    // 一个预约、其客户及其时间段
    @Query("select a from Appointment a join fetch a.client join fetch a.slot where a.id = :id")
    Optional<Appointment> read(int id);

    // 某位医生在某一天的预约,包含客户和时间段。
    // [appointments] 表不直接引用医生:我们通过时间段来关联。
    @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);

    // 某位客户从 [fromDay] 这一天起(含)的预约,按
    // 时间顺序排列,包含时间段及该时间段所属的医生
    @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);

    // 某位客户从 [fromDay] 这一天起(含)的预约数量
    long countByClientIdAndDayGreaterThanEqual(int clientId, LocalDate fromDay);

    // 某位医生的预约数量(过去的或未来的)
    @Query("select count(a) from Appointment a where a.slot.doctorId = :doctorId")
    long countByDoctor(int doctorId);

    // 删除一个预约:DELETE FROM appointments WHERE id = ?
    @Modifying
    @Query("delete from Appointment a where a.id = :id")
    void remove(int id);

    // 删除某位客户的所有预约(过去的和未来的)
    @Modifying
    @Query("delete from Appointment a where a.clientId = :clientId")
    void deleteByClient(int clientId);
}

我们来说明这段代码:

  • 第 26–27 行:一个预约及其客户和时间段。在 [JPQL] 中,[join fetch a.client] 执行连接并把被连接的实体加载到结果中:这相当于把 [@EntityGraph] 写在查询里。连接是通过沿着关系字段([a.client])进行的:[Hibernate] 知道外键([@JoinColumn]),并自行写出条件 [on]。使用 [@Query] 时,方法名是任意的:执行的就是所写的查询。名称 [findById] 已被从 [JpaRepository] 继承的方法占用,该方法既不加载客户,也不加载时间段;
  • 第 31–34 行:某位医生在指定日期的预约,每个预约都带有各自的客户和时间段。该查询写在 [Java] 文本块中(自 [Java] 15 起):由三个引号界定的字符串 ["""],可以跨越多行。表 [appointments] 并不直接引用医生:我们通过时间段,连接为它指定别名 [s],然后在 [s.doctorId] 上过滤。[a.day = :day] 比较两个日期:[Hibernate] 把 [LocalDate] 作为 SQL [DATE] 值传递;
  • 第 38–42 行:某位患者从 [fromDay] 当天起的预约,连同其时间段以及分配给该时间段的医生:[join fetch s.doctor] 沿着关系从时间段到它的医生(两个级联的连接)。排序依据是日期,然后是时间段的时间。这就是“我的账户”所显示的内容。所分配的医生没有加载其自己的记录([user]):该页面不需要它;
  • 第 45 行:某位客户从 [fromDay] 当天起的预约数量,用于“只能有一个即将到来的预约”的规则:[count] 生成 [select count(...)],[GreaterThanEqual] 生成比较 [>=]。结果的类型为 [long];
  • 第 48–49 行:某位医生拥有的预约数量,用于阻止删除有预约的医生。[a.slot.doctorId] 沿着关系 [slot] 而不使用 [join fetch]:[Hibernate] 添加与 [slots] 的连接 用于过滤,而不加载任何内容;
  • 第 52–54 行:通过直接的 [DELETE] 调用取消预约。[JpaRepository] 确实提供了 [deleteById],但该方法会先读取预约,然后再删除它;
  • 第 57–59 行:删除某位客户的所有预约,无论过去的还是将来的:业务层在删除客户之前调用它,否则外键 [appointments.client_id] 会阻止删除。

下面是第 42 行的查询,经 [Hibernate] 翻译为 SQL 之后的样子:两个 [join fetch] 变成了两个连接,时间段和医生的列与预约的列同时被读取:

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

请注意,[join fetch] 生成的是内连接([join]),而 [@EntityGraph] 在 [PersonRepository] 中生成的是外连接([left join]):在这里,每个预约都必须有时间段,每个时间段也都必须有医生。

11.11.6. repositories/UserRepository.java

// =========================================================================
// repositories/UserRepository.java
// -------------------------------------------------------------------------
// [User] 实体的 DAO 层。创建(或删除)医生或
// 客户的同时也会创建(或删除)其账户——参见 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()
    Optional<User> findByLogin(String login);

    @Modifying
    @Query("delete from User u where u.id = :id")
    void remove(int id);
}
  • 第 20 行:与该登录名关联的账户,或者一个空的 [Optional]。它用于登录([AuthService]),以及在分配登录名之前验证该登录名是否可用;
  • 第 22–24 行:通过直接的 [DELETE] 调用删除账户。顺序与创建过程相反:业务层先删除引用该账户的人,然后再删除账户。

账户的创建和修改使用从 [save] 继承自 [JpaRepository] 的方法:对于新实体(ID 为 [null]),它调用 [persist] ,来自 [EntityManager] (即一条 [INSERT]);对于已经登记过的实体,它调用 [merge]。我们将会看到,业务层实际上只在创建时才需要 [save] 。

11.12. 业务层

业务层包含应用程序的业务规则:不能预约过去的时间、每位患者只能有一个即将到来的预约、登录名和个人信息唯一,以及可以删除医生或客户。它依赖 DAO 层([repositories] 文件夹)来进行读写,负责开启事务,并且对 HTML 或界面语言一无所知。更确切地说,它就是示例 28 中的 [PersonsBusiness] 层。

11.12.1. business/Dates.java

// =========================================================================
// business/Dates.java
// -------------------------------------------------------------------------
// 今天的日期。它被业务规则使用(不能在过去
// 预订,每位患者只能有一个即将到来的预约):因此它位于
// 业务层。Web 层会重用它。
// =========================================================================
package rdvmedecins.business;

import java.time.LocalDate;

public final class Dates {

    private Dates() {
    }

    // 今天的日期,使用服务器的时区
    public static LocalDate today() {
        return LocalDate.now();
    }
}
  • 第 12 行:一个工具类,只包含一个名为 [static] 的方法,通过类名来调用([Dates.today()])。[final] 阻止继承它;
  • 第 14–15 行:[private] 构造函数阻止创建 [Dates] 对象,因为那毫无意义;
  • 第 18–20 行:今天的日期,按服务器的时区,以 [LocalDate] (不含时间的日期,即 [Appointment.day] 的类型)的形式给出。两个 [LocalDate] 对象使用以下方法进行比较:[day.isBefore(today)]、[isAfter]、[equals]。当前日期用于业务规则,因此它位于业务层;Web 层会复用它(例如,在 [ScheduleController] 中,用来判断某一天是否仍可预约)。

11.12.2. business/BusinessException.java

// =========================================================================
// business/BusinessException.java
// -------------------------------------------------------------------------
// 当业务规则被违反时
// (登录名已被占用、仍有预约的医生、时间段已被预订等),业务层抛出的异常。
// 它不携带文本,而是携带翻译
// 键(例如 "ERRORS.LOGIN_TAKEN"):由 Web 层在显示页面时
// 将其翻译成法语或英语
// (参见 i18n/fr.json、i18n/en.json)。
//
// BusinessException 并不是异常状况:它是一种正常的回答
// (“该登录名已被占用”),会显示给用户。任何其他
// 异常才是真正的异常状况,会导致 500 错误页面。
//
// RuntimeException:“非受检”异常;抛出它的方法
// 不必声明它(throws),并且 Spring 会撤销(ROLLBACK)被它中断的
// 事务。
// =========================================================================
package rdvmedecins.business;

import java.util.Map;

public class BusinessException extends RuntimeException {

    // 消息的翻译键
    private final String key;

    // 消息的可能参数({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;
    }
}
  • 第 23 行:当业务规则拒绝某个操作时抛出的异常(参见示例 28)。它继承自 [RuntimeException]:它是一个非受检异常。在 [Java] 中,可能抛出受检异常的方法必须声明它([throws ...]),并且调用者必须处理它;非受检异常则不受这一要求约束。另一个重要的后果是:[Spring] 会回滚([ROLLBACK])被非受检异常中断的事务(而对于 [@Transactional],受检异常默认情况下会让事务提交);
  • 第 26 和 29 行:消息的翻译键 ([ERRORS.LOGIN_TAKEN])以及任何关联的参数。与示例 28 的区别:该异常携带的不是法语文本,而是一个键。因此业务层不了解界面语言:由 Web 层使用字典 [i18n/fr.json] 和 [i18n/en.json] 来翻译这个键(参见“字典”一节)。这些字段是 [final]:由构造函数设置,之后不再改变;
  • 第 31–33 行:不带消息参数的构造函数。[this(key, Map.of())] 用一个空字典调用该类的另一个构造函数:[Map.of()] 创建一个只读字典。因此 Web 层永远不必测试 [null]。[BusinessService] 抛出的异常实际上只使用这个构造函数;
  • 第 36 行:[super(key)] 把键传递给父类的构造函数,父类用它作为异常消息([getMessage()]),这在错误日志中很有用;
  • 第 41–47 行:访问器。

[BusinessException] 不是错误:它是一种正常的响应(“此登录名已被占用”),控制器会拦截它,并将其显示给用户,要么显示在页面上,要么显示在弹出消息中。任何其他异常都是真正的错误,会导致显示 500 错误页面。

11.12.3. business/Business.java

// =========================================================================
// business/Business.java
// -------------------------------------------------------------------------
// 业务层的契约:读取、日程、预约、医生和客户
// 的管理。
//
// Optional<T>:可能不存在的结果(不存在的医生
// 等)。调用者被迫处理这种情况:不会遗漏 null。
// =========================================================================
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 {

    // —————————————————————————— 读取
    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);

    // 用户账户为 [userId] 的客户(患者)
    Optional<Client> getClientByUserId(int userId);

    // 某位客户今天或将来的预约,包含时间段和医生
    List<Appointment> getClientUpcomingAppointments(int clientId);

    // —————————————————————————— 预约(ADMIN、DOCTOR、USER)
    // 在以下情况下抛出 BusinessException:
    //  - 日期已过去("ERRORS.PAST_DATE");
    //  - 患者已有一个即将到来的预约("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    //  - 该时间段当天已被预订("ERRORS.SLOT_ALREADY_BOOKED")。
    Appointment addAppointment(LocalDate day, Slot slot, Client client);

    void deleteAppointment(Appointment appointment);

    // —————————————————————————— 医生(ADMIN)
    // 创建医生及其用户账户(角色 DOCTOR)
    Doctor addDoctor(PersonData data);

    // 编辑医生及其用户账户
    Doctor editDoctor(int id, PersonData data);

    // 删除医生、其时间段及其账户——如果有预约则拒绝
    void deleteDoctor(int id);

    // —————————————————————————— 客户
    // (ADMIN;addClient 也用于患者的注册,
    // editClient 和 deleteClient 由患者对自己的账户使用)
    // 创建客户及其用户账户(角色 USER)
    Client addClient(PersonData data);

    Client editClient(int id, PersonData data);

    // 删除客户、其账户及其所有预约(过去的和未来的)
    void deleteClient(int id);
}
  • 第 22 行:业务层的契约:其他层可以向它请求什么,而不规定如何完成(接口已在示例 06 中讨论过);
  • 第 25–47 行:读取操作。可能找不到结果的那些方法(第 33–44 行)返回 [Optional]:未知的医生返回一个空的 [Optional],而绝不会返回 [null]。另一方面,当没有内容可返回时,列表为空;
  • 第 50–56 行:预约。[addAppointment] 的注释列出了可能的错误代码:这是控制器必须了解的契约的一部分;
  • 第 60–66 行:医生管理(仅限 ADMIN)。每位医生都与其用户账户一起被创建、修改和删除;
  • 第 72–77 行:客户管理,采用相同的逻辑。[addClient] 也用于注册患者,而 [editClient] 和 [deleteClient] 则用于管理自己账户的患者。

接口的方法隐含是 [public] 和 [abstract]:它们不需要显式定义。有两个 Bean 实现了这一契约:下面介绍的 [BusinessService],以及 [ApplicationModel](文件夹 [web]),后者用医生和客户列表的缓存对其进行扩展,并把其余部分委托给 [BusinessService] (参见“Web 层:共享服务”一节)。控制器使用的是 [ApplicationModel]。

11.12.4. business/PersonData.java

// =========================================================================
// business/PersonData.java
// -------------------------------------------------------------------------
// 在“医生”或“客户”表单中输入的数据,即
// Web 层传给业务层的数据。
// =========================================================================
package rdvmedecins.business;

public record PersonData(
        String title, // Mr、Mme、Melle
        String lastName,
        String firstName,
        // 创建:可选(null),默认为小写的姓
        // 编辑:可选,如果缺失则登录名保持不变
        String login,
        // 创建:可选,默认为登录名
        // 编辑:可选,如果缺失则密码保持不变
        String password,
        // 编辑:显示表单时记录的版本
        // (乐观锁,参见 AbstractEntity.version)
        Integer version) {
}

要创建或修改的医生或客户的数据,由 Web 层传递(参见示例 28):一个 record,其组件在这里每行写一个,以便为注释留出空间(第 9–21 行)。称谓、姓和名始终会提供。用户名和密码(第 15 行和第 18 行)是可选的,未输入时设为 [null] :创建时,它们默认为小写的姓;修改时,它们保持不变。[version] (第 21 行)是显示编辑表单时所读取记录的版本:它用于乐观锁。它的类型是 [Integer],而不是 [int],这样它才可以是 [null] (创建时没有版本)。

11.12.5. business/BusinessService.java

这是应用程序中内容最全面的文件。我们分五段连续的摘录来展示它。

11.12.5.1. 描述符

// =========================================================================
// business/BusinessService.java
// -------------------------------------------------------------------------
// 业务层的实现。
//
// 医生和客户的管理遵循三条业务规则:
//
//   1. 人员(医生或客户)及其用户账户始终一起
//      处理:它们在同一个事务中一起创建、编辑和删除——
//      要么全部成功,要么什么都不写入;
//   2. 登录名在整个应用中是唯一的,并且两位医生(或
//      两位客户)不能有相同的名和姓;
//   3. 删除:
//      - 有预约的医生不能被删除(其
//        患者会在不知情的情况下失去预约):必须
//        先取消这些预约。其时间段会随之一起消失;
//      - 而客户则会连同其所有预约(过去的和
//        未来的)一起消失——无论删除请求来自 ADMIN 还是来自患者
//        本人。
//
// 还有两条预订预约的规则,无论预订者的角色是什么
// (ADMIN、DOCTOR 或患者本人):
//   4. 不能在过去预约;
//   5. 一位患者同一时间只能有一个即将到来的预约。
//
// 医生和客户遵循完全相同的规则:公共代码
// 只写一次(泛型的私有方法 xxxPerson),并由一个小的
// “描述符”来参数化,它指明我们处理的是哪种类型的人员。
//
// 事务由 TransactionTemplate 显式开启
// (参见文件末尾的 transaction 方法),以便把数据库在 COMMIT 时报告的错误
// 转换为 BusinessException。
// =========================================================================
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:业务层的 Bean;整个应用
// 只有一个实例(单例)
@Service
public class BusinessService implements Business {

    // 就业务规则而言,医生与客户的所有区别
    private record Descriptor<T extends Person>(
            PersonRepository<T> dao,
            Supplier<T> factory, // Doctor::new 或 Client::new
            Role role, // DOCTOR 或 USER
            String notFoundKey, // 人员不存在时的消息
            String alreadyExistsKey, // 相同的名和姓已存在时的消息
            // 可选(null):如果存在,只要该人员还有预约
            // (countAppointments > 0),就拒绝删除,并给出消息 hasAppointmentsKey
            IntToLongFunction countAppointments,
            String hasAppointmentsKey,
            // 可选:必须在删除该人员之前先删除的内容(通过外键
            // 引用它的行)
            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;

    // 所有依赖都由 Spring 的
    // 依赖注入提供。TransactionTemplate:Spring Boot 提供的 Bean,用于
    // 在事务中执行代码。
    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",
                // 没有预约的医生仍可能有时间段:
                // 没有医生它们就没有意义了,我们一并删除它们(否则
                // 外键 slots.doctor_id 会禁止删除)
                slotRepository::deleteByDoctor);

        clientDescriptor = new Descriptor<>(
                clientRepository,
                Client::new,
                Role.USER,
                "ERRORS.PATIENT_NOT_FOUND",
                "ERRORS.PATIENT_ALREADY_EXISTS",
                // 没有 countAppointments:客户的删除从不被拒绝;
                // 其预约(过去的和未来的)会一并删除(否则
                // 外键 appointments.client_id 会禁止删除)
                null,
                null,
                appointmentRepository::deleteByClient);
    }
  • 第 6–24 行:头部注释概述了该类所应用的五条业务规则;
  • 第 50–52 行:来自 [Spring] 的、表示数据库错误的异常,以及用于检查它们的工具(参见最后一段摘录);
  • 第 53 行:[PasswordEncoder] 接口,来自 [Spring Security],用于计算 [bcrypt] 哈希值(参见示例 25)。对应的 Bean,即成本因子为 10(与 SQL 脚本中密码的相同)的 [BCryptPasswordEncoder] ,声明在 [config/SecurityConfig.java] 中(参见“身份验证”一节);
  • 第 55 行:[TransactionTemplate],用于在事务中执行代码(参见最后一段摘录);
  • 第 75–76 行:[@Service] 使该类成为业务层的 Bean。与所有默认的 Bean 一样,它是一个单例:整个应用程序只有一个实例,由所有请求共享。这不成问题,因为该对象不存储任何特定于请求的数据:它的字段都是依赖,一次性设定。Bean 的名称是类名,首字母小写:[businessService],也就是 [ApplicationModel] 在其 [@Qualifier] 中引用的名称。该类实现了 [Business] 接口:它必须提供该接口的所有方法;
  • 第 79–92 行:在业务规则方面区分医生与客户的一切:其仓库、创建空对象的方式、其账户的角色([DOCTOR] 或 [USER])、其错误消息,以及删除时发生的事情。由于医生和客户遵循相同的规则,这些规则的代码只写一次,写在接受描述符的泛型方法中。描述符是一个泛型 record,声明在类内部(并且是 [private]:没有其他人使用它);
  • 第 81、87 和 91 行:三个函数式接口 ,来自 [java.util.function] 包——只有一个方法、用来描述函数类型的接口。[Supplier<T>] 是一个无参数、返回 [T] 的函数(方法 [get()]);[IntToLongFunction],是接受一个 [int] 并返回一个 [long] 的函数(方法 [applyAsLong]);[IntConsumer],是接受一个 [int] 而不返回任何内容的函数(方法 [accept])。这种类型的值可以写成 lambda ([x -> ...])或 方法引用 ([Class::method]);
  • 第 94–102 行:类的字段:五个仓库、哈希计算器、[TransactionTemplate],以及两个描述符。[final] 阻止它们在构造函数之后被修改;
  • 第 107–109 行:所有依赖都由 [Spring] 通过依赖注入提供:该类只有一个构造函数,[Spring] 使用所请求类型的 Bean 来调用它。仓库是由 [Spring Data JPA] 编写的实现;[TransactionTemplate] 由 [Spring Boot] 创建;
  • 第 118–129 行:医生描述符。[new Descriptor<>(...)]:菱形符号 [<>] 让编译器推断接收该对象的变量的类型参数([Doctor])。各个值按 record 组件的顺序给出;
  • 第 120 行:[Doctor::new] 是一个构造函数引用:一个返回 [new Doctor()] 的无参函数。它具有预期的类型 [Supplier<Doctor>]。这里并不调用它;每次创建医生时才会调用;
  • 第 124 行:[appointmentRepository::countByDoctor] 是一个方法引用:对象 [appointmentRepository] 的方法 [countByDoctor],它接受一个 [int] 并返回一个 [long]——也就是说,是 [IntToLongFunction] 类型的值。只要医生还有预约,就会拒绝删除该医生;
  • 第 129 行:同样,[slotRepository::deleteByDoctor] (接受一个 [int],无结果)是一个 [IntConsumer]:在删除医生之前,会先删除该医生的时间段;
  • 第 131–142 行:客户描述符。[Java] 没有命名参数或可选参数:两个不需要的组件([countAppointments] 和 [hasAppointmentsKey])被赋值为 [null] (第 140–141 行)。因此,删除客户永远不会被拒绝,并且在删除客户本身之前,会先删除其预约(过去的和将来的);否则,外键 [appointments.client_id] 会阻止删除。

11.12.5.2. 读取操作与日程

    // =======================================================================
    // 读取,在任何事务之外(每个 DAO 查询单独运行,
    // 在调用期间打开一个 EntityManager)
    // =======================================================================

    @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());
    }

    // 与 JSON 服务器(以及原始 Spring 项目)相同的算法
    @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);
        // 时间段编号 -> 在该时间段上预订的预约
        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));
    }
  • 第 6–54 行:读取操作只是委托给 DAO 层,并把仓库的方法名(通常由 [Spring Data JPA] 强加)转换为业务名称。[@Override] 表示该方法实现了接口中的某个方法:编译器会验证它确实存在于 [Business] 中。这些方法不会启动事务:每个查询独立运行,在调用期间创建一个 [EntityManager] (参见“JPA、Hibernate 和 Spring Data”一节)。每个方法都会加载页面所需的关系(个人的账户、时间段对应的医生、预约对应的客户和时间段):返回的实体是游离的,控制器和视图可以安全地读取这些关系;
  • 第 53 行:某位患者即将到来的预约:业务层把当前日期提供给仓库;
  • 第 58–71 行:计算某位医生在指定日期的日程。未知的医生返回空的 [Optional] ([Optional.empty()]);否则,会获取该医生的时间段和当天的预约。日程执行三次相继的读取,彼此独立:这对于一个显示出来的页面是可以接受的,用户必要时会重新加载它;
  • 第 65–66 行:当天的预约存储在一个字典([Map])中,其键是预约所在时间段的标识符。[stream()] 把列表转换为流:一个通过链式操作处理的元素序列。[collect(Collectors.toMap(...))] 把流中的元素存储到字典中:每个预约的键由 [Appointment::getSlotId] (一个方法引用,应用于每个预约)计算,而值由 [Function.identity()] 计算,这个函数返回其参数:即预约本身。如果两个键相等,[toMap] 就会失败,但这不会发生:约束 [unq1_appointments] 防止在同一天的同一时间段安排两个预约。字典避免了为每个时间段遍历整个预约列表;
  • 第 67–69 行:每个时间段都与其预约关联,或者与 [null] 关联:当键不存在时,也就是时间段空闲时,[get] 返回 [null] 。[map] 使用 lambda [slot -> new DoctorDaySlot(...)] 转换流中的每个元素:这是一个匿名函数,其参数 [slot] 写在箭头左侧,结果写在右侧。[toList()] 把结果收集到一个只读列表中。查询所指定的时间段的时间顺序得以保留;
  • 第 70 行:日程,放在一个有内容的 [Optional] 中([Optional.of]);[doctor.get()] 从它的 [Optional] 中取出医生,我们在这里知道它不为空。结果是来自 [DoctorDaySchedule] 对象的 [domain] record,日程视图将显示它。

11.12.5.3. 预约

    // =======================================================================
    // 预约
    // =======================================================================

    // -----------------------------------------------------------------------
    // 在事务中预订预约:
    //   1. 不能在过去预约;
    //   2. 我们锁定患者的行(SELECT ... FOR UPDATE):如果
    //      同一位患者在同一时刻预订两个时间段(两个标签页、
    //      双击等),第二个事务会等待
    //      第一个事务结束——然后看到它刚刚创建的预约;
    //   3. 每位患者只能有一个即将到来的预约;
    //   4. 最后是插入。如果该时间段刚刚被另一位
    //      患者占用,则是 SQL 约束 unq1_appointments(day、slot_id)
    //      拒绝插入——由 [transaction] 转换为 BusinessException。
    // -----------------------------------------------------------------------
    @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:对时间段和患者的“引用”,
            // 无需再从数据库读取它们——只要知道它们的 id 就足以
            // 写入外键
            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;
        });
    }
  • 第 19 和 35 行:整个预订过程都在一个事务中进行:该方法向 [transaction] (参见最后一段摘录)传入一个无参的 lambda,即 [() -> { ... }],它执行任务并返回所创建的预约。lambda 可以使用外围方法的参数([day]、[slot]、[client]),前提是这些参数从未被修改;
  • 第 21–23 行:不能预约过去的时间。无论进行预订的人是什么角色(ADMIN、DOCTOR 或患者),这条规则都会在这里强制执行,即使 Web 层已经隐藏了过去日期的“预订”按钮:请求可以被手工构造;
  • 第 24–25 行:患者的行被 锁定 ,使用 [SELECT ... FOR UPDATE] (参见 [ClientRepository])。这是一种悲观锁:它在任何工作开始之前就被获取,假定可能发生冲突,并一直保持到事务结束。没有它,针对同一位患者同时发送的两个预订(两个标签页、双击)可能在任何一个把预约写入磁盘之前,都通过下面的测试。有了这把锁,第二个事务会等待第一个事务完成,然后看到它创建的预约。找不到的患者(在此期间被删除)会被拒绝:[orElseThrow] 返回 [Optional] 的内容,如果它为空,则抛出由 lambda 生成的异常;
  • 第 26–28 行:每位患者只能有一个即将到来的预约;
  • 第 32–33 行:[getReferenceById] 返回对某个实体的引用 ——一个代理——它只包含标识符,而不从数据库读取该行。要写入 [appointments] 行的外键,只需知道时间段和患者的标识符;无需再次读取它们。我们不直接使用作为参数收到的 [slot] 和 [client] 对象:它们来自 Web 层,是游离的,不属于这个事务的持久化上下文;
  • 第 34 行:插入。[save] 保存新预约(键 [IDENTITY]:[INSERT] 会立即发出)并返回它。如果另一位患者刚刚预订了同一个时间段,锁并不能阻止这种情况(锁作用于患者的记录):拒绝这次插入的是数据库的唯一性约束 [unq1_appointments (day, slot_id)] ,并且 [transaction] 把该错误转换为带有键 [BusinessException] 的 [ERRORS.SLOT_ALREADY_BOOKED];
  • 第 39–44 行:取消预约,没有特殊规则。仓库中的 [remove] 方法是一个 [@Modifying] 请求:它需要一个接受写入的事务,因此要调用 [transaction]。lambda 必须返回一个值:它返回 [null],没有人使用它。

下面是预订期间发送的 SQL 命令,取自控制台记录。第一条读取时间段及其医生([getSlotById],由控制器在 [addAppointment] 之前调用);接下来的三条属于事务:加锁、计数和插入。多亏了 [getReferenceById],时间段和客户都没有被再次读取:

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] 还会写入列 [version]:[Hibernate] 会给每个新实体分配版本 0。

11.12.5.4. 医生和客户的管理

    // =======================================================================
    // 医生和客户——公共方法委托给公共的
    // 私有方法,并带上正确的描述符
    // =======================================================================

    @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);
    }

    // 客户、其账户及其所有预约(ADMIN,或患者
    // 本人通过“管理我的账户”:同一个方法,同样的规则)
    @Override
    public void deleteClient(int id) {
        deletePerson(clientDescriptor, id);
    }

    // -----------------------------------------------------------------------
    // 创建:先创建用户账户(人员引用它),
    // 然后创建人员——全部在一个事务中。
    // -----------------------------------------------------------------------
    private <T extends Person> T addPerson(Descriptor<T> d, PersonData data) {
        String lastName = data.lastName().trim().toUpperCase(Locale.ROOT);
        String firstName = data.firstName().trim();
        // dbrdvmedecins2 数据库的规则:登录名 = 小写的姓,
        // 密码 = 登录名——除非 ADMIN 输入了其他值
        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);
        });
    }

    // -----------------------------------------------------------------------
    // 编辑:人员及其账户(显示名称 "firstName LASTNAME"
    // 必须随之更新;登录名和密码只有在输入了
    // 新值时才会改变)。
    // -----------------------------------------------------------------------
    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()));

            // 乐观锁:如果数据库中的版本不再是表单的版本,
            // 说明在此期间有人编辑了这条记录——我们拒绝,
            // 而不是悄悄覆盖其修改。
            // (如果并发的编辑发生在这次读取之后,则由
            // UPDATE 的 "WHERE version = ..." 子句检测到。)
            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);

            // 我们只是修改对象:在事务中读取的实体
            // 由 JPA“管理”,JPA 会在 COMMIT 时自行发送必要的 UPDATE
            // (无需调用 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;
        });
    }

    // -----------------------------------------------------------------------
    // 删除,在一个事务中,按外键
    // 规定的顺序进行:
    //   1. 如果仍有预约则可能拒绝(医生);
    //   2. 引用该人员的内容(医生的时间段、客户的
    //      预约);
    //   3. 该人员(它引用其账户);
    //   4. 其账户。
    // -----------------------------------------------------------------------
    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] 期望得到一个结果:我们在这里不需要
        });
    }

    // 拒绝已被同类型的另一位人员使用的名和姓
    // (currentId:正在编辑的人员,他显然有
    // 权保留自己的名和姓;创建时为 null)
    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();
    }
  • 第 6–36 行:六个公有方法委托给三个私有的泛型方法,并使用正确的描述符。编译器根据描述符推断出 [T] :[doctorDescriptor] 对应 [Doctor],[clientDescriptor] 对应 [Client];
  • 第 42 行:写在返回类型之前的 [<T extends Person>] 使 [addPerson] 成为一个泛型方法:它有自己的类型为 [T] 的参数,该类型必须是 [Person] 或其子类;
  • 第 43–48 行:数据准备,在事务之外。[trim()] 去除字符串首尾的空格;名称的首字母大写。[Locale.ROOT] 要求进行与服务器语言无关的转换(例如在土耳其语中,[I] 的小写形式不是 [i])。默认情况下,用户名与姓相同,并且始终为小写;默认情况下,密码与用户名相同:这些是 SQL 脚本中的账户规则。[a ? b : c] 是条件运算符:如果 [a] 为真,则为 [b] ,否则为 [c];
  • 第 51–52 行:在事务中检查两条唯一性规则:不得有重复的姓名,登录名必须未被占用。这些检查在写入数据库之前进行,以便显示清晰的消息(参见示例 28);
  • 第 54–59 行:先创建用户账户,因为人员引用它(外键)。密码绝不以明文存储:[hasher.encode] 计算它的哈希值,即 [bcrypt]。[save] 立即发送 [INSERT] (键 [IDENTITY]):在这次调用之后,[user] 就有了标识符,并成为受管实体;
  • 第 61–66 行:然后是人员。[d.factory().get()] 指的是描述符的工厂引用:[new Doctor()] 或 [new Client()]。[setUser(user)] 把人员与其账户关联起来:在为人员执行 [INSERT] 时,[Hibernate] 会把账户 ID 写入 [user] 列。如果第二次写操作失败,事务也会回滚第一次写操作:账户绝不可能在没有人员的情况下存在;
  • 第 75–111 行:在单个事务中修改人员及其账户;
  • 第 77 行:人员及其账户([findWithUserById]),如果不存在,则抛出带有描述符键的 [BusinessException] ;
  • 第 84–86 行:乐观锁 (参见示例 28):表单携带了显示时所读取记录的版本;如果数据库中的版本不同,说明有人在此期间修改了该记录,系统会拒绝更新,而不是悄无声息地覆盖他们的工作。与预订时使用的悲观锁不同,这里不会阻塞任何东西:我们假定冲突很少发生,只是检测它们。这些版本是 [Integer],它们是对象:我们用 [equals] 来比较,而不是用 [!=],后者比较的是对象引用。如果并发修改发生在这次读取之后,那么检测到它的是 [WHERE version = ...] 条件,它属于 [UPDATE] (参见最后一段摘录);
  • 第 88–90 行:新的名和姓,以及同名检查。它传入此人的标识符:此人显然有权保留自己的名和姓;
  • 第 95–97 行:只需修改所读取的对象。它是在事务中读取的,因此被 管理 于 [EntityManager],后者会在 [COMMIT] 时,通过将对象与所读取的状态进行比较,自行发送 [UPDATE](参见“JPA、Hibernate 和 Spring Data”一节):无需调用 [save]。[UPDATE] 会递增版本并检查旧版本;
  • 第 99–108 行:账户跟随人员。它与人员一起被加载([@EntityGraph]),同样是受管的:它的显示名称被重新计算;只有在输入了登录名且与当前登录名不同时,登录名才会改变(这种情况下它必须是可用的);只有在输入了密码时,密码才会改变;并且同样会被哈希;
  • 第 109 行:返回修改后的人员;在 [COMMIT] 之后,她是游离的,但已加载的账户仍然可以被控制器读取;
  • 第 122–135 行:删除,在事务中,按外键所要求的顺序进行;
  • 第 124 行:[findById] 就足够了:不需要账户,只需要它的标识符,它由 [userId] 字段提供,而无需加载账户;
  • 第 125–127 行:可能的拒绝:有已安排预约的医生不能被删除(其患者将在没有收到通知的情况下失去预约)。[d.countAppointments().applyAsLong(id)] 调用描述符中列出的函数,即 [appointmentRepository.countByDoctor(id)];
  • 第 128–130 行:删除对此人的引用:医生的时间段、客户的预约;
  • 第 131–132 行:先删除人员,再删除该人员所引用的账户;
  • 第 133 行:[transaction] 需要一个返回结果的函数:返回 [null],没有人会使用它;
  • 第 140–146 行:同名者会被拒绝,除非它指的是当前正在编辑的人员([currentId],新建时为 [null] )。[Objects.equals(a, b)] 比较两个对象并接受 [null]:[namesake.get().getId().equals(null)] 同样可行,但 [Objects.equals] 避免了判断两者中哪一个可能是 [null] 的需要;
  • 第 148–152 行:已被占用的用户名——无论是被医生、客户还是管理员占用——都会被拒绝;
  • 第 154–156 行:缺失([null])或为空的字符串:这就是处理未输入的可选字段的方式。

请注意,只有创建操作才调用 [save]。更新只是修改现有实体,而删除是通过 [delete] 查询完成的:这是使用 [JPA] 的标准方式。

11.12.5.5. 事务与唯一性约束

    // -----------------------------------------------------------------------
    // 在事务中执行 [work]:
    //   transactions.execute(...) -> START TRANSACTION,然后执行工作,然后
    //   如果一切顺利则 COMMIT;如果抛出异常
    //   (包括 BusinessException),则 ROLLBACK:什么都不写入。
    //
    // “登录名可用”和“名 + 姓唯一”的检查在写入之前进行,
    // 以便给出明确的消息。但两位 ADMIN 可能在同一时刻
    // 保存相同的登录名(或相同的医生):在这种
    // 罕见的情况下,是 SQL 唯一性约束拒绝第二次
    // 写入——发生在 Hibernate 发送 SQL 语句的时刻,通常是在
    // COMMIT 时,也就是在工作结束之后。这就是为什么我们在这里、在事务
    // 外围拦截异常,把它们转换为同一个
    // 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; // 真正的异常状况:我们让它继续向上传播
        }
    }

    // -----------------------------------------------------------------------
    // 数据库错误 -> BusinessException
    //
    // Spring 将 Hibernate 和 JDBC 驱动程序的异常转换为一个
    // 与数据库无关的异常层次结构(DataAccessException):
    // - OptimisticLockingFailureException:UPDATE "WHERE id = ... AND
    //   version = ..." 没有修改任何行(乐观锁);
    // - DataIntegrityViolationException:数据库的某个约束拒绝了
    //   写入。对于 UNIQUE 约束,MySQL 的错误消息
    //   (异常的“最具体”原因)会引用该约束的名称:
    //     Duplicate entry 'marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
    //   (MySQL 8 会在名称前加上表名,MariaDB 则不会)。这就是
    //   SQL 脚本为其所有约束命名的原因。
    // 任何其他错误都是真正的异常状况:我们返回 null(不翻译)。
    // -----------------------------------------------------------------------
    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;
    }
}
  • 第 16 行:所有写入都经过这个泛型方法:[R] 是处理结果的类型([Appointment]、[Doctor]、 [Client],或者 [Object] (当 lambda 返回 [null] 时)),而 [Supplier<R>] 是返回 [R] 的无参函数的类型;
  • 第 18 行:[transactions.execute(...)] 开启一个事务([START TRANSACTION]),执行传给它的 lambda,然后提交事务([COMMIT])并返回 lambda 的结果。如果 lambda 抛出非受检异常——包括 [BusinessException]——事务就会回滚([ROLLBACK]),并重新抛出该异常。lambda 函数接收事务状态作为参数([status]),这使它可以在不抛出异常的情况下请求回滚;不过,它并没有这样做——它只是调用 [work.get()];
  • 第 19–20 行:[BusinessException] (被拒绝的业务规则)会原封不动地传回给控制器。这个代码块必须位于下一个之前:[BusinessException] 本身就是一个 [RuntimeException],而 [Java] 会按顺序尝试各个 [catch] 块;
  • 第 21–26 行:任何其他异常都由 [translateDatabaseError] 处理:如果它是已知的数据库错误,就改为抛出相应的 [BusinessException];否则,它是真正的异常情况,原样重新抛出,这会生成一个 500 错误页面;
  • 第 45–49 行:对于 SQL 脚本中每个命名的唯一性约束,给出其翻译键。这就是 SQL 脚本为其所有约束命名的原因。[Map.of(k1, v1, k2, v2...)] 创建一个只读字典;[static final] 使它成为类常量,只创建一次;
  • 第 51 行:一个正则表达式,由 [Pattern.compile] 一次性编译好。它从数据库错误消息中提取约束名称(见下文);
  • 第 53–65 行:把数据库错误翻译为 [BusinessException],如果无法识别该错误,则返回 [null] ;
  • 第 54–56 行:[UPDATE ... WHERE id = ... AND version = ...] 没有修改任何行:有人在读取和保存之间修改了该记录(乐观锁)。[instanceof] 检查对象的实际类型。收到的异常是 [ObjectOptimisticLockingFailureException],它是 [OptimisticLockingFailureException] 的子类;
  • 第 57–63 行:数据库约束拒绝了这次写入;
  • 第 58 行:[Spring] 异常包装了 [Hibernate] 异常,而后者又包装了驱动程序异常 [MySQL]:每个异常都把前一个异常保留为它的原因 ([getCause()])。[NestedExceptionUtils.getMostSpecificCause(e)] 追溯到根本原因,即驱动程序的异常,其消息就是 [MySQL] 的消息。[String.valueOf] 处理来自 [null] 的消息(此时它返回字符串 ["null"]);
  • 第 59–61 行:在这条消息中搜索约束名称,如果它出现在字典中,就对其进行翻译。[find()] 在消息中搜索正则表达式;[group(1)] 返回括号中第一个分组所捕获的内容。任何其他错误,包括违反了字典中找不到的约束,都会原样返回而不加翻译:这是真正的异常情况。

唯一性约束被违反时的错误消息会指明约束的名称。下面是在两次输入相同的名和姓时 [MariaDB] 产生的消息(排序规则不区分大小写:[marie pelissier] 是 [Marie PELISSIER] 的重复):

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

[MySQL] 8 写出 [for key 'doctors.unq_doctors_first_name_last_name'],以表名作为前缀。正则表达式 [for key '(?:[^'.]*\.)?([^']+)'] 两种形式都接受:[(?:[^'.]*\.)?] 跳过以句点结尾的可选前缀(一个不捕获任何内容的分组 [(?:...)]),而分组 [([^']+)] 捕获直到撇号为止的名称。在 [Java] 字符串中,句点写作 [\\.]:反斜杠被写了两次,因为它本身就是 [Java] 字符串中的转义字符。

还需要解释为什么应用程序使用 [TransactionTemplate] 而不是示例 28 中的注解 [@Transactional] 。原因有两个:

  • 数据库中的错误并不总是出现在工作本身之中。新实体的 [INSERT] 会立即发送(键 [IDENTITY]):创建时违反的唯一性约束会在 [save] 期间、在 lambda 内部引发异常。然而,被修改实体的 [UPDATE] 要到 [COMMIT] 时才会发送(参见 [editPerson]):只有到那时,数据库才会报告登录名已被占用或版本已过期。使用 [@Transactional] 时,[COMMIT] 发生在方法返回之后,位于包裹该方法的 [Spring] 代码之中:方法无法拦截由它引起的错误。示例 28 通过调用 [saveAndFlush] 规避了这个问题,它会强制立即发送 SQL 命令。使用 [transactions.execute(...)] 时,[COMMIT] 是在 [transaction] 方法内部执行的:它的 [try] 处理所有错误,无论这些错误发生在处理期间还是 [COMMIT] 期间;
  • [@Transactional] 通过代理工作:[Spring] 把 Bean 包装在一个对象中,该对象在调用方法之前开启事务。同一个对象内部一个方法对另一个方法的调用不会经过这个代理:如果把它放在被 [addDoctor] 调用的私有方法 [addPerson] 上,该注解就不会起作用。[TransactionTemplate] 没有这个限制:它就是一次普通的方法调用。

最后,在发生失败时,没有什么需要清理的:持久化上下文与事务绑定,并随着事务在 [ROLLBACK] 中一同消失。而 [ASP.NET Core] 版本则必须清除其 [DbContext] 中的变更跟踪,后者会持续整个请求期间。

11.13. 身份验证

[auth] 文件夹以更完整的形式包含了示例 25 到 27:Cookie 中的 JWT 令牌、角色、验证码和尝试次数限制。它还包含用于创建客户账户的“通行证”。[Spring Security] 自身的配置把这些组件整合在一起,存放在与其他配置类相同的文件 [config/SecurityConfig.java] 中:我们就从这里开始。本节末尾讨论的 [AuthController] 控制器负责提供登录页面。

11.13.1. config/SecurityConfig.java

该文件分成两段摘录来展示。第一段声明密码学相关的 Bean:密钥、令牌的生成与验证,以及密码哈希。

// =========================================================================
// config/SecurityConfig.java
// -------------------------------------------------------------------------
// Spring Security 的配置(参见第 8 章):谁可以访问
// 什么,以及每次请求时如何识别用户。
//
// Spring Security 是放在 Spring
// MVC 前面的一条 Servlet 过滤器链。对于每个请求:
//   1. OAuth2“资源服务器”过滤器查找 JWT 令牌(此处位于
//      rdvmedecins_jwt Cookie 中),检查其签名和过期
//      日期,并由此得出用户(Authentication);
//   2. 授权过滤器应用 URL 访问规则;
//   3. 只有此后 Spring MVC 才调用操作,其注解
//      @PreAuthorize(由 @EnableMethodSecurity 启用)会检查角色。
// 两种失败情形,两种适合 HTML 应用的响应:
//   - 没有已通过身份验证的用户(没有令牌、令牌已过期或被伪造)
//     -> 重定向到登录页面;
//   - 角色不足 -> 403 响应,由 ErrorController 转换为页面。
// =========================================================================
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 {

    // 用于签署和验证令牌的密钥(对称算法 HMAC-SHA256)
    @Bean
    public SecretKey jwtKey(AuthProperties auth) {
        byte[] bytes = auth.jwtSecret().getBytes(StandardCharsets.UTF_8);
        if (bytes.length < 32) {
            // HMAC-SHA256 要求密钥至少为 256 位:我们在启动时就明确
            // 说明这一点,而不是等到第一次登录时
            throw new IllegalStateException(
                    "rdvmedecins.auth.jwt-secret must be at least 32 characters long (see application.properties).");
        }
        return new SecretKeySpec(bytes, "HmacSHA256");
    }

    // 令牌的构建(参见 auth/AuthService.java)
    @Bean
    public JwtEncoder jwtEncoder(SecretKey key) {
        return NimbusJwtEncoder.withSecretKey(key).algorithm(MacAlgorithm.HS256).build();
    }

    // 令牌的验证:签名和过期日期
    @Bean
    public JwtDecoder jwtDecoder(SecretKey key) {
        return NimbusJwtDecoder.withSecretKey(key).macAlgorithm(MacAlgorithm.HS256).build();
    }

    // 密码的哈希:bcrypt,10 轮,版本 $2b$——与
    // SQL 脚本中的哈希相同
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(BCryptVersion.$2B, 10);
    }

我们来说明这段代码:

  • 第 4–18 行:头部注释回顾了第 8 章中讨论的原理:[Spring Security] 是一条由Servlet 过滤器组成的链,在请求到达 [Spring MVC] 之前执行。一个过滤器根据令牌识别用户,另一个对 URL 应用访问规则,然后每个动作上的 [@PreAuthorize] 注解验证角色;
  • 第 54 行:[@Configuration] 把该类变成 Bean 的来源:它每个带有 [@Bean] 注解的方法在启动时被调用一次,它返回的对象成为一个单例 Bean,由 [Spring] 在需要它的任何地方注入;
  • 第 55 行:[@EnableMethodSecurity] 启用对控制器上的 [@PreAuthorize("hasRole('ADMIN')")] 注解的验证(参见示例 26)。没有它,这些注解就会被忽略,而且不会有任何错误消息;
  • 第 59–69 行:用于签名和验证令牌的密钥(参见示例 25)。参数 [AuthProperties auth] 是为属性 [rdvmedecins.auth.*] (来自 [application.properties] ,参见“项目配置”)提供类型化结构的 record:[Spring] 像提供任何其他 Bean 一样提供它。相对于示例 25 的新特性:过短的密钥会被拒绝。HMAC-SHA256 算法需要 256 位的密钥,即 32 个字节;生成令牌的 [Nimbus] 库只会在生成第一个令牌时——也就是第一次连接时——才进行这项验证。而在这里,在创建 Bean 时抛出的异常会阻止应用程序启动,并给出一条确切指明需要纠正什么的消息;
  • 第 72–81 行:使用同一个密钥进行令牌生成([JwtEncoder])和验证([JwtDecoder]);该算法是对称的。解码器验证签名和过期时间(声明 [exp])。默认情况下,它允许服务器之间存在六十秒的时钟偏差容限:令牌在过期后一分钟内仍然有效;
  • 第 85–88 行:使用 [bcrypt] 算法进行密码哈希(参见示例 25)。这一次有两个参数:成本因子(10:该算法执行 2^10 轮计算,这使得涉及数百万次密码尝试的暴力攻击代价非常高昂)和算法的版本。SQL 脚本中的密码是由某个库哈希的,它写出以 [$2b$10$] 开头的哈希值,而 [BCryptPasswordEncoder] 默认写出 [$2a$]。两个版本都能毫无困难地通过验证;强制使用 [$2B] 版本([BCryptVersion] 枚举中的一个常量:字符 [$] 在 [Java] 标识符中是允许的)只是为了让应用程序创建的账户拥有与脚本中形式相同的哈希值。

第二段摘录是过滤器链本身,以及它的两个后备响应。

    @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. URL 访问规则,按顺序检查。公开的
                // 页面:登录、账户创建、语言选择、
                // 静态文件、错误页面。所有其他页面都需要
                // 已通过身份验证的用户;角色由控制器的
                // @PreAuthorize 检查。
                .authorizeHttpRequests(access -> access
                        .requestMatchers("/", "/login", "/register", "/register/**", "/language/**",
                                "/css/**", "/js/**", "/lib/**", "/error")
                        .permitAll()
                        .anyRequest().authenticated())
                // 2. JWT 令牌身份验证,从 Cookie 中读取
                .oauth2ResourceServer(jwt -> jwt
                        .bearerTokenResolver(AuthService::tokenOf)
                        .authenticationEntryPoint(toLogin)
                        .accessDeniedHandler(accessDenied)
                        .jwt(config -> config.jwtAuthenticationConverter(converter())))
                // 3. 两种失败情形
                .exceptionHandling(errors -> errors
                        .authenticationEntryPoint(toLogin)
                        .accessDeniedHandler(accessDenied))
                // 4. 登出(POST /logout):清除令牌的 Cookie,
                // 然后转到登录页面。仅限 POST:放在其他站点上的
                // 简单链接(GET)无法在用户不知情的情况下
                // 将其登出
                .logout(out -> out
                        .logoutRequestMatcher(PathPatternRequestMatcher.withDefaults().matcher(HttpMethod.POST, "/logout"))
                        .deleteCookies(AuthService.JWT_COOKIE)
                        .logoutSuccessUrl("/login"))
                // 5. 服务器是无状态的:绝不使用 HTTP 会话
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                // 6. 没有防 CSRF 令牌:SameSite=Lax Cookie 已经保护了
                // 来自其他站点的 POST 请求(参见 AuthService)
                .csrf(csrf -> csrf.disable());
        return http.build();
    }

    // -----------------------------------------------------------------------
    // 没有已通过身份验证的用户 -> 登录页面。如果存在
    // Cookie,则其令牌已不再有效:会话已过期。
    // 于是我们清除该 Cookie,并通过闪现
    // 消息提醒用户(在 Spring MVC 之外设置,因此使用 Flash Bean)。
    // -----------------------------------------------------------------------
    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");
        };
    }

    // -----------------------------------------------------------------------
    // 从令牌到已通过身份验证的用户:[name] 声明是其姓名
    // (Authentication.getName()),[role] 声明是其角色。Spring Security
    // 以 ROLE_ 前缀书写角色:声明 role=ADMIN 会变成
    // 权限 ROLE_ADMIN,由 hasRole('ADMIN') 检查。
    // -----------------------------------------------------------------------
    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;
    }
}

我们来分解这段代码:

  • 第 2 行:Bean [SecurityFilterChain] 描述过滤器链。[HttpSecurity] 是由 构建器 对象,由 [Spring Security] 提供:对它调用的每个方法([authorizeHttpRequests]、[oauth2ResourceServer]、[logout]……)配置安全的一个方面,而 [build()] (第 40 行)构造过滤器链。每个方法都接收一个 lambda (参见示例 25)来配置相应的方面。参数 [Flash flash] 是一个应用程序 Bean(文件夹 [web]),用来发布来自 [Spring MVC] 的闪现消息;
  • 第 4–5 行:对角色不足的响应:[sendError(403)]。该 lambda 实现了 [AccessDeniedHandler] 接口,它只有一个方法(一个函数式接口)。[sendError] 本身并不生成页面:[Tomcat] 服务器把请求转发到 [/error],由 [ErrorController] (参见“Web 层:控制器”)生成 403 错误页面,与示例 26 中一样;
  • 第 12–16 行:URL 的访问规则,按顺序检查:第一条与 URL 匹配的规则生效。根目录、登录、账户创建、语言选择、静态文件和错误页面是公开的([/**] 表示某个路径下的所有内容)。任何其他 URL 都需要已通过身份验证的用户。这里不检查角色,而是在每个动作上通过 [@PreAuthorize] 检查:因此规则就写在它所保护的代码旁边。[/error] 必须是公开的:否则,未登录访客的错误页面本身也会被拒绝;
  • 第 18–22 行:基于令牌的 JWT 身份验证,由 [Spring Security] 的“资源服务器”模块([OAuth2] “资源服务器”)处理,与示例 25 中一样。默认情况下,该模块在 [Authorization: Bearer ...] 头中查找令牌;第 19 行为它提供另一个 [BearerTokenResolver],从 [rdvmedecins_jwt] Cookie 中读取令牌。[AuthService::tokenOf] 是一个方法引用:是 lambda [request -> AuthService.tokenOf(request)] 的简写形式。静态方法 [tokenOf] (文件 [auth/AuthService.java])的形式确实与函数式接口 [BearerTokenResolver] 所要求的完全一致:它接收请求并返回令牌,或者返回 [null]。第 22 行:由已验证的令牌创建已认证用户的转换器(第 65–73 行);
  • 第 20 和 25 行:同一个入口点 [toLogin] 被指定了两次,因为有两种未通过身份验证的方式。存在但无效的令牌(已过期、伪造)会被资源服务器过滤器拒绝,该过滤器调用它自己的入口点(第 20 行)。没有令牌:过滤器放行匿名请求,授权过滤器通过调用 [exceptionHandling] 的入口点(第 25 行)来拒绝它。同样,角色不足的处理程序在两个位置都被指定(第 21 行和第 26 行)。[exceptionHandling] 中的处理程序(第 26 行)处理来自 [@PreAuthorize] 的拒绝;第 21 行是一种预防措施,以确保这两种配置保持对称。如果没有任何处理程序,资源服务器会以它自己的方式响应 403 错误,带有面向 [WWW-Authenticate] 头,该头是为 [JavaScript] 客户端准备的,并且没有错误页面;
  • 第 31–34 行:注销由 [Spring Security] 自身处理;没有任何控制器具有名为 [/logout] 的动作。[deleteCookies] 清除令牌 Cookie,然后浏览器被重定向到 [/login]。第 32 行只接受 POST 方法:当 CSRF 保护被禁用时(第 39 行),[Spring Security] 会接受使用任何方法——包括 GET——的 [/logout] ,这样放在另一个站点上的一张简单图片([<img src="http://.../logout">])就足以让用户注销。[PathPatternRequestMatcher] 通过方法和路径来描述请求;
  • 第 36 行:[STATELESS]:[Spring Security] 从不创建 HTTP 会话(示例 20 和 23 中的 [JSESSIONID] Cookie),也不用它来跟踪用户:用户在每个请求中都根据其令牌被识别。服务器在两次请求之间不在内存中存储任何内容;
  • 第 39 行:默认情况下,[Spring Security] 通过要求每个表单包含一个带有随机令牌的隐藏字段,来保护 POST 表单免受 CSRF 攻击(另一个站点上的陷阱页面向我们的站点提交表单)。与示例 25 中一样,我们在这里不需要它:应用程序的 Cookie 是 [SameSite=Lax],浏览器不会把它们附加到来自其他站点的 POST 请求上;因此恶意请求到达时将没有 JWT 令牌——是匿名的——并会被拒绝;
  • 第 49–57 行:入口点,即对未通过身份验证请求的响应:重定向到登录页面(参见示例 25)。新特性(第 51–54 行):如果请求包含令牌 Cookie,就意味着用户曾经登录过,但其令牌已不再有效(已过期或伪造)。我们删除这个已经无用的 Cookie,并设置一条“会话已过期”的闪现消息,由登录页面显示,而不是让用户纳闷自己为什么会来到这里。该消息是一个翻译键(参见示例 22)。我们目前处于 [Spring Security] 的一个过滤器中,位于 [Spring MVC] 之前:示例 20 中的 [RedirectAttributes] 对象此时尚不存在,因此才有了 [Flash] Bean(放在 [web] 文件夹中);
  • 第 65–73 行:示例 26 中的转换器接收已验证的令牌,并创建对象 [Authentication],它代表发出请求的用户。声明 [role] 提供授权,带有前缀 [ROLE_]:声明 [role=ADMIN] 变为授权 [ROLE_ADMIN],由 [hasRole('ADMIN')] 验证。声明 [name] 变为用户名([Authentication.getName()])。声明的名称是 [ConnectedUser] record(下一个文件)中的常量。

在 [Spring] 中,这相当于 [JwtBearer] 处理程序对 [ASP.NET Core] 及其“事件”的配置:[BearerTokenResolver] 起到事件 [OnMessageReceived] 的作用,而 [AuthenticationEntryPoint] 起到 [OnChallenge] 的作用。

让我们用 [curl] 来检查这些响应,针对不需要登录的请求。未带 Cookie 请求受保护的页面,会被重定向到登录页面:

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

要继续下去,我们需要一个令牌。这是患者 [martin] 的令牌;它是专门为此使用 [application.properties] 中的密钥,由一个执行 HMAC-SHA256 计算的小程序生成的。这凸显了妥善保管这个密钥的重要性:任何知道它的人都可以为任何人生成令牌。不过,读者并不需要这项计算:他们用浏览器登录,然后从开发者工具(F12)中复制 [rdvmedecins_jwt] Cookie 的值。在生产环境中,它会被替换为一个较长的随机字符串(参见“项目配置”)。令牌由三个以句点分隔的 Base64 编码部分组成:头部、内容和签名。

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1IiwibG9naW4iOiJtYXJ0aW4iLCJuYW1lIjoiSmVhbiBNQVJUSU4iLCJyb2xlIjoiVVNFUiIsImV4cCI6MTc5MDM2MjAzNiwiaWF0IjoxNzkwMzU0ODM2fQ.hA1rLedxez9s4xqNcNNjyni_kDI9h496EBk8Oj2apdQ

解码之后,前两部分是明文:令牌是经过签名的,而不是加密的。

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

有了这个令牌,站点的根路径会把患者重定向到他的主页“我的账户”:

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

(令牌在命令中被截断了)。访问仅限 ADMIN 的医生管理部分会被拒绝:[@PreAuthorize] 拒绝访问,处理程序 [accessDenied] 以 [sendError(403)] 作出响应,错误页面由 [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>
...

攻击者现在试图冒充 ADMIN:他们在令牌的内容中把 ["role":"USER"] 替换为 ["role":"ADMIN"] ,同时保留签名。修改后的内容不再与签名匹配:令牌被拒绝,并被当作过期的会话处理:

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

入口点 [toLogin] 执行了三个预期的操作:令牌 Cookie 被清除(第一个头 [Set-Cookie] 把它重置为空,并将有效期设为零),一条闪现消息被存储在 [rdvmedecins_flash] Cookie 中(第二个头,在 [web/CookieFlashMapManager.java] 文件中有说明),浏览器被重定向到 [/login],消息显示在页面底部:

Image

同样的处理也适用于已过期的令牌,甚至适用于 [/login] 这样的公开页面:资源服务器过滤器会在检查访问规则之前,检查所出示的任何令牌。

剩下的是注销。在 POST 时,它会删除令牌 Cookie 并重定向到登录页面:

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

在 GET 时,URL 和 [/logout] 只是与其他页面一样的受保护页面——而且是不存在的页面:没有令牌时,入口点会把请求重定向到登录页面;有有效令牌时,它会返回 404 页面。无论如何都不会让用户注销:

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
// -------------------------------------------------------------------------
// JWT 令牌包含什么,以及如何将其读回。
//
// 在 Spring Security 中,请求的用户是一个
// Authentication 对象,存放在请求的 SecurityContext 中。使用
// JWT 令牌身份验证时(参见 config/SecurityConfig.java),它是一个
// JwtAuthenticationToken,其中包含已验证的令牌:一个 Jwt 对象,其
// “claims”就是令牌的各个字段。控制器
// 通过参数 @AuthenticationPrincipal Jwt token 获取它。
//
// 我们令牌的 claims(参见 AuthService.setToken):
//   sub   :用户账户的 id(JWT 约定:“subject”)
//   login :登录名
//   name  :显示名称("Marie PELISSIER"),用于导航栏
//   role  :ADMIN、DOCTOR 或 USER
// =========================================================================
package rdvmedecins.auth;

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

import rdvmedecins.entities.Role;

// 已连接的用户,以带类型的形式表示
public record ConnectedUser(int userId, String login, String name, Role role) {

    // 各个 claim 的名称
    public static final String SUB = "sub";
    public static final String LOGIN = "login";
    public static final String NAME = "name";
    public static final String ROLE = "role";

    // 由已验证的令牌所描述的用户;如果令牌
    // 不存在(未经身份验证的请求)或格式错误,则为 null
    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;
    }
}

我们来分解这段代码:

  • 第 6–11 行:在 [Spring Security] 中,请求的用户是一个 [Authentication] 对象,存储在请求的 [SecurityContext] 中。对于 JWT 令牌,它是一个 [JwtAuthenticationToken],其中包含已验证的令牌,即一个 [Jwt] 对象。动作通过带有 [@AuthenticationPrincipal Jwt token] 注解的参数来接收它(参见示例 25);
  • 第 26 行:登录用户的类型化形式:一个整数标识符、一个类型为 [Role] 的角色(来自 [ADMIN]、[DOCTOR]、[USER] 的枚举,位于 [entities] 文件夹),而不是一个其声明按名称标识的令牌。这是一个 record (参见“领域:日历”):[Java] 为我们生成构造函数以及访问器 [userId()]、[login()]、[name()] 和 [role()] ;
  • 第 29–32 行:令牌声明的名称,归并为常量:[ConnectedUser.NAME] 中的拼写错误会被编译器指出,而字符串 ["name"] 中的错误只有在运行时才会被发现。record 可以包含静态字段:它们属于类,而不属于每个对象;
  • 第 36–50 行:静态方法 [of] 由已经验证过的令牌(其签名有效)创建用户,或者返回 [null]。[getSubject()] 返回声明 [sub],即以文本形式书写的账户 ID;[Integer.parseInt] 把它转换为整数。[Role.valueOf] 返回具有给定名称的枚举常量。如果文本无效(或者为 [null]),这两个方法都会抛出异常:因此,签名正确但内容不完整的令牌会返回 [null],而不是 500 错误;
  • 第 52–58 行:供视图和控制器使用的两个方法,避免了比较角色:[isAdmin()] 和 [isPatient()]。[Thymeleaf] 视图只需写 [${user.isAdmin()}]。

11.13.3. auth/AuthService.java

该文件分成两段摘录来展示。

// =========================================================================
// auth/AuthService.java
// -------------------------------------------------------------------------
// 身份验证逻辑:
//   - validateUser() :检查登录名 / 密码对;
//   - setToken()     :构建已验证用户的 JWT 令牌
//                      并将其存入 Cookie;
//   - clearToken()   :删除该 Cookie;
//   - currentUser()  :当前请求的已连接用户。
//
// JWT 令牌在哪里传递?
// 使用 JavaScript 客户端时,是客户端的代码保存令牌
// 并自行将其添加到每个请求中(头 "Authorization: Bearer
// ...")。显示普通 HTML 页面的浏览器无法
// 这样做:要让它在每个请求上自行出示令牌,就
// 必须把令牌存放在 Cookie 中。该 Cookie 的选项对
// 安全性很重要:
//   - HttpOnly :页面的 JavaScript 无法读取该 Cookie(因此
//     被注入的脚本无法窃取令牌);
//   - SameSite=Lax :浏览器不会随来自
//     其他站点的 POST 一起发送该 Cookie。由于所有修改数据的操作都
//     是 POST,其他站点上的陷阱页面无法冒充用户
//     来预订或删除任何东西
//     (即所谓的 CSRF 攻击);
//   - Secure :在生产环境(HTTPS)中,Cookie 绝不以明文传输;
//   - Max-Age :Cookie 与令牌同时失效。
// =========================================================================
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 {

    // 承载令牌的 Cookie 的名称
    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()。
    // matches 使用存储的哈希中包含的“盐”对输入的密码进行
    // 哈希,然后比较两个结果。
    public Optional<User> validateUser(String login, String password) {
        return userRepository.findByLogin(login).filter(user -> hasher.matches(password, user.getPassword()));
    }

我们来说明这段代码:

  • 第 11–26 行:注释解释了为什么令牌要通过 Cookie 发送,以及它的每个选项的作用(参见示例 25)。跟随链接和提交表单的浏览器不知道如何在其请求中添加 [Authorization] 头;然而,它会自动把收到的 Cookie 发送回去;
  • 第 57 行:[@Service] 使该类成为单例 Bean(参见示例 06),就像 [@Component] 一样:这两个注解是等价的,[@Service] 只是表明它是一个服务;
  • 第 61 行:承载令牌的 Cookie 的名称;
  • 第 63–76 行:该服务接收包含用户账户的 DAO([UserRepository],参见“DAO 层”)、[bcrypt] 编码器、令牌编码器和解码器([SecurityConfig] 的 Bean),以及身份验证属性。这些字段是 [final]:它们在构造之后不会改变;
  • 第 81–83 行:如果用户名和密码正确,则返回账户(参见示例 25)。[findByLogin] 返回一个 [Optional<User>],这个盒子要么包含一个账户,要么为空(参见“DAO 层”);[filter] 只有在条件为真时才保留该账户;否则返回一个空盒子。条件 [hasher.matches(...)] 用存储的哈希值中包含的“盐”对输入的密码进行哈希,并比较两个结果:密码本身从不被存储。
    // -----------------------------------------------------------------------
    // 构建 [user] 的 JWT 令牌并将其存入 Cookie。
    // 令牌用密钥签署(HMAC-SHA256):浏览器
    // 可以读取它(它没有加密),但不能修改它——任何
    // 修改都会使签名失效。
    // -----------------------------------------------------------------------
    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());
    }

    // 清除 Cookie:我们再次设置它,内容为空,有效期为零
    public static void clearToken(HttpServletResponse response) {
        response.addHeader(HttpHeaders.SET_COOKIE, ResponseCookie.from(JWT_COOKIE, "").path("/").maxAge(0).build().toString());
    }

    // 请求中存在的令牌,无论有效与否
    public static String tokenOf(HttpServletRequest request) {
        Cookie cookie = WebUtils.getCookie(request, JWT_COOKIE);
        return cookie == null ? null : cookie.getValue();
    }

    // -----------------------------------------------------------------------
    // 已连接的用户,或 null。
    // 通常情况下,Spring Security 已经建立了它(SecurityContextHolder)。
    // 但错误页面是由服务器向 /error 地址发出的第二个内部请求
    // 构建的,该请求不会再次经过
    // 身份验证:于是我们自己读取 Cookie 中的令牌,以便
    // 让错误页面的导航栏显示用户。
    // -----------------------------------------------------------------------
    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; // 已过期或被伪造的令牌
        }
    }
}

我们来说明这段代码:

  • 第 8–19 行:令牌,按示例 25 中的方式生成。它包含账户 ID(声明 [sub])、登录名、导航栏中显示的名称、角色、签发日期([iat],“issued at”)和过期日期([exp]),默认比签发日期晚两小时。[JwtClaimsSet.builder()] 返回一个构建器对象:每个声明调用一个方法,最后调用 [build()]。第 18 行:令牌头部指定了算法 HS256(HMAC-SHA256),编码器使用密钥对整个令牌进行签名;
  • 第 20–27 行:Cookie,带有示例 25 中的选项([HttpOnly]、[SameSite=Lax])以及另外两个选项:[Secure],在生产环境中启用(站点以 [HTTPS] 提供服务),阻止浏览器通过未加密的连接发送该 Cookie;[Path=/] 确保它被包含在对站点的所有请求中。[Max-Age] 在令牌过期时删除该 Cookie。[ResponseCookie] 生成 [Set-Cookie] 头的文本,该头由第 27 行添加到响应中;
  • 第 31–33 行:删除 Cookie 就是把它再次设置为空,并把有效期设为零;浏览器会立即删除它。为了让浏览器识别要删除的 Cookie,路径([Path])必须与设置时使用的路径相同。该方法是静态的:它不依赖于对象的任何字段。入口点 [SecurityConfig] 和异常处理程序 [HtmlExceptionHandler] (文件夹 [web])会用到它,它们不需要 [AuthService] 的实例;
  • 第 36–39 行:请求中存在的令牌,不加验证。[WebUtils.getCookie] 在请求所带的 Cookie 中按名称查找某个 Cookie。这就是 [SecurityConfig] 作为 [BearerTokenResolver] 所提供的方法;
  • 第 49–63 行:已登录的用户,或者 [null]。在典型情况下(第 50–53 行),[Spring Security] 已经确立了这一点:[SecurityContextHolder.getContext().getAuthentication()] 返回当前请求的 [Authentication] 对象,其“主体”就是已验证的令牌。[instanceof Jwt token] 检查对象的类型,如果检查成功,就把它存储在变量 [token] 中,该变量已经被转换为 [Jwt]。第二种情况(第 54–62 行)涉及错误页面:当请求以 403 或 404 错误结束时,服务器通过一个第二个内部请求到 [/error] 来生成页面。资源服务器过滤器不处理这个内部请求:用户在该请求中未通过身份验证。为了确保错误页面的导航栏仍然显示用户,我们使用 [SecurityConfig] 中的解码器自行验证 Cookie 中的令牌;过期或伪造的令牌会触发 [JwtException],我们返回 [null]。

[currentUser] 方法由 [web/CommonModel.java] 为每个页面调用,它在模板中为所有视图设置用户。

11.13.4. auth/InvalidSessionException.java

// =========================================================================
// auth/InvalidSessionException.java
// -------------------------------------------------------------------------
// 令牌有效,但它所指向的账户已不存在:该账户在登录之后
// 已被删除(由患者本人在另一个
// 标签页中,或由 ADMIN 删除)。我们将这种情况视为会话已过期:
// web/HtmlExceptionHandler 清除 Cookie 并重定向到
// 登录页面。
// =========================================================================
package rdvmedecins.auth;

public class InvalidSessionException extends RuntimeException {

    public InvalidSessionException() {
        super("the account of the connected user no longer exists");
    }
}
  • 第 12–16 行:令牌可能是有效的(签名正确、未过期),尽管它所指向的账户在用户登录之后已被删除。患者页面通过查找与该账户关联的客户来检测这种情况([web/Utils.java] 文件中的方法 [connectedPatient]),然后抛出这个异常;异常处理程序 [HtmlExceptionHandler] (参见示例 24)会拦截它,删除 Cookie,并重定向到登录页面,同时显示消息“会话已过期”。该异常派生自 [RuntimeException]:它是一个非受检异常,方法不需要使用 [throws] 子句来声明它。构造函数通过 [super(...)] 把它的消息传给父类的构造函数。

11.13.5. auth/Captcha.java

// =========================================================================
// auth/Captcha.java
// -------------------------------------------------------------------------
// 一个验证码:id,放入表单的隐藏字段 "captchaId" 中;
// svg,图片,原样插入页面。
// =========================================================================
package rdvmedecins.auth;

public record Captcha(String id, String svg) {
}
  • 第 9 行:页面所接收到的验证码(CAPTCHA):标识符,放在隐藏的表单字段中,以及 [SVG] 图像,原样插入页面中。一个单独的 record 就足够了:该对象是只读的。预期的答案不会出现在这里:它从不离开服务器。

11.13.6. auth/CaptchaService.java

// =========================================================================
// auth/CaptchaService.java
// -------------------------------------------------------------------------
// 由服务器自己制作的 CAPTCHA(“区分人类与机器人的测试”),
// 不依赖任何外部服务:几个扭曲的字符,
// 被笔画扰乱,位于一张 SVG 图片中(参见 CaptchaDrawing.java)。人类
// 读起来毫无困难;而只是循环发送表单的
// 机器人则无法做到。
//
// 工作原理:
//   1. generate() 绘制一段随机文本,将其转换为图片,并把
//      正确答案保存在服务器的内存中,对应一个随机标识符;
//   2. 页面显示图片,并把标识符放入表单的隐藏字段中
//      (答案本身绝不会离开服务器);
//   3. verify(id, input) 将输入与期望的答案比较,然后
//      忘记这个验证码:每张图片只使用一次,机器人无法
//      重放已经找到的答案。
//
// 单例 Bean(整个服务器只有一个实例),被
// 多个请求并行使用:因此使用 ConcurrentHashMap,这是一个
// 多个线程可以同时读取和修改而
// 不会被破坏的字典。
//
// 可接受的局限:单个进程的内存。如果负载均衡器
// 后面有多台服务器,就需要共享存储。
// =========================================================================
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 {

    // 图片的有效期:你有 10 分钟来填写表单
    private static final Duration LIFETIME = Duration.ofMinutes(10);

    // 内存保护:超过此数量,我们会忘记所有待验证的验证码
    private static final int MAX_CAPTCHAS = 10_000;

    // 期望的答案及其过期日期
    private record Expected(String text, Instant expires) {
    }

    // id -> 期望的答案
    private final Map<String, Expected> pending = new ConcurrentHashMap<>();

    public Captcha generate() {
        purge();
        String text = CaptchaDrawing.randomText(5); // 5 个字符
        String id = UUID.randomUUID().toString(); // 随机的标识符,无法猜测
        pending.put(id, new Expected(text, Instant.now().plus(LIFETIME)));
        return new Captcha(id, CaptchaDrawing.svg(text));
    }

    // 如果 [input] 是验证码 [id] 的正确答案(忽略
    // 大小写),则为 true。验证码在任何情况下都会被消费。
    // remove 是原子的:如果两个请求在同一时刻
    // 出示同一个验证码,只有一个能将其移除——另一个会失败。
    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();
        }
    }
}

该服务与示例 27 中的相同,只增加了两点:过期时间和上限。我们来逐步看这段代码:

  • 第 37 行:单例 Bean——整个服务器只有一个服务,也就是说,所有请求共享同一个待处理验证码列表;
  • 第 41–44 行:图像的有效期为十分钟,并且待处理验证码的数量设有上限。每次显示登录页面时,都会在内存中添加一个验证码;如果没有上限,一个请求该页面数百万次却从不作答的机器人,最终会耗尽服务器的内存。[10_000]:字符 [_] 把数字分成若干组,以提高可读性;
  • 第 47–48 行:预期的答案及其过期日期。该 record 是嵌套的 且私有的:它只为这个服务而存在。[Instant] 表示一个特定的时间点,与时区无关;
  • 第 51 行:标识符 → 预期的答案。该服务是单例,被并发请求使用,每个请求都在自己的执行线程([thread])上:因此使用 [ConcurrentHashMap] (参见示例 27),这是一种字典,多个 [thread] 实例 可以同时读取和修改它而不会损坏它。该字段被声明为由 [Map] 接口所定义的类型:其余代码不依赖于所选择的实现;
  • 第 53–59 行:清理,然后随机生成一个五个字符的文本字符串,以随机标识符([UUID.randomUUID()],122 个随机位,无法猜测)存储,并由 [CaptchaDrawing] 渲染;
  • 第 65–70 行:验证,与示例 27 中的相同:无论如何,验证码都会从字典中移除([remove] 返回被移除的值,或者 [null]),然后我们验证它是否存在、是否未过期,以及输入的内容——去除空格后——是否正确,不区分大小写([equalsIgnoreCase])。[remove] 是原子的:如果两个请求在同一时间提交同一个验证码,只有一个能移除它;另一个收到 [null]。因此每张图像只使用一次:机器人无法重用之前找到的答案;
  • 第 72–78 行:清理。[removeIf] 从字典中移除 lambda 函数返回 [true] 的那些条目——在这里就是已过期的验证码。如果仍然达到上限(正在遭受攻击),所有待处理的验证码都会被丢弃:此刻正在填写表单的真实用户将不得不重新输入新的图像。这种情况只会在遭受攻击时发生:这个简单的方案就足够了。

11.13.7. auth/CaptchaDrawing.java

绘制图像的类就是示例 27 中的那个。它分两部分展示:字符的“字体”,然后是绘制。

// =========================================================================
// auth/CaptchaDrawing.java
// -------------------------------------------------------------------------
// 验证码的 SVG 图片(150 x 50 像素)的绘制,原样取自
// 示例 27。一个重要的要点:每个字符都用
// 笔画(<path>)绘制,绝不写成文本(<text>)——否则机器人
// 只需读取图片的源代码即可。
// =========================================================================
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:“密码学”随机数生成器,
    // 不可预测(不像 Random,其序列可能被猜出)
    private static final SecureRandom RANDOM = new SecureRandom();

    // “字体”:每个字符是一组笔画的列表,每个笔画是 4 x 6 网格中的
    // 点序列 (x, y)(y 轴朝下)。
    // 过于容易互相混淆的字符已被排除(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();

    // 几种深色,在浅色背景上易于阅读
    private static final String[] COLORS = { "#1f4e79", "#7b2d26", "#2e6b30", "#5b2c83", "#8a5a00", "#23395d", "#9c2a5b" };

我们来说明这段代码:

  • 第 16 行:该类不是 [public];没有修饰符时,它只在其包 ([rdvmedecins.auth])内可见,其中只有 [CaptchaService] 使用它。[final] 禁止从它派生其他类;
  • 第 23 行:[SecureRandom] 是一个“密码学”随机数生成器:它的输出是不可预测的,而 [Random] 的输出则可以根据之前的输出被猜出。所有抽取都使用同一个生成器;多个 [thread] 实例 可以同时使用它;
  • 第 28–62 行:“字体”:对于每个字符,是一个笔画列表,每个笔画是 4 × 6 网格中的一系列 (x, y) 坐标。[double[][]] 是数组的数组,这里用花括号以展开形式书写。字典由 [static { ... }] 块(第 30–62 行)填充,该块在类加载时执行一次。容易混淆的字符(0 和 O、1、I 和 L)被省略了。[LinkedHashMap] 保留键的插入顺序;
  • 第 64–65 行:可用的字符——即字体的键——被收集到一个 [char] 数组中。键的流(参见“业务层”)被转换为单字符字符串([String::valueOf]),再把它们连接起来([reduce("", String::concat)]),然后把得到的字符串拆分成数组([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\"/>");

        // 字符:每个字符都经过放大、倾斜、移位,每个点还
        // 被随机地略微移动
        double step = (WIDTH - 20) / (double) text.length();
        for (int i = 0; i < text.length(); i++) {
            double scale = randomBetween(4.6, 5.6); // 网格单位的大小,以像素为单位
            double angle = randomBetween(-0.35, 0.35); // 旋转角度,以弧度为单位(约 ±20°)
            double cx = 10 + step * (i + 0.5) + randomBetween(-3, 3); // 字符的中心
            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) {
                    // 网格点,以 (2, 3) 为中心,经过扭曲、旋转、放置
                    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 条扰乱笔画:穿过图片的曲线
        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();
    }

    // 带小数点的数字,与服务器的语言无关
    // (在法语中,"%.1f" 会写成 "12,5",SVG 无法读取)
    private static String number(double value) {
        return String.format(Locale.ROOT, "%.1f", value);
    }
}

我们来说明这段代码:

  • 第 1–2 行:私有构造函数——该类只包含静态方法,因此永远不会创建对象;
  • 第 4–18 行:随机选择:指定长度的文本、两个边界之间的实数、一种颜色。[nextInt(n)] 返回 0 到 n – 1 之间的整数,[nextDouble()] 返回 0 到 1 之间的实数;
  • 第 20–58 行:图像是一段 [SVG] 文本,在 [StringBuilder] (一种可以不断扩展而无需每次添加元素时重写的字符串)中组装。[formatted] 方法按顺序用其参数替换 [%d] (整数)和 [%s] (字符串)。每个字符(第 29–47 行)变成一个 [<path>] 路径:每个网格点都被轻微偏移、放大、旋转,并放置在图像中的相应位置,颜色和线条粗细随机选择。字符是线条,而不是文本:机器人无法从图像的代码中读出它们。然后,三条干扰曲线横穿图像(第 50–55 行);
  • 第 62–64 行:[SVG] 中的数字用小数点书写。[Locale.ROOT] 强制使用这种写法,而不管服务器的语言:如果语言是法语,[%.1f] 就会使用逗号(参见第 5 章)。

11.13.8. auth/AttemptLimiterService.java

该文件分成两段摘录来展示。

// =========================================================================
// auth/AttemptLimiterService.java
// -------------------------------------------------------------------------
// 防范机器人的第二道屏障(第一道是验证码):我们统计
// 尝试次数,超过阈值就封锁一段时间。
//
//   - 登录:同一 IP 地址上同一登录名失败 loginMaxFailures 次
//     (验证码错误或密码错误)之后,这一
//     组合将被封锁 loginBlockMinutes 分钟。如果同一 IP 地址
//     累计的失败次数达到其 5 倍(所有登录名合计),该 IP 地址也会被封锁(
//     机器人会尝试成千上万个不同的登录名);
//   - 账户创建:同一 IP 地址每
//     小时最多创建 registrationMaxPerHour 个账户。
//
// 在教室里要当心:所有计算机常常通过同一个 IP 地址
// 访问 Internet。这就是为什么登录封锁
// 首先适用于(IP, 登录名)这一组合——输入错误
// 密码的学生不会封锁其邻座——也是为什么阈值可以在
// application.properties 中设置(rdvmedecins.protection.*)。
//
// 单例 Bean,由并行的请求调用:所有公共方法
// 都是“synchronized”——同一时刻只有一个线程读取并修改
// 计数器。
// =========================================================================
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; // 在当前窗口内统计的尝试次数
        Instant start; // 统计窗口的开始时间
        Instant blockedUntil = Instant.MIN; // 如果未被封锁则为 Instant.MIN
    }

    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();
    }

    // —————————————————————————— 登录

    // 剩余的封锁分钟数(0 = 允许尝试)
    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);
    }

    // 登录成功会重置该登录名的计数器
    public synchronized void loginSuccess(String ip, String login) {
        counters.remove(loginKey(ip, login));
    }

    // —————————————————————————— 注册

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

    // 一小时的窗口;一旦达到配额,就封锁到这一小时结束
    public synchronized void registrationSuccess(String ip) {
        count("registration|" + ip, maxRegistrations, ONE_HOUR, ONE_HOUR);
    }

与示例 27 中的 [LimiterService] 相比,该限制器保护两个操作(登录和账户创建),登录锁定作用于(IP 地址,登录名)这一对,并且阈值可在 [application.properties] 中配置。我们来说明这段代码:

  • 第 40–44 行:一个计数器:尝试次数、计数窗口的开始时间,以及锁定的结束时间([Instant.MIN],即可能的最早时间,表示没有锁定)。这是一个静态的私有嵌套类:它只为这个服务而存在。它是一个常规类,而不是 record:从字典中读取的计数器会被就地修改,而 record 不允许这样做;
  • 第 48 行:一个常规的 [HashMap],而不是 [ConcurrentHashMap]:统计一次尝试需要读取计数器、修改它,并可能替换它,而这一整个操作序列必须在不被其他请求打断的情况下执行。这就是关键字 [synchronized] (参见示例 27)的作用,它放在每个公有方法上:同一时间只有一个 [thread] 能执行该对象的某个 [synchronized] 方法;其他的则等待轮到自己;
  • 第 54–58 行:阈值,一次性从 [ProtectionProperties] record 中读取,该 record 为 [rdvmedecins.protection.*] 属性提供类型化形式:允许的登录失败次数(默认为 5)、封锁时长(15 分钟)以及每小时创建的账户数量(10);
  • 第 63–65 行:登录尝试的剩余锁定时间:两种可能的锁定时段中较长的那个,即(IP 地址,登录名)这一对的锁定时段与单独 IP 地址的锁定时段;
  • 第 67–70 行:一次失败的尝试会被计数两次。对于(IP 地址,登录名)这一对:使用同一个登录名的五次失败尝试会锁定该登录名,但仅限于该地址。对于单独的 IP 地址,阈值高五倍:尝试大量不同登录名的机器人同样会被封锁。在教室里,所有计算机通常通过同一个 IP 地址连接互联网:输错密码的学生不应该封锁他们的邻座,因此才按这一对来封锁;
  • 第 73–75 行:登录成功会重置该特定登录名的计数器(而不是 IP 地址的计数器);
  • 第 79–86 行:对于账户创建,只统计成功的尝试:同一个 IP 地址每小时最多创建十个账户。一旦达到配额,该地址会被封锁一小时。
    // —————————————————————————— 共用的机制
    // (私有方法总是由 synchronized 方法调用)

    private long remainingMinutes(String key) {
        Counter c = counters.get(key);
        if (c == null) {
            return 0;
        }
        Duration remaining = Duration.between(Instant.now(), c.blockedUntil);
        // 向上取整到分钟:剩余 30 秒的封锁 -> "1 分钟"
        return remaining.isNegative() || remaining.isZero() ? 0 : (remaining.toSeconds() + 59) / 60;
    }

    // 统计一次尝试;如果在窗口内达到阈值,则封锁
    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; // 封锁结束后,我们从零重新开始
            c.start = c.blockedUntil;
        }
    }

    // 我们忘记不再有用的计数器(既未被封锁,也不是最近的)
    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;
    }
}

我们来分解这段代码:

  • 第 4–12 行:剩余的封锁时间,向上取整到下一个整数:当剩下 20 秒时,显示的是剩余“1 分钟”,而不是“0 分钟”。[Duration.between] 测量两个时间点之间的时间差。这些私有方法不是 [synchronized]:它们总是由已经持有对象锁的公有方法调用;
  • 第 15–30 行:计数。未知的键,或者其计数窗口已过期的键,从一个新的计数器开始。达到阈值时,该键被锁定,锁定解除后计数将从零重新开始;
  • 第 33–39 行:清理不再需要的计数器(既未被锁定也不是最近的),仅当字典超过 1,000 个条目时才执行。[values()] 是字典的值的视图 :[removeIf] 从中移除计数器,相应的条目就会从字典中消失;
  • 第 41–47 行:生成字典的键。登录名会去除空格并转换为小写:[Admin] 和 [admin] 共用同一个计数器;机器人无法通过改变大小写来绕过封锁。[Locale.ROOT] 使转换与服务器的语言无关。

我们来看看封锁的效果。一个尝试用登录名 [robot] 登录、却无法读取图像的机器人,验证码会失败;每次失败都会被计数。第六次尝试时,(IP 地址,[robot])这一对被封锁,甚至不再检查验证码。下面是六次尝试中每一次在页面底部显示的消息:

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>

来自同一地址的其他登录名仍然可以使用。

11.13.9. auth/RegistrationPassService.java

// =========================================================================
// auth/RegistrationPassService.java
// -------------------------------------------------------------------------
// 账户创建的“通行令牌”。
//
// 要打开“创建客户账户”页面,必须先
// 抄对身份验证页面上的验证码(参见
// RegistrationController,POST /register/access)。然后服务器会签发
// 一个通行令牌:
//   - 一个随机标识符,存放在 HttpOnly Cookie 中;
//   - 有效期 15 分钟(足够填写表单,即使
//     在输入错误后多次尝试);
//   - 一旦创建了账户就被消费:一个已解答的验证码最多对应一个
//     账户。机器人无法批量创建账户。
//
// 没有有效的通行令牌时,GET 和 POST /register 会重定向到
// 身份验证页面:直接输入 URL /register 无法
// 绕过验证码。
//
// 与验证码一样,通行令牌存在于进程的内存中。
// =========================================================================
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 -> 过期日期
    private final Map<String, Instant> passes = new ConcurrentHashMap<>();

    // 签发一个新的通行令牌;返回其标识符
    public String issue() {
        purge();
        String id = UUID.randomUUID().toString();
        passes.put(id, Instant.now().plus(LIFETIME));
        return id;
    }

    // 如果 [id] 是一个存在且未过期的通行令牌,则为 true
    public boolean isValid(String id) {
        Instant expires = id == null ? null : passes.get(id);
        return expires != null && expires.isAfter(Instant.now());
    }

    // 通行令牌已被使用:我们忘记它
    public void consume(String id) {
        if (id != null) {
            passes.remove(id);
        }
    }

    // 浏览器只会向 /register... 地址发送该 Cookie
    public static ResponseCookie cookie(String id) {
        return ResponseCookie.from(COOKIE, id).httpOnly(true).sameSite("Lax").maxAge(LIFETIME)
                .path("/register").build();
    }

    // ……并通过再次设置它(内容为空、有效期为零)来清除它
    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();
        }
    }
}

你可以在登录页面创建客户账户,前提是已经解出验证码。注册表单是通过后续的请求显示和提交的:这些请求必须知道之前的某个请求已经成功解出了验证码。这就是令牌的作用,它由 [RegistrationController] 签发和验证(参见“Web 层:控制器”):

  • 第 36 行:承载令牌的 Cookie 的名称;
  • 第 38–42 行:令牌的有效期为十五分钟;待处理的令牌与验证码一样保存在内存中,并具有相同的时间上限;
  • 第 45–50 行:通行证是一个随机标识符,与其过期日期一起存储;控制器把它放在 Cookie 中;
  • 第 53–56 行:只有持有有效令牌,注册表单才会显示——并被接受。验证不会消耗令牌([get],而不是 [remove]):如果输入有误,用户可以多次重新提交表单;
  • 第 59–63 行:创建账户会用掉通行证:解出一个验证码,用户就有权创建一个账户,仅此而已;
  • 第 66–74 行:Cookie 及其删除。[path("/register")] 限制该 Cookie 只随以 [/register] 开头的 URL 请求一起发送:其他请求不会不必要地携带它。被删除的 Cookie 必须具有相同的路径;
  • 第 76–82 行:清理,与验证码的清理相同。

11.13.10. controllers/AuthController.java

登录页面控制器分成两段摘录来展示。

// =========================================================================
// controllers/AuthController.java
// -------------------------------------------------------------------------
// 登录的未受保护的路由:
//   GET  /        重定向到该角色的主页(或重定向到 /login)
//   GET  /login   显示登录表单(带有其验证码)
//   POST /login   检查尝试次数限制、验证码、登录名 / 密码
// (POST /logout,即登出,由 Spring Security 自己处理,
// 参见 config/SecurityConfig.java)
//
// 防范机器人,按以下顺序:
//   1. 该 IP 地址上该登录名最近失败次数过多?
//      -> 立即拒绝,甚至不看密码;
//   2. 验证码答案错误?-> 拒绝(算作一次失败);
//   3. 只有此后才检查密码。
// 对于在第 1 步或第 2 步被拒绝的尝试,我们绝不检查其
// 密码:因此机器人即使一再尝试也学不到任何东西。
// =========================================================================
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;
    }

    // 每个角色在登录后立即进入的主页
    public static String homePage(Role role) {
        return role == Role.USER ? "/my-area" : "/schedule";
    }

    // -----------------------------------------------------------------------
    // GET /
    // 该路由是公开的(参见 SecurityConfig):如果 Cookie 包含有效令牌,Spring Security 可能已经
    // 建立了用户,但
    // 并不要求这样。AuthService.currentUser() 告诉我们是否有用户(或为 null)。
    // -----------------------------------------------------------------------
    @GetMapping("/")
    public String home(HttpServletRequest request) {
        ConnectedUser user = authService.currentUser(request);
        return "redirect:" + (user != null ? homePage(user.role()) : "/login");
    }

    // -----------------------------------------------------------------------
    // GET /login[?login=xxx]:可选参数会预先填入
    // 登录名字段(在创建账户之后立即使用,参见 RegistrationController)
    // -----------------------------------------------------------------------
    @GetMapping("/login")
    public String showLogin(@RequestParam(required = false) String login, HttpServletRequest request,
            Model model) {
        // 已经登录(令牌仍然有效):直接进入主页
        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
    // 操作的参数由同名的表单字段填充。
    // required = false:缺失的字段得到 null(而不是
    // 400 错误)——由代码决定如何处理它。
    // -----------------------------------------------------------------------

我们来说明这段代码:

  • 第 11–17 行:执行登录检查的顺序很重要。因锁定或验证码不正确而被拒绝的尝试,其密码绝不会被验证:持续攻击的机器人什么也学不到;
  • 第 41–52 行:[@Controller] 把该类变成动作返回视图名称的控制器(参见示例 13)。它通过构造函数接收所需的三个服务。没有 [@PreAuthorize] 注解:它的页面是公开的(参见 [SecurityConfig]);
  • 第 55–57 行:主页取决于角色:患者是“我的区域”,其他人是日历。该方法是静态的:它不依赖于对象的任何字段;
  • 第 65–69 行:站点根路径重定向(前缀 [redirect:],参见示例 04)到该角色的主页或登录页面。该路由是公开的,但资源服务器过滤器会对所有请求运行:如果 Cookie 中包含有效令牌,用户就已通过身份验证,即使在这里也是如此;[authService.currentUser] 返回该用户,或者返回 [null];
  • 第 75–85 行:已经登录的用户会被重定向到他们的主页。可选参数 [login] 来自 URL([@RequestParam(required = false)],参见示例 07),在账户创建之后预先填写该字段。[substring] 最多保留前三十个字符:来自请求的数据绝不会在不采取预防措施的情况下使用。
    @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. 最近失败次数过多?
        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. 验证码
        if (!captchaService.verify(captchaId, captcha)) {
            limiter.loginFailure(ip, login);
            return form(model, login, Message.of("ERRORS.WRONG_CAPTCHA"));
        }

        // 3. 密码
        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());
    }

    // 访问者的 IP 地址。在反向代理(nginx 等)后面,
    // 必须启用 server.forward-headers-strategy=native,才能得到
    // 访问者的地址,而不是代理的地址。
    public static String ipAddress(HttpServletRequest request) {
        return request.getRemoteAddr();
    }

    // 表单,始终带有新的验证码(每张图片只使用
    // 一次);我们再次显示输入的登录名,绝不显示密码
    private String form(Model model, String login, Message error) {
        model.addAttribute("model", new LoginModel("LOGIN.TITLE", error, login, captchaService.generate()));
        return "login";
    }
}

我们来分解这段代码:

  • 第 2–7 行:登录表单的字段(参见示例 11),包括通过隐藏字段传递的验证码 ID 以及用户的输入。它们全都是可选的([required = false]):缺失的字段会得到 [null] 而不是 400 错误,由动作来决定如何处理它。该动作还接收请求(用于 IP 地址和验证码)、响应(用来在其中存放令牌 Cookie)以及视图模板;
  • 第 8–9 行:缺失的用户名变成去除空格的空字符串;缺失的密码变成空字符串;
  • 第 13–17 行:1. 被封锁的一对甚至不会被处理:既不检查验证码,也不检查密码。错误是一条待翻译的消息(record [Message],文件夹 [models]):一个翻译键和一个参数——需要等待的分钟数。[Map.of] 创建一个只读字典;
  • 第 20–23 行:2. 验证码。不正确的验证码算作一次失败(参见示例 27);
  • 第 26–32 行:3. 然后才是密码。空的用户名或密码不会进行计算开销很大的 [bcrypt] 计算:直接使用空盒子([Optional.empty()])。用户名未知或密码不正确:给出相同的消息,有意含糊其辞(参见示例 25),并再记一次失败;
  • 第 34–36 行:成功:计数器重置为零,令牌存储在 Cookie 中,重定向到该角色的主页。[user.get()] 从盒子中取出账户,我们知道它不为空;
  • 第 42–44 行:客户端的 IP 地址,由网络连接提供。该方法是公有且静态的:[RegistrationController] 和 [PatientAreaController] 也把它用于速率限制器。在中间服务器(反向代理,例如 [nginx])之后,这个地址将是代理的地址:注释指出,在这种情况下应启用 [Spring Boot] 的相应属性;
  • 第 48–51 行:登录页面,它总是显示新的 验证码:每张图像只使用一次。它的模板,即 record [LoginModel] (文件夹 [models]),包含页面标题的翻译键、任何错误消息、输入的用户名(绝不包含密码)以及验证码。它以名称 [model] 存储在模板中,这是应用程序中所有视图使用的名称。视图是 [login] (文件 [templates/login.html])。

对验证码不正确的尝试的处理可以用 [curl] 看到:返回登录页面(状态码 200),带有输入的用户名、一张新图像,以及页面底部的错误消息:

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>
...

响应中没有提到密码,因为它没有被检查。另一方面,成功的登录无法用 [curl] 展示,因为必须读取图像;它在浏览器中可见(参见“使用应用程序”):对 POST 的响应是重定向(302)到该角色的主页,并带有设置令牌的头 [Set-Cookie] 。

11.14. Web 层:共享服务

在讲到控制器和视图之前,先介绍它们的共同之处:翻译、所有视图共享的属性、闪现消息、异常处理、医生和客户列表的缓存、重新显示的表单的准备,以及一些工具函数。所有这些文件都在 [web] 文件夹中。它汇集了示例 15 到 24 中的大部分技术。

11.14.1. web/Translator.java

该文件分成两段摘录来展示。

// =========================================================================
// web/Translator.java
// -------------------------------------------------------------------------
// 界面的法语 / 英语翻译(参见示例 22)。
//
// 这些字典与该应用的 NestJS 和
// ASP.NET Core 版本所用的文件完全相同(i18n/fr.json、i18n/en.json),在启动时
// 只读取一次。
//
// 该 Bean 名为 [messageSource],并实现 Spring 的 MessageSource 接口:
// 因此 Thymeleaf 对视图中的表达式
// #{KEY} 使用的就是它。文本的参数({name}、{minutes} 等)
// 有两种传递方式:
//   #{AREA.HELLO('name', ${patient})}           按(名称, 值)对;
//   #{${message.key}(${message.params})}        按字典(Map)。
//
// 当前语言:由 LocaleResolver(参见 config/WebConfig.java)
// 在每个请求中根据 Cookie 确定。Spring 将其存放在
// LocaleContextHolder 中,并传给 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}:文本中的一个参数
    private static final Pattern PARAMETER = Pattern.compile("\\{(\\w+)\\}");

    // 语言 ->(完整键 "LOGIN.TITLE" -> 文本)
    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);
            }
        }
    }

    // 与 [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)
    //   -> 在该语言的字典中查找 "DOCTORS.ADDED",并
    //      将 {name} 替换为其值。所请求语言中缺失的键
    //      会在英语中查找;如果到处都没有,就显示键
    //      本身(这样疏漏会被立即发现)。
    // -----------------------------------------------------------------------
    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())));
    }

这是示例 22 中的翻译服务。字典 [i18n/fr.json] 和 [i18n/en.json] 与 [ASP.NET Core] 版本中的文件相同,在启动时只读取一次(参见“字典”)。我们来说明这段代码:

  • 第 40–41 行:该类实现了 [MessageSource] 接口,来自 [Spring],这是提供文本的服务的接口,并且该 Bean 被命名为 [messageSource]([@Component] 的参数)。[Spring] 正是用这个名称查找应用程序的 [MessageSource]:因此我们的 Bean 取代了 [Spring Boot] 本来会配置的那个,并且 [Thymeleaf] 针对视图中的每个 [#{KEY}] 表达式查询的就是这个 Bean(参见示例 22);
  • 第 43–44 行:支持的语言和默认语言。[List.of] 创建一个只读列表;
  • 第 47 行:一个正则表达式 ,用来识别文本中的参数:[{]、一个或多个单词字符([\w+],由括号捕获)、[}]。在 [Java] 字符串中,反斜杠写作 [\\]。该模式只编译一次([Pattern.compile]),然后重复使用;
  • 第 50 行:对每种语言,有一个“完整键 → 文本”的字典。该 Bean 是单例,被并发请求使用;然而,一个简单的 [HashMap] 就足够了,因为由构造函数填充的字典,此后只会被读取;
  • 第 52–61 行:构造函数读取两个 JSON 文件。[ClassPathResource] 指代“类路径”中的文件——类路径是虚拟机查找类的文件夹和归档的集合:[src/main/resources] 文件夹在编译期间会被复制到那里。[ObjectMapper] 是来自 [Jackson] 库的读写 JSON 的工具(版本 3,因此使用 [tools.jackson] 包)。[readTree] 返回 JSON 的文档树,[flatten] 方法再把它转换为字典。[try (...)] 结构会在块结束时关闭流,即使发生了异常。如果缺少某个文件,由 [IOException] 异常(由 [throws] 声明)阻止应用程序启动;
  • 第 64–67 行:与 [Locale] 对应的受支持语言,[Java] 对象用来描述一种语言以及(可选的)一个国家:[en_US] 得到 [en];不受管理的语言得到 [en];
  • 第 76–89 行:翻译。如果请求的语言的字典中缺少某个键,就到英语字典中查找;如果到处都缺失,就返回键本身([getOrDefault(key, key)]):遗漏会立即在屏幕上显现出来。文本的参数 [{name}] 随后被替换为它们的值(第 88 行):[replaceAll] 对找到的每个参数调用 lambda 函数;[r.group(1)] 是花括号之间捕获的名称,[r.group()] 是找到的整个文本,而 [{name}] 在没有提供值时保持原样。[Matcher.quoteReplacement] 会对字符 [$] 和 [\] 进行转义,否则它们对 [replaceAll] 具有特殊含义。
    // 由 Thymeleaf(或 Spring)传入的参数:单个
    // 字典,或(名称, 值)对
    @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());
            }
        }
    }

    // —————————————————————————— 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);
    }

    // 由多个可能的代码描述的消息(例如验证
    // 错误):字典中出现的第一个代码
    // 优先;否则使用默认消息,它本身就是一个键
    @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);
    }
}

我们来分析这段代码:

  • 第 5–18 行:消息的参数以对象数组([Object[]])的形式传入,有两种可能的方式。写成 [#{AREA.HELLO('name', ${patient})}] 的视图传入(名称, 值)对(第 14–16 行)。显示闪现消息或错误的视图写成 [#{${message.key}(${message.params})}]:它传入单个参数,即参数字典(第 10–13 行)。[instanceof Map<?, ?> dictionary] 检查类型,并将转换后的对象存入变量 [dictionary];[<?, ?>] 表示“任意类型的键和值”。[String.valueOf] 将任意对象转换为文本;
  • 第 21–30 行:JSON 的扁平化:[{ "LOGIN": { "TITLE": "Login" } }] 变为 [{ "LOGIN.TITLE": "Login" }]。该方法是递归的:它对每个嵌套对象调用自身,并扩展键前缀;
  • 第 34–42 行:[MessageSource] 接口的两个主要方法:代码(键)、其参数和语言。[@Override] 指示编译器验证该方法确实重新定义了接口的某个方法。第一个方法提供的默认消息会被忽略:缺失的键将原样显示;
  • 第 47–57 行:第三个方法接收由多个可能的代码描述的消息,例如由 [Spring] 针对验证或转换错误生成的代码([typeMismatch.version]、[typeMismatch]……)。在字典中找到的第一个代码优先;否则翻译默认消息。在本应用中,验证约束消息就是翻译键(参见 [models/Forms.java]):因此默认消息本身就是一个键。

请求的语言不会出现在控制器的任何地方:它由 [LocaleResolver] ([localeResolver] Bean,位于 [config/WebConfig.java],参见“项目配置”)在每次请求开始时从 [rdvmedecins_language] Cookie 中读取;[Spring] 再将其传给 [Thymeleaf],后者再将其传给 [getMessage]。

11.14.2. web/CommonModel.java

// =========================================================================
// web/CommonModel.java
// -------------------------------------------------------------------------
// 所有视图都需要的内容,无论是哪个页面(参见示例
// 15):@ControllerAdvice 使该类成为所有
// 控制器的补充,而每个 @ModelAttribute 方法在每个
// 操作之前执行,向视图的模型添加一个属性:
//   - user     :已连接的用户(或 null),用于导航栏;
//   - language :"fr" 或 "en";
//   - path     :所请求的 URL(导航栏的当前菜单、
//                验证码的“换一张图片”链接)。
// 闪现消息由 Spring MVC 自己添加到模型中,
// 名称为 [flash](参见 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:请求的语言,由 Spring 提供(参见 config/WebConfig.java)
    @ModelAttribute("language")
    public String language(Locale locale) {
        return Translator.language(locale);
    }

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

所有页面都显示相同的导航栏:已登录用户的姓名、按其角色显示的菜单、高亮显示的当前所选菜单,以及 FR / EN 按钮。因此,每个视图的模板都必须包含用户、语言和所请求的 URL。我们不在每个操作中逐一添加,而是一劳永逸地添加一次,如示例 15 所示:

  • 第 26 行:[@ControllerAdvice] 使该类成为所有控制器的组件(参见示例 15 和 24);
  • 第 35–38 行:名为 [@ModelAttribute("user")] 的方法在每个操作之前执行,其返回值以指定的名称添加到模板中。这里是已登录的用户,或者 [null],通过 [AuthService.currentUser] 获得(参见 [auth/AuthService.java]):导航栏 显示 [${user.name}], [${user.isAdmin()}]……与操作一样,这些方法接收其所需的参数——此处为请求;
  • 第 41–44 行:当前语言([fr] 或 [en]),用于页面的 [lang] 属性以及 FR / EN。[Locale] 类型的参数接收请求的语言,该语言由 [LocaleResolver] 设置;
  • 第 47–49 行:所请求 URL 的路径,例如 [/my-area]:导航栏会高亮显示路径以此开头的菜单(参见示例 16),验证码(CAPTCHA)中的“换一张图片”链接会重新加载当前页面。

闪现消息是第四项公共数据,不需要方法:[Spring MVC] 会自行将其添加到模板中(参见下文的 [CookieFlashMapManager.java])。在 [ASP.NET Core MVC] 中,这些数据是所有视图共享的父类的属性;[Thymeleaf] 没有视图的父类,而是由每个视图的模板接收这些数据。

11.14.3. web/FlashType.java

1
2
3
4
5
6
7
8
9
// =========================================================================
// web/FlashType.java - 闪现消息的两种类型(参见 Flash.java)
// =========================================================================
package rdvmedecins.web;

public enum FlashType {
    SUCCESS, // Bootstrap 类 alert-success:位于页面顶部
    DANGER // 错误:位于页面底部(参见 templates/fragments/errors.html)
}
  • 第 6–9 行:闪现消息的两种类型,以枚举的形式给出:枚举是其可能取值一次性固定下来的类型。成功消息显示在页面顶部(片段 [templates/fragments/flash.html]),错误消息显示在底部(片段 [templates/fragments/errors.html];参见“视图”)。

11.14.4. web/FlashMessage.java

// =========================================================================
// web/FlashMessage.java
// -------------------------------------------------------------------------
// 一条“闪现”消息:在下一个页面上只显示一次的消息
// (参见示例 20)。key:翻译键;params:其参数
// ({name}、{login} 等)。
// =========================================================================
package rdvmedecins.web;

import java.util.Map;

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

    // 闪现属性的名称,位于视图的模型中
    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;
    }
}
  • 第 12 行:闪现消息(参见示例 20)由类型、翻译键及其参数组成——而不是预先翻译好的文本——并将由下一个页面翻译为该页面的语言;
  • 第 15 行:传递消息所用的名称,视图在其模板中也以此名称找到它:[flash]。例如,控制器写成 [redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.success("SCHEDULE.CANCELLED"))];
  • 第 17–31 行:四个创建消息的静态方法,带参数或不带参数。名称相同但参数不同的方法称为重载:编译器根据实参选择正确的方法。[Map.of()] 是一个空字典;
  • 第 33–35 行:供视图使用的判断:[${flash.successful()}]。

11.14.5. web/CookieFlashMapManager.java

// =========================================================================
// web/CookieFlashMapManager.java
// -------------------------------------------------------------------------
// “闪现”消息:在下一个
// 页面上只显示一次的消息。它是“Post / Redirect / Get”模式的自然补充,
// 该模式被应用的所有表单使用:成功的 POST 不会
// 构建页面,而是重定向(302)到 GET 页面;消息
// 必须在重定向之后继续存在。
//
// Spring MVC 将其作为标准功能提供:控制器放入一个闪现属性
// (RedirectAttributes.addFlashAttribute,参见示例 20),它最终出现
// 在下一个请求的模型中,然后消失。默认情况下,Spring
// 将其保存在 HTTP 会话中(SessionFlashMapManager)。但我们的
// 服务器是无状态的:它在两个请求之间不保留任何东西(JWT
// 令牌在 Cookie 中)。因此我们用自己的实现取代 Spring 的“闪现属性
// 管理器”(FlashMapManager),它把闪现属性存储在
// Cookie 中——这就是 config/WebConfig.java 的 [flashMapManager] Bean。
//
// AbstractFlashMapManager 完成了大部分工作(消息
// 是为哪个请求准备的、过期等):剩下的只是读取和写入
// 闪现属性列表。我们只保留一个,以 JSON 文本形式
// 用 base64 编码(Cookie 不能包含任意字符)。
//
// 该 Cookie 既未加密也未签名:它只包含一个翻译
// 键及其参数,并以转义形式显示。修改它的
// 用户只会改变他自己看到的消息。
// =========================================================================
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";

    // Cookie 中包含的内容:消息所针对的页面、
    // 过期日期(以毫秒为单位)、消息
    private record CookieContent(String path, long expires, FlashMessage flash) {
    }

    private final ObjectMapper json = new ObjectMapper();

    // 上一个请求的闪现属性(null:没有)
    @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());
            // 一个可修改的列表:Spring 自行从中移除已被消费的消息
            // (List.of(...) 会给出不可修改的列表)
            return new ArrayList<>(List.of(flashMap));
        } catch (RuntimeException e) {
            return null; // 无法读取的 Cookie:我们忽略它
        }
    }

    // 要为后续请求保留的列表:为空 -> 我们清除 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());
    }
}

在示例 20 中,[Spring MVC] 的闪现属性在重定向与下一个页面之间保存在 HTTP 会话中:这是服务器上专属于每个浏览器的内存空间,由 [JSESSIONID] Cookie 标识。然而,我们的服务器是无状态的:它在两次请求之间不在内存中保留任何东西,因为用户由其令牌标识。因此,这个类将闪现属性存储在 Cookie 中,就像 [TempData] 在 [ASP.NET Core] 版本中所做的那样。我们来说明这段代码:

  • 第 46 行:[Spring MVC] 将闪现属性的存储委托给 [FlashMapManager] 类型的 Bean。[AbstractFlashMapManager] 完成了大部分工作:它知道闪现属性是为哪个请求准备的、何时过期以及何时已被消费。派生类只需实现两个方法:读取待处理闪现属性的列表(第 58–77 行)和保存该列表(第 80–94 行)。[flashMapManager] Bean(来自 [config/WebConfig.java] )创建该类的对象;它所用的名称正是 [Spring MVC] 查找此处理器时使用的名称,因此会取代 [Spring MVC] 自带的那个;
  • 第 52–53 行:Cookie 的内容:消息所针对页面的路径、其过期日期(以毫秒为单位)以及消息本身;
  • 第 55 行:[Jackson] 将对象转换为 JSON 文本,反之亦然,包括 record;
  • 第 58–77 行:解析过程,在每次请求开始时调用。Cookie 被解码(先 base64,再 JSON),消息被放回一个 [FlashMap] 对象中(一个闪现属性的字典,带有其目标路径和过期日期),它是列表中唯一的元素。返回的列表必须是可修改的(第 71–73 行):[Spring MVC] 在消费消息时会自行将其从列表中移除。无法读取的 Cookie(例如被手动修改过)不应导致页面失败:异常会被捕获,该 Cookie 被忽略;
  • 第 80–94 行:列表发生变化时调用的函数——消息已发布、已被消费或已过期。空列表会清除 Cookie;否则,将最后发布的消息写入 Cookie。放在条件中的表达式 [instanceof FlashMessage flash]检查属性的类型,并将其存入变量 [flash],该变量在第 88 行使用。JSON 文本以 Base64 编码([Base64.getUrlEncoder()],一种不含字符 [+] 和 [/] 的变体),因为 Cookie 不能包含任意字符;JSON 中的引号和重音字符是不允许的。该 Cookie 没有过期时间([Max-Age]):它是浏览器会话 Cookie,起作用的是内容的过期时间(默认三分钟);
  • 第 24–26 行:与 [TempData] 和 [ASP.NET Core] 中的 Cookie 不同,该 Cookie 既未加密也未签名。这没有必要:它只包含一个翻译键及其参数,视图会以转义形式显示它们;修改它的用户只会改变他自己看到的消息。

我们在 [SecurityConfig] 中看到,“会话已过期”消息就存储在这个 Cookie 中。下面是后续命令中所用 Cookie 的解码内容(它是在与上述测试不同的另一次测试中捕获的:仅过期日期不同):

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

下面这个发往 [/login] 的请求消费了该消息:页面显示它,响应则删除该 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>
...

消息只显示一次:重新加载页面时,页面不再显示它。

11.14.6. web/Flash.java

// =========================================================================
// web/Flash.java
// -------------------------------------------------------------------------
// 从任何地方放入闪现消息,包括在
// Spring MVC 之外:JWT 身份验证(会话过期,参见
// config/SecurityConfig.java)在 Spring Security 过滤器中运行,
// 早于 Spring MVC——那里还不存在 RedirectAttributes。
// 因此我们直接使用 FlashMapManager(CookieFlashMapManager)。
// 在控制器中,我们则更倾向于使用 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;
    }

    // 放入 [message],针对页面 [target](下一个请求)
    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);
    }
}

在控制器中,闪现消息通过 [RedirectAttributes.addFlashAttribute] 显示(参见示例 20)。而 [SecurityConfig] 的入口点则在 [Spring Security] 的过滤器中执行,早于 [Spring MVC] 接管请求:

  • 第 20 行:[@Component] 将该类转换为 Bean,[SecurityConfig] 将其作为参数接收;
  • 第 25–27 行:该 Bean 接收闪现属性处理器,即我们的 [CookieFlashMapManager];
  • 第 30–35 行:我们自己创建 [FlashMap]——通常由 [Spring MVC] 创建——其中包含消息以及应接收该消息的页面的路径([/login])。[saveOutputFlashMap] 将其传给处理器,由处理器把 Cookie 写入响应。

11.14.7. web/HtmlExceptionHandler.java

// =========================================================================
// web/HtmlExceptionHandler.java
// -------------------------------------------------------------------------
// 错误如何变成 HTML 页面。三种机制
// 分担这项工作(参见示例 24):
//
//   1. 这个类:InvalidSessionException(账户在登录之后
//      被删除)-> 返回登录页面;
//   2. 400、403 或 404 错误响应(控制器抛出的 ResponseStatusException、
//      角色不足、未知页面等)由服务器
//      传给 /error 地址:ErrorController 将其转换为页面;
//   3. 任何其他异常(真正的异常状况)会被写入
//      服务器日志,然后同样传给 /error:用户
//      看到的是 500 错误页面——绝不会看到调用栈。
// =========================================================================
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);
        // 后续重定向的闪现属性(相当于
        // RedirectAttributes.addFlashAttribute,用于 @ExceptionHandler 方法)
        RequestContextUtils.getOutputFlashMap(request)
                .put(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.SESSION_EXPIRED"));
        return "redirect:/login";
    }
    // 其他异常不在这里处理:它们向上传播
    // 到服务器,由服务器将其传给 /error(500 页面)
}

头部注释(第 4–14 行)描述了将错误转换为 HTML 页面的三种机制(参见示例 24)。其中两种不需要代码:错误响应([sendError(403)]、由控制器抛出的 [ResponseStatusException] 、未知的 URL)由服务器发送到地址 [/error],由 [ErrorController] 生成页面;未处理的异常会连同其调用栈记录在服务器日志中,然后同样转发到 [/error],由其显示 500 错误页面。用户永远看不到调用栈,因为它会帮助攻击者(属性 [spring.web.error.include-stacktrace=never];参见“项目配置”)。还剩下一种特殊情况,在此处理:

  • 第 27 行:[@ControllerAdvice],与 [CommonModel] 一样:该类的方法适用于所有控制器;
  • 第 30–31 行:当某个操作抛出指定的异常时,会调用带有 [@ExceptionHandler] 的方法(参见示例 24)。它可以接收请求和响应,并像操作一样返回视图名称或重定向;
  • 第 32–37 行:已登录用户的账户在其登录之后被删除了,尽管其令牌仍然有效(参见 [auth/InvalidSessionException.java])。我们清除令牌 Cookie,显示“会话已过期”的闪现消息,并重定向到登录页面:该用户被当作会话已过期来处理。带有 [@ExceptionHandler] 的方法不能接受名为 [RedirectAttributes] 的参数:[RequestContextUtils.getOutputFlashMap(request)] 直接返回重定向将传给下一个页面的 [FlashMap]。

11.14.8. web/ApplicationModel.java

该文件分为两个片段呈现。

// =========================================================================
// web/ApplicationModel.java
// -------------------------------------------------------------------------
// JSON 服务器中已有的缓存 / 外观(相当于原始 Spring 项目的
// [ApplicationModel] 类):医生和客户的列表
// 在启动时读取一次,之后
// 从内存中提供。
//
// 这些列表可能发生变化(ADMIN 添加、编辑、删除
// 医生和客户):因此每次写入都要经过这个外观,
// 它会在写入之后立即重新加载相关的列表。这正是业务层只有
// 唯一入口点的全部意义:“写入 =>
// 重新加载缓存”这条规则只写在这里。
//
// 该外观是单例 Bean,与业务层本身一样:在
// Spring 中,DAO 和业务层不依赖任何请求(是
// Spring 为每个线程关联其事务和其连接)。
// 因此缓存和外观可以是同一个对象。
//
// Spring 在多个线程上并行处理请求。因此我们绝不
// 就地修改列表:而是用一个新列表完全替换它。
// 替换引用是原子的;"volatile" 保证
// 所有线程都立即看到新列表。
// =========================================================================
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;

// 与业务层(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();

    // 有两个 Bean 实现了 Business:BusinessService 和 ApplicationModel
    // 本身。@Qualifier 按名称指定我们想要的那一个。
    public ApplicationModel(@Qualifier("businessService") Business business) {
        this.business = business;
    }

    // -----------------------------------------------------------------------
    // 两个列表的初始加载。@PostConstruct:在对象创建并注入其依赖之后,
    // 于应用启动期间,由 Spring 调用
    // 该方法。读取错误不会被捕获:
    // 它会停止服务器,而不是让服务器带着“空”列表启动(无法
    // 访问的数据库会让它更早停止,即在 Hibernate 启动时)。
    // -----------------------------------------------------------------------
    @PostConstruct
    public void load() {
        reloadDoctors();
        reloadClients();
    }

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

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

    // —————————————————————————— 从缓存读取

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

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

    // 用户账户为 [userId] 的医生——用于为已连接的医生预先选中
    // 其自己的日程
    public Optional<Doctor> getDoctorByUserId(int userId) {
        return doctors.stream().filter(d -> Objects.equals(d.getUserId(), userId)).findFirst();
    }

医生列表和客户列表几乎在每个页面上都会显示(日历中的下拉列表、管理页面)。我们不在每次请求时都从数据库中检索它们,而是将它们保存在内存中:这是应用作用域的数据(参见示例 23)。我们来说明这段代码:

  • 第 45–46 行:该类是一个单例 Bean,实现了 [Business] 接口,即业务层接口(参见“业务层”):对控制器而言,这个类就是业务层,也是它们唯一接收的业务层(例如 [public ScheduleController(ApplicationModel application)])。它是一个外观:一个隐藏其背后细节的单一入口点。在 [ASP.NET Core] 中,缓存必须是与外观分离的服务,因为业务层在那里只在一次请求期间存在;而使用 [Spring] 时,业务层本身就是单例(是 [Spring] 将每个 [thread] 与其事务和数据库连接关联起来):一个对象就够了(第 15–18 行);
  • 第 48 行:真正的业务层 [BusinessService],外观把请求转发给它;
  • 第 50–51 行:缓存本身:两个列表,最初为空([List.of()])。[Spring] 在多个 [threads] 实例上并行处理请求。因此,共享列表绝不能在另一个请求正在遍历它时被修改。所选的规则很简单:永远不要修改列表;而是用一个新列表替换它。替换引用只需一次操作,而关键字 [volatile] 确保所有 [threads] 实例立即看到新列表;没有它,某个 [thread] 可能会继续读取存放在其处理器缓存中的旧值;
  • 第 55–57 行:有两个 Bean 属于 [Business] 类型:[BusinessService] 和 [ApplicationModel] 本身。单纯请求“一个 [Business]”会有歧义,[Spring] 会拒绝启动。[@Qualifier("businessService")] 按名称指向所需的 Bean;由 [@Service] 声明的 Bean 默认以其类名命名,首字母小写;
  • 第 66–70 行:两个列表的初始加载。[@PostConstruct] 在对象创建并注入其依赖之后,通过 [Spring] 调用该方法,发生在应用启动期间、服务器接受任何请求之前。读取错误不会被捕获:它会终止应用,这比让服务器带着空列表启动要好(顺带一提,数据库无法访问时,应用会更早终止,即在 [Hibernate] 启动时;参见“安装与运行”);
  • 第 72–78 行:重新加载列表:整个列表从数据库中读取,并替换缓存中的列表。[List.copyOf] 创建该列表的只读副本;
  • 第 82–90 行:列表从内存中提供。返回的列表就是缓存本身的那个列表:由于它是只读的,调用者若试图向其中添加元素,会触发异常,因此缓存不会被意外修改;
  • 第 94–96 行:与某个账户关联的医生,从缓存中获取:已登录的医生可以立即看到自己的日程。对医生流进行过滤([filter]),[findFirst] 在 [Optional] 中返回选中的第一位医生,若无合适者则该 Optional 为空。[getUserId()] 返回一个 [Integer] (对象),而 [userId] 是一个 [int]:[Objects.equals] 可以安全地比较这两个值,即使 [Integer] 等于 [null]。
    // —————————————————————————— 简单的委托

    @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);
    }

    // 这里没有缓存:重要的是最新的数据(刚刚编辑或删除了
    // 自己账户的患者)
    @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);
    }

    // —————————————————————————— 写入 => 重新加载

    @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();
    }
}

我们来说明这段代码:

  • 第 3–58 行:其他请求原样传递给业务层;
  • 第 38–43 行:账户持有人有意不从缓存中查找;刚刚修改或删除了自己账户的患者,必须以其在数据库中的实际状态来呈现;
  • 第 60–101 行:任何涉及医生或客户的写操作之后,都会重新加载相关的列表。由于该 Bean 是控制器访问业务层的唯一入口点,“写入 = 重新加载缓存”这条规则只在这里实现,缓存因此不会变得过时。如果业务层拒绝该操作([BusinessException]),异常会在缓存重新加载之前终止该方法,因为这一步已不再必要。

11.14.9. web/Validation.java

// =========================================================================
// web/Validation.java
// -------------------------------------------------------------------------
// 重新显示被拒绝的表单所需的内容:逐字段的输入错误,
// 以及要用红色框出的字段。
// =========================================================================
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(由 Spring 在表单的绑定和验证
    // 期间填充) -> 字典 字段 -> 消息键,
    // 每个字段只保留第一条消息:{ "lastName": "ERRORS.LASTNAME_REQUIRED", ... }
    //
    // 转换错误(在应为数字的地方出现文本:
    // version="abc")的代码为 "typeMismatch",带有英文的技术消息:
    // 我们将其替换为键 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;
    }

    // -----------------------------------------------------------------------
    // 每个“输入”业务错误所涉及的表单字段
    // (重复项):它们以红色框出,消息显示在页面底部
    // -----------------------------------------------------------------------
    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"));

    // 要(重新)显示的表单的状态:被验证拒绝的每个字段下方的消息
    // (errors),以及要以红色框出的字段,
    // 即这些字段外加可能的其他字段(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);
    }

    // 页面的那条错误消息,显示在页面底部:如果有 [error] 则为它,
    // 否则,如果存在字段错误,则为“表单包含错误。”,
    // 否则什么也没有
    public static Message pageMessage(Map<String, String> errors, Message error) {
        if (error != null) {
            return error;
        }
        return errors.isEmpty() ? null : Message.of("ERRORS.INVALID_FORM");
    }
}

当表单被拒绝时,页面会重新显示,保留已输入的数据,在每个无效字段下方显示一条消息,将无效字段以红色高亮显示,并在页面底部显示一条消息。这个类为控制器准备这些信息:

  • 第 22–25 行:一个工具类:[final] (不能被继承)、一个私有构造函数(不能创建该类的对象),并且只有静态方法;
  • 第 36–45 行:将 [BindingResult] (参见示例 09 和 19)——由 [Spring] 在表单绑定和验证期间填充——转换为简单的“字段 → 消息键”字典。[putIfAbsent] 仅当字段尚无条目时才添加:每个字段只保留第一条消息,字段下方也只显示一条消息。验证约束消息是翻译键(参见 [models/Forms.java]);而转换错误([isBindingFailure()]:在应为数字的地方出现了文本)则带有英文的技术消息,会被键 [ERRORS.INVALID_FORM] 替换;
  • 第 51–54 行:业务层的某些错误与特定字段有关:已被占用的用户名,或姓名相同的医生或客户。这些字段将以红色高亮显示,消息显示在页面底部。[Map.of] 以单个表达式生成字典;
  • 第 59–65 行:待显示表单的状态:字段下方的消息,以及要以红色高亮显示的字段——即带有消息的字段——再加上 [otherFields] 字段(指示业务错误的字段)。[HashSet] 是一个集合:每个元素只出现一次。结果是一个 [FormState] record(参见 [models/ViewModels.java]);
  • 第 70–75 行:页面底部的消息:若有特定的错误消息,则为该消息;否则,若存在字段错误,则为消息“表单包含错误”;否则什么也没有([null])。

11.14.10. web/Utils.java

// =========================================================================
// web/Utils.java
// -------------------------------------------------------------------------
// Web 层的小型工具函数:
//   - 标签:"Mme Alice DURAND";
//   - 日期:"yyyy-MM-dd",时间 "8:05",日 "Wednesday 23 September 2026";
//   - 输入:读取浏览器发送的正整数;
//   - 患者:已连接用户对应的患者(Client 实体)。
//
// 一个“工具”类:只有静态方法,我们从不创建
// 该类的对象(私有构造函数)。
// =========================================================================
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() {
    }

    // —————————————————————————— 标签

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

    // —————————————————————————— 日期

    // URL 中以及 <input type="date"> 字段中日期的格式;
    // STRICT:"2026-02-30" 会被拒绝(而不是被调整为 3 月 2 日)
    private static final DateTimeFormatter ISO = DateTimeFormatter.ofPattern("uuuu-MM-dd")
            .withResolverStyle(ResolverStyle.STRICT);

    // 日期,如果 [text] 是 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" 而不是 "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",取决于
    // 请求的语言
    public static String formatDay(LocalDate day, Locale language) {
        return day.format(DateTimeFormatter.ofPattern("EEEE d MMMM yyyy", language));
    }

    // —————————————————————————— 输入

    // "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;
    }

    // —————————————————————————— 用户

    // 由请求的令牌所描述的用户(操作的参数
    // @AuthenticationPrincipal Jwt token)。有效但
    // 不完整(缺少 claims)的令牌会被视为会话已过期。
    public static ConnectedUser user(Jwt token) {
        ConnectedUser user = ConnectedUser.of(token);
        if (user == null) {
            throw new InvalidSessionException();
        }
        return user;
    }

    // —————————————————————————— 患者

    // -----------------------------------------------------------------------
    // 与已连接用户对应的患者(Client 实体)。
    //
    // JWT 令牌只包含账户的 id(users.id)。对于角色
    // USER,我们借助 clients.user 列找到对应的客户。
    //
    // 如果没有对应的客户,说明该账户在登录之后
    // 已被删除,而其令牌仍然有效:我们将其视为
    // 会话已过期(参见 InvalidSessionException)。
    // -----------------------------------------------------------------------
    public static Client connectedPatient(ApplicationModel application, ConnectedUser user) {
        if (user == null) {
            throw new InvalidSessionException();
        }
        return application.getClientByUserId(user.userId()).orElseThrow(InvalidSessionException::new);
    }
}

我们来说明这段代码:

  • 第 38–40 行:医生或客户的姓名:“Mme Alice DURAND”。参数的类型为 [Person],即实体 [Doctor] 和 [Client] 的父类(参见“实体”):同一个函数同时用于两者;
  • 第 46–47 行:URL 实体以及 [<input type="date">] 字段中的日期格式。[STRICT] 模式会拒绝不存在的日期:[2026-02-30] 是错误,而不是被转换为 3 月 2 日(参见示例 12)。在此模式下,年份写作 [uuuu]:[yyyy] 指的是“纪元内的”年份,这就需要同时指明纪元(公元前或公元后);
  • 第 50–56 行:如果文本是格式为 [yyyy-MM-dd] 的有效日期,则返回该日期;否则为空。格式为 [null] 的文本会触发 [NullPointerException],它被当作拼写错误的日期而被拦截:格式 [catch (A | B e)] 可拦截两种类型的异常;
  • 第 58–60 行:反向操作:将日期转换为文本 [yyyy-MM-dd];
  • 第 63–69 行:格式为 [8:05] 的时间([%02d] 格式将整数写成至少两位,不足补零),以及时间段的时间:[8:00 - 8:20];
  • 第 73–75 行:以请求的语言完整拼写的日期(星期几),控制器通过参数([Locale])接收该语言:“mercredi 23 septembre 2026”或“Wednesday 23 September 2026”。[EEEE] 是完整拼写的星期几,[MMMM] 是月份;
  • 第 80–86 行:浏览器发送的标识符(在 URL 或表单字段中):严格为正的整数,或 [null]。正则表达式 [\d{1,9}] 只接受最多九位数字:不接受符号、空格,也不接受对 [int] 来说过大的数。这样控制器只需测试 [null];
  • 第 93–99 行:由请求令牌标识的用户,操作通过名为 [@AuthenticationPrincipal Jwt token] 的参数接收它。签名正确但内容不完整的令牌会被视为会话已过期;
  • 第 113–118 行:与已登录用户关联的患者(实体 [Client])。JWT 令牌只包含账户 ID;我们要查找与该账户关联的客户。如果它已不存在,就意味着该账户在用户登录之后被删除了:[InvalidSessionException] 将由 [HtmlExceptionHandler] 处理,如上所述,它会重定向到登录页面。[orElseThrow] 让客户退出其 [Optional] 会话,或者在 [Optional] 为空时抛出其参数所生成的异常。[InvalidSessionException::new] 是一个构造函数引用:即 lambda [() -> new InvalidSessionException()] 的简写形式。

11.15. 表单与视图模型

有两类类在浏览器、控制器和视图之间传递数据:表单,由模型绑定根据浏览器发送的内容填充,然后进行验证;以及视图模型,由控制器为视图准备。前者是 JavaBean,后者是 record;我们稍后会看到原因。它们存放在 [models] 文件夹中,同时还有它们共用的输入验证规则。

11.15.1. models/InputRules.java

// =========================================================================
// models/InputRules.java
// -------------------------------------------------------------------------
// "人员"表单共用的输入规则。
// =========================================================================
package rdvmedecins.models;

import java.util.List;

public final class InputRules {

    private InputRules() {
    }

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

    // 登录名:小写字母、数字、点、连字符、下划线——最多 30 个字符
    public static final String LOGIN_FORMAT = "^[a-z0-9._-]{1,30}$";

    // 患者所选密码的最小长度
    public static final int PASSWORD_MIN = 6;

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

    // 空字段 -> null;对于密码,我们不去除
    // 空格(它们可以是密码的一部分)
    public static String emptyToNull(String value) {
        return value == null || value.isEmpty() ? null : value;
    }
}
  • 第 15 行:可选的称谓。它们用于生成表单的下拉列表(参见下文的 [ViewModels.java]);
  • 第 18 行:用户名的格式,由正则表达式描述:1 到 30 个字符,由小写字母、数字、句点、下划线和连字符组成。[^] 和 [$] 分别表示文本的开头和结尾;
  • 第 21 行:患者所选密码的最小长度;
  • 第 18 行和第 21 行:这两个字段是常量:[static final],以程序中硬编码的值初始化。编译器知道它们的值,因此可以将它们用作注解的实参,例如 [@Size(min = InputRules.PASSWORD_MIN)]。列表 [TITLES] (第 15 行)则不然,它是在运行时创建的;
  • 第 24–26 行:清理输入:去除首尾空格,空字段或仅由空格组成的字段([isBlank()])变为 [null],即视为缺失;
  • 第 30–32 行:对于密码,空字段变为 [null],但空格会被保留:它们是密码的一部分。

11.15.2. models/Forms.java

该文件分为两个片段呈现。

// =========================================================================
// models/Forms.java
// -------------------------------------------------------------------------
// “人员”表单的字段及其约束。三种
// 表单共用相同的身份字段(称谓、名、姓):
//
//   PersonFields                  称谓、名、姓
//    ├─ PersonForm                + 可选的登录名 / 密码、版本
//    │                              (ADMIN 添加或编辑医生 / 客户)
//    ├─ RegistrationForm          + 必填的登录名 / 密码 / 确认密码
//    │                              (患者创建其账户)
//    └─ MyAccountForm             + 登录名、可选的新密码、
//                                   必填的当前密码、版本
//                                   (患者编辑其账户)
//
// 模型绑定:当控制器操作接收到其中某个类的参数时,
// Spring MVC 会创建该对象,并通过其 setter,用同名参数填充每个字段
// (参见示例 18)。
//
// 验证:使用 @Valid,Spring 随后检查约束
// (@NotBlank、@Size 等),并把错误存入紧跟在参数之后的 BindingResult 中
// (参见示例 09 和 19)。
//
// 错误消息是翻译键(参见 i18n/*.json)。
//
// 输入清理:setter 会去除多余的空格
// (空输入变为 null),并将登录名转为小写。而
// 密码则不会被“清理”(空格可以是密码的一部分)。
//
// 这些类是 Forms 类中的“嵌套”(static)类:四个小类
// 放在同一个文件中。它们被称为
// 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() {
    }

    // —————————————————————————— 公共基类
    public abstract static class PersonFields {

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

        // 最大长度 = 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); }
    }

头部注释(第 4–32 行)描述了三种“人员”表单及其公共基类。这些表单遵循示例 18 和 19 中使用的方法:操作接收一个带有 [@Valid] 注解的参数,后面紧跟一个 [BindingResult] 参数。[Spring MVC] 创建该对象,用接收到的字段填充它(模型绑定),然后检查注解所设定的约束(验证),并将所有错误存入 [BindingResult]。这些注解([@NotNull]、[@NotBlank]、[@Size]、[@Pattern])属于 [Bean Validation] 标准(包 [jakarta.validation]),由 starter [spring-boot-starter-validation] 连同其实现 [Hibernate Validator] 一起引入。我们来说明这段代码:

  • 第 41–44 行:这个类的唯一目的是把四个小的嵌套类归入同一个文件。它们被声明为 [static],独立于 [Forms] 的任何实例:它们被引用为 [Forms.PersonForm],或者在 [PersonForm] 经过 [import] 之后直接写作该名称;
  • 第 47 行:身份字段,三种表单共用。该类是抽象的 ([abstract]):不能创建它的对象,只能从它派生;
  • 第 49–51 行:称谓,必填([@NotNull]),并从列表中选择([@Pattern])。这些值在正则表达式 [Mr|Mme|Melle] ([|] 表示“或”)中重复出现:注解的实参必须是常量,而列表 [InputRules.TITLES] 不是常量。[@Pattern] 要求整个文本与该表达式匹配;
  • 第 53–60 行:名和姓,必填,且长度不得超过 20 个字符:这是 SQL 的列宽(参见“数据库”)。[@NotBlank] 拒绝 [null]、空文本以及仅由空格组成的文本。每个约束都有自己的消息;这些消息是翻译键 (参见示例 22),由视图翻译为用户的语言;
  • 第 62–69 行:getter,每个写在一行上。setter 会随时清理输入:由于模型绑定在验证之前通过 setter 更新字段,因此被验证的是清理之后的值。由空格组成的名会变为 [null],并由 [@NotBlank] 拒绝它。

为什么用 JavaBean 而不是 record?JavaBean 是一个普通类,具有无参构造函数,并且每个属性都有一对 [getXxx()] 和 [setXxx()]。[Spring MVC] 创建空对象,然后对每个接收到的字段调用一次 setter:每个字段都是单独处理的。[Spring MVC] 也可以填充 record,但它是一次性用全部字段调用其构造函数:只要有一个字段无法转换(例如数值字段 [version] 中出现了文本),对象就不会被构造,也不会检查任何约束。使用 JavaBean 时,某个字段的转换错误不会妨碍其他字段的验证:用户可以一次看到所有错误。JavaBean 还允许在 setter 中清理输入。

    // —————————————————————————— ADMIN
    public static class PersonForm extends PersonFields {

        // 可选(参见 business/PersonData.java)
        @Pattern(regexp = InputRules.LOGIN_FORMAT, message = "ERRORS.INVALID_LOGIN")
        private String login;

        // 可选;最多 72 个字符(超过的部分 bcrypt 会忽略)
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        // 编辑表单的隐藏字段(乐观锁)。
        // Integer:缺失或为空的字段得到 null;不是
        // 数字的文本会产生绑定错误(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; }
    }

    // —————————————————————————— 患者注册
    public static class RegistrationForm extends PersonFields {

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

        // 两个 @Size 约束,各自带有其消息
        @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); }
    }

    // —————————————————————————— "管理我的账户"
    public static class MyAccountForm extends PersonFields {

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

        // 可选:为空 = 密码不变
        @Size(min = InputRules.PASSWORD_MIN, message = "ERRORS.PASSWORD_TOO_SHORT")
        @Size(max = 72, message = "ERRORS.PASSWORD_TOO_LONG")
        private String password;

        private String confirmation;

        // 当前密码,对账户的任何编辑都是必填的
        @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);
    }
}

我们来说明这段代码:

  • 第 2 行:来自 ADMIN 的表单,用于添加或修改医生或客户。该类继承了身份字段、它们的约束及其访问器;
  • 第 4–6 行:登录名,在此处是可选的 (若留空,创建时默认为小写的姓名,修改时保持不变;参见“业务层”),但如果提供,则必须格式正确。与 [Bean Validation] 中除 [@NotNull] 和 [@NotBlank] 之外的所有约束一样,[@Pattern] 接受值 [null]:这正是该字段可选的原因。setter(第 18 行)会清理登录名并将其转换为小写(方法 [lowerCase],第 89–91 行);
  • 第 8–10 行:密码,同样是可选的,最多 72 个字符:[bcrypt] 算法会忽略其后的字符。它不会被清理,只是在为空时被设为 [null] (第 21 行);
  • 第 12–15 行:记录的版本,位于更新表单的隐藏字段中(乐观锁;参见示例 28)。类型 [Integer]——而不是 [int]——接受值 [null]:缺失或为空的字段会得到 [null]。不是数字的文本会产生转换错误,[web/Validation.java] 会将其转换为消息“表单包含错误”;
  • 第 28 行:患者创建账户。登录名是必填的(第 30 行):[@NotNull] 就足够了,因为 setter 会将空输入转换为 [null];
  • 第 34–38 行:密码,必填,长度为 6 到 72 个字符。同一个字段上有两个注解 [@Size]:被声明为可重复的 注解可以出现多次,此处是为了让每个限制都有自己的消息;
  • 第 40–41 行:确认密码,必填。验证密码与其确认是否一致涉及两个字段:这由控制器检查([RegistrationController],参见“Web 层:控制器”);
  • 第 54 行:患者修改其账户。登录名是必填的;新密码是可选的(第 60–63 行):若留空,则保持不变,因此这里不需要其确认(第 65 行)。然而,当前密码对任何修改都是必填的(第 67–69 行),隐藏字段中的行程记录版本也是必填的(第 71 行);
  • 第 89–91 行:将用户名转换为小写。[Locale.ROOT] 使转换与服务器的语言无关(例如在土耳其语中,[I] 的小写形式不是 [i])。全名 [java.util.Locale] 避免了出现类似 [import] 的一行。

11.15.3. models/ViewModels.java

该文件分为两个片段呈现。

// =========================================================================
// models/ViewModels.java
// -------------------------------------------------------------------------
// “视图模型”:每个控制器以名称 [model] 传给其视图的
// 内容。它们是 record:不可变对象,
// 由控制器一次性构建,视图只是读取它们
// (${model.schedule.rows} 等)。
//
// 所有页面遵循的规则:视图中不含逻辑。
// 控制器准备好已经格式化的数据("Mme Marie
// PELISSIER"、"8:00 - 8:20"、selected = true 等),并已按
// 用户的角色过滤;视图只是把它们放入 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() {
    }

    // -------------------------------------------------------------------------
    // 所有页面的共同点,由布局读取
    // (templates/layout.html):页面标题的键,以及页面的那条错误
    // 消息,显示在页面底部(null:没有错误)
    // -------------------------------------------------------------------------
    public interface ViewModel {
        String pageTitle();

        Message error();
    }

    // 一条待翻译的消息:其键及其参数
    public record Message(String key, Map<String, String> params) {

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

    // 下拉列表的一个选项(医生、患者)
    public record OptionView(int id, String label, boolean selected) {
    }

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

    // —————————————————————————— 日程
    public record ScheduleRowView(
            int slotId,
            String time, // "8:00 - 8:20"
            boolean free,
            String patient, // 已预订时间段显示的姓名;null = "已预订"
            boolean mine, // 已连接患者的预约
            boolean bookable, // 是否显示“预订”按钮?
            String bookUrl,
            Integer appointmentId) { // 仅在显示“取消”按钮时才填充
    }

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

    public record BookingView(
            int slotId,
            String time,
            List<OptionView> clients, // ADMIN / DOCTOR:可供选择的患者
            String patient) { // USER:患者就是其本人
    }

    public record ScheduleModel(
            String pageTitle,
            Message error,
            List<OptionView> doctors,
            Integer doctorId,
            String day, // "yyyy-MM-dd"
            ScheduleView schedule,
            BookingView booking,
            String backUrl, // 所显示的日程,不含预订对话框
            // 已有即将到来预约的患者:解释
            // 为什么没有“预订”按钮的消息
            String info) implements ViewModel {
    }

视图模型遵循示例中已经应用的一条规则:视图中不含逻辑。控制器准备好已经格式化(“Mme Marie PELISSIER”、“8:00 – 8:20”)并已按用户角色过滤的数据;视图只是把它们放入 HTML。这些是 record:由控制器构造一次,之后只由视图读取,视图例如写成 [${model.schedule.rows}];[Thymeleaf] 随后调用访问器 [schedule()],接着是 [rows()]。每个控制器都以名称 [model] 存储其视图的模型。我们来说明这段代码:

  • 第 32–36 行:所有页面的共同点,由模板 [templates/layout.html] 读取(参见“视图”):页面标题的翻译键,以及页面的错误消息(显示在底部),或者 [null]。这是一个接口,而不是父类:record 不能继承类,但可以实现接口。具有组件 [pageTitle] 和 [error] 的 record 会自动拥有访问器 [pageTitle()] 和 [error()]:它无需任何额外代码就实现了该接口;
  • 第 39–44 行:一条待翻译的消息:其键和参数。静态方法 [of] 创建不带参数的消息;
  • 第 47–48 行:下拉列表中的一个选项(医生、患者),已标记为选中或未选中(参见示例 18);
  • 第 51–52 行:登录页面:已输入的用户名和要显示的验证码(CAPTCHA)。record 的主体为空:一切都在其组件中;
  • 第 55–64 行:日历中的一个条目,即一个时间段。控制器已经确定了一切:是否显示患者的姓名(患者看不到其他人的姓名:此时 [patient] 等于 [null],视图显示“已预订”)、是否显示“预订”按钮,以及是否显示“取消”按钮([appointmentId] 已填入时显示)。[appointmentId] 是一个 [Integer],它可能等于 [null];
  • 第 66–67 行:医生某一天的日程:医生、完整拼写的日期,以及各行;
  • 第 69–74 行:预约窗口:对 ADMIN 和医生而言是患者列表,对单个患者而言则只是已登录患者的姓名;
  • 第 76–88 行:预约日历页面:医生列表、所选的医生和日期、预约日历(在未选择医生时为 [null] )、预订窗口(如适用)、不带该窗口的预约日历 URL(第 84 行),以及向患者说明其为何无法预订的消息。
    // —————————————————————————— “人员”表单

    // 表单字段中显示的值(绝不包括密码)
    public record PersonValues(String title, String firstName, String lastName, String login, Integer version) {

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

    // 被拒绝的表单的状态:显示在每个字段下方的消息
    // (字段 -> 消息键),以及要以红色框出的字段(Bootstrap
    // 类 is-invalid):即有消息的字段,外加可能的其他字段
    // (名 + 姓重复、登录名已被占用等)
    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" : "";
        }
    }

    // 称谓列表的一个选项
    public record TitleOption(String value, boolean selected) {
    }

    // 公共片段 person-fields.html 所使用的内容(称谓、名、姓)
    public interface FormView extends ViewModel {
        PersonValues values();

        FormState state();

        // 一个“默认”方法:写在接口中,由 record 继承
        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:添加;false:编辑
            String action, // POST 的 URL
            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;
        }
    }

    // —————————————————————————— 医生 / 客户列表

    // 每种人员类型专用的翻译键
    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 {
    }

    // —————————————————————————— 患者专区
    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 {
    }

    // —————————————————————————— 错误页面
    public record ErrorModel(String pageTitle, Message error, int code, String message) implements ViewModel {
    }
}

我们来分析这段代码:

  • 第 4–9 行:“人员”表单字段中显示的值;绝不包括密码——密码不会回送到浏览器。[empty()] 提供添加表单的值;
  • 第 15–28 行:表单的状态,由 [web/Validation.java] 准备:字段下方的消息,以及要以红色高亮显示的字段。record 可以有方法:[errorOf] 返回字段的消息(或 [null]),[invalidClass] 返回 [Bootstrap] [is-invalid] 类(它会用红色框出字段)或空字符串。例如,视图写成 [th:classappend="${state.invalidClass('login')}"],其中 [state] 指 [model.state];
  • 第 31–32 行:称谓列表中的一个选项,并标记了选中项(参见示例 18);
  • 第 35–44 行:公共片段 [person-fields.html] 所使用的内容,该片段显示三种表单的称谓、名和姓字段:值和状态。一个接口可以继承另一个接口([extends ViewModel])。第 41–43 行:默认方法([default])是其代码直接写在接口内部的方法;实现该接口的类和 record 会继承它。这里是根据表单的值生成的称谓列表:称谓流被转换([map])为选项,而 [toList()] 将结果汇集成列表。三个表单模板都因此受益,而无需任何额外代码;
  • 第 46–54 行:ADMIN 表单,用于添加和修改条目(参见示例 28):模式、表单提交 URL,以及返回按钮所用的列表 URL;
  • 第 56–70 行:注册表单和账户管理表单;它们把密码最小长度传给视图,该值在字段的错误消息中用作参数 [{min}] ,在注册时还用于帮助文本。在 record 主体中写一个普通方法就足够了:视图写成 [${model.passwordMin()}];
  • 第 75–84 行:医生和客户的管理页面是相同的视图;只有其文本不同。这个 record 包含每种人员类型特有的翻译键;
  • 第 86–92 行:医生或客户列表中的一行,带有其“编辑”和“删除”按钮的地址,以及列表页面的模板;
  • 第 95–100 行:患者专区:其姓名和即将到来的预约,每个预约都带有指向当日日历的链接;
  • 第 103–104 行:错误页面:HTTP 代码和消息键。

11.16. Web 层:控制器

控制器是 Web 层的可见部分:每个控制器接收来自一组页面的请求,读取其参数,查询业务层(始终通过 [ApplicationModel] 服务),然后选择一个视图并向其传递模型,或者重定向请求。操作返回一个字符串:要么是视图的名称(["schedule"] 指文件 [templates/schedule.html];参见示例 13),要么是重定向(["redirect:/login"];参见示例 04)。视图模板始终是单个对象,即来自文件 [record] [models/ViewModels.java] 的 record,以名称 [model] 存放在 Spring 的 [Model] 中。所有 POST 表单都遵循 Post/Redirect/Get 模式(参见示例 20);所有消息都是翻译键,由视图翻译。登录控制器 [AuthController] 已与身份验证一起被注释掉。

11.16.1. controllers/LanguageController.java

// =========================================================================
// controllers/LanguageController.java
// -------------------------------------------------------------------------
// GET /language/fr、GET /language/en:导航栏的两个 FR / EN 按钮。
// 非受保护的路由:必须能够在登录之前更改
// 语言。
//
// 该选择被记在 CookieLocaleResolver 的 Cookie 中(参见
// config/WebConfig.java):在之后的每个请求中,Spring MVC 会将其读回
// 并设置请求的语言(操作的 Locale 参数、视图中 #{...} 消息的
// 语言)。然后我们回到
// 来源页面。
// =========================================================================
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)) {
            // -> 404 错误页面(参见 ErrorController)
            throw new ResponseStatusException(HttpStatus.NOT_FOUND);
        }
        // 设置语言 Cookie
        localeResolver.setLocale(request, response, Locale.of(language));
        return "redirect:" + originPage(request);
    }

    // -----------------------------------------------------------------------
    // 上一个页面,依据浏览器发送的 HTTP 头 "Referer"。
    // 我们只保留其路径(/schedule?...):如果重定向到
    // 请求所提供的完整地址,就有可能把
    // 用户送到另一个站点(所谓的“开放重定向”漏洞)。
    // -----------------------------------------------------------------------
    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/..." 会被浏览器理解为另一个站点上的
            // 地址:同样予以拒绝
            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 "/";
        }
    }
}

这大致就是示例 22 中的控制器:相同的路由 [/language/{language}],来自 [CookieLocaleResolver] 的相同 Cookie,通过头 [Referer] 返回原页面的方式也相同。我们来逐一说明:

  • 第 32 行:[@Controller] 将该类变为名为 MVC 的控制器,在启动时被检测到,并由 [Spring] 创建为 Bean (Spring 管理其创建、并可将其注入其他地方的对象,参见示例 06);
  • 第 35–39 行:控制器通过依赖注入接收 在 [LocaleResolver] [config/WebConfig.java] 中定义的 [@Autowired]。该类只有一个构造函数:Spring 调用它并提供所请求的 Bean,无需用 @Autowired 注解它。应用的所有控制器都是这样编写的;
  • 第 41–42 行:路由 [GET /language/{language}]。[@PathVariable] 将参数 [language] 映射到 URL 的段 [{language}] (参见示例 02)。该操作还接收服务器的请求和响应([Servlet]):只需将它们声明为参数,Spring MVC 就会提供它们;
  • 第 43–46 行:未知的语言([/language/de])返回 404 页面。该操作并不生成这个页面:它抛出 [ResponseStatusException],Spring MVC 将其转换为 404 错误响应;服务器随后将请求转发到 [/error],由(下文的)[ErrorController] 生成页面;
  • 第 48 行:[setLocale] 设置语言 Cookie(其名称 [rdvmedecins_language]、一年的有效期,以及其选项 [HttpOnly] 和 [SameSite=Lax] 均已在 [WebConfig] 中设定)。在之后的每次请求中,[CookieLocaleResolver] 都会读取该 Cookie 并设置请求的语言;
  • 第 49 行:返回上一个页面。前缀 [redirect:] 会让 Spring MVC 返回 302 响应;
  • 第 58–76 行:上一个页面,依据 [Referer] 头。我们只保留路径和参数([/schedule?doctorId=1&day=...]):重定向到请求所提供的完整 URL 可能会把用户送到另一个网站(这种漏洞称为“开放重定向”);
  • 第 68–71 行:以下情况会被拒绝,并返回站点根目录:相对地址、以 [//] 开头的路径(浏览器会将其解释为另一个站点的地址),以及名为 [/language/...] 的页面,它会使浏览器陷入循环。[getRawPath] 和 [getRawQuery] 会还原路径和参数在 URL 中出现时的样子,仍保持编码状态([%20]……),可直接重新插入 URL。

我们用 [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

Cookie 已设置,浏览器被重定向到登录页面,该页面现在将以英文显示。

11.16.2. controllers/ScheduleController.java

应用的主页面,也是功能最丰富的控制器。我们逐部分来分析。

11.16.2.1. 页面上的 URL 代码

// =========================================================================
// controllers/ScheduleController.java
// -------------------------------------------------------------------------
// 日程页面:选择医生和日期、该医生在
// 该日的日程、预约的预订和取消。
//
//   GET  /schedule?doctorId=1&day=2026-09-23               页面
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        同一页面,并
//                                                          打开
//                                                          时间段 7 的预订对话框
//   POST /schedule/book                                    创建预约
//   POST /schedule/cancel                                  取消预约
//
// 整个页面由其 URL 描述:可以重新加载,可以
// 加入书签,可以使用浏览器的“后退”按钮——而无需一行
// JavaScript。
//
// 每种角色能看到什么、能做什么:
//
//   | 角色          | 显示的已预订时间段                | 预订               | 取消    |
//   |===============|===================================|====================|=========|
//   | ADMIN, DOCTOR | 患者姓名                          | 为在列表中         | 是      |
//   |               |                                   | 选定的患者         |         |
//   | USER (患者)   | “已预订”,若是其本人的预约则        | 为自己,若         | 否 (*)  |
//   |               | 显示其本人的姓名                  | 没有即将到来       |         |
//   |               |                                   | 的预约             |         |
//
//   (*) 患者从其“我的专区”页面取消自己的预约。
//
// 保密性:对患者而言,其他患者的姓名并不是
// 简单地被视图隐藏——它们从未被放入传给视图的
// 模型中。因此发送到浏览器的 HTML 并不包含它们,
// 甚至不以隐藏形式包含(否则只需“查看页面源代码”就会暴露它们)。
//
// 不能在过去预订:“预订”按钮只出现在
// 今天及之后的日子(而且业务层反正也会
// 拒绝)。
//
// 安全性:所有 /schedule URL 都要求有已通过身份验证的用户
// (参见 SecurityConfig:anyRequest().authenticated())。操作上的 @PreAuthorize
// 额外要求具备所列角色之一。没有有效令牌:返回
// /login;角色不足: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 {

    // 控制器对用户所了解的信息,用于决定显示内容
    private record Rights(
            boolean manager, // ADMIN 或 DOCTOR
            Client patient, // 已连接的客户(角色 USER),否则为 null
            boolean patientCanBook) { // 没有即将到来预约的 USER
    }

    // 隐藏字段 doctorId / day,两个 POST 表单共用
    private record ScheduleRequest(int doctorId, LocalDate day) {
    }

    private final ApplicationModel application;

    public ScheduleController(ApplicationModel application) {
        this.application = application;
    }
  • 第 7–12 行:页面的路由。请注意,预订窗口不是由 [JavaScript] 打开的:它是 URL 的一个参数([book=7]),指示服务器在渲染页面时打开该窗口。因此,“预订”按钮只是一个链接。整个页面由其 URL 描述:你可以重新加载它、将其加入书签,或使用浏览器的“后退”按钮;
  • 第 20–28 行:每种角色能看到什么、能做什么。这张表是页面的“规格说明”:控制器的其余部分实现它;
  • 第 30–33 行:隐私规则,我们稍后会再谈到:其他患者的姓名不是由视图隐藏的;它们从未被发送到浏览器;
  • 第 39–42 行:安全性。该类没有安全注解:要求用户登录才能访问任何 [Spring Security] ([anyRequest().authenticated()],参见 [config/SecurityConfig.java])的配置是针对任何 [/schedule...] 地址的。另外还需要角色的操作用 [@PreAuthorize] 注解(参见示例 26);
  • 第 84–86 行:应用于类的 [@RequestMapping("/schedule")]是该控制器中所有路由的前缀(参见示例 02);
  • 第 88–93 行:控制器对已登录用户所了解的信息,每次请求计算一次(参见下文的 [rights] 方法)。这是一个 record (参见“领域:日历”),其访问器为 [rights.manager()], [rights.patient()]……这个 [record] 是私有的,并声明在类的内部:只有该类使用它。管理者 是 ADMIN 或 DOCTOR;[patient] 只对客户(角色 USER)填充;
  • 第 95–97 行:从页面上两个 POST 表单的隐藏字段中读取并转换后的医生姓名和日期;
  • 第 99–103 行:由构造函数接收的 [ApplicationModel] 服务(参见“Web 层:公共服务”)。

11.16.2.2. GET /schedule

    // -----------------------------------------------------------------------
    // GET /schedule
    // URL 参数按原始形式读取(request.getParameter),以便
    // 区分缺失的参数(null)与为空的参数(?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);

        // 日期:如果 URL 中的有效则用它,否则用今天
        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());

        // 医生:URL 中的那位;如果没有,对已连接的医生则是其本人
        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);
        }

        // 医生的下拉列表("final":可在 lambda 中使用)
        final Integer chosenId = doctorId;
        List<OptionView> doctors = application.getAllDoctors().stream()
                .map(d -> option(d, d.getId().equals(chosenId)))
                .toList();

        // 日程,如果已选择医生(且日期有效)
        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);
            }
        }
  • 第 7 行:不带路径的 [@GetMapping] :该操作响应 [GET /schedule],即控制器的前缀;
  • 第 8–9 行:操作的参数,全部由 Spring MVC 提供。[@AuthenticationPrincipal Jwt token] 是已登录用户的 [JWT] 令牌,已由 [Spring Security] 验证(参见“身份验证”);[request] 提供对 URL 原始参数的访问;[locale] 是请求的语言,由 [CookieLocaleResolver] 设置;[model] 是模板,由操作为视图填充。该操作不声明参数 [doctorId] 或 [day]:它自己从请求中读取它们([HttpServletRequest],参见示例 05):[request.getParameter] 对于[null] 缺失的参数返回 null,对于空参数([?doctorId=])则返回空字符串。这两种情况必须加以区分(见下文);
  • 第 11–12 行:已登录用户及其权限。[Utils.user] (文件夹 [web])读取令牌信息(claims:ID、登录名、姓名、角色)并将其转换为 [ConnectedUser] 对象;
  • 第 15–25 行:所请求的日期(如果有效);否则为今天。如果缺少 [day] 参数,则返回今天,且不产生错误消息。如果存在但无效([day=2026-02-30]),则会生成错误消息。[Utils.validDate] 返回一个 [Optional] (参见“DAO 层”),在用 [isPresent()] 测试之后,再用 [get()] 提取其值。预订只能从今天开始([dayBookable]);
  • 第 28–32 行:所请求的医生。[Utils.positiveInteger] 返回严格为正的整数,如果值缺失、为空或无效,则返回 [null] :其类型是 [Integer],即 [int] 类型的“对象”版本,它可以为 [null]。如果 URL 中[doctorId] 参数缺失,已登录的医生会看到自己的日程:这是他的主页。如果它为空([doctorId=],即列表中的“选择医生”选项),则不显示日历。第 31 行:[map(d -> d.getId())] 将 由 [Optional<Doctor>] [getDoctorByUserId] 返回的值转换为 [Optional<Integer>],而 [orElse(null)] 从中提取值,若为空则得到 [null] ;
  • 第 35–38 行:医生下拉列表的选项,从 [ApplicationModel] 的缓存中读取;所请求医生对应的选项被选中(参见文件末尾的 [option] 方法)。[stream()] 将列表转换为流,由 [map] 逐个元素处理,再由 [toList()] 转换回列表。[d -> option(...)] 是一个 lambda:就地定义的匿名函数。lambda 只有在局部变量不再被修改时才能使用它:这就是为什么在第 31 行被修改的 [doctorId] 在第 35 行被复制到一个 [final] (不可修改)变量中。在第 37 行,两个 [Integer] 值 由 [equals] 比较,它比较的是它们的值,而不是由 [==] 比较,后者比较的是两个对象:这是 [Java] 的经典陷阱;
  • 第 41–49 行:只有在选择了医生且日期有效时才计算日程。未知的医生 ID 会触发一条消息,而不是错误页面。由业务层计算的日历(来自 [domain] 文件夹的 [DoctorDaySchedule] 对象)由下文讨论的 [scheduleView] 方法进行格式化。

11.16.2.3. 预订窗口与视图模型

        // 预订对话框:仅当所请求的时间段
        // 可由该用户预订时才有
        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";
    }
  • 第 3–8 行:URL 请求预订的时间段([book=7])。它必须出现在所显示的日历中并且可由该用户预订:手动构造的 URL(过去的时间段、已被占用的时间段,或属于另一位医生的时间段)不会打开该窗口。[filter] 只保留满足条件的行,[findFirst] 在 [Optional] 中返回第一个(若无合适者则为空);
  • 第 9–17 行:窗口模型。管理者从列表中选择一位患者(所有客户,从缓存中读取);患者为自己预订:窗口只显示其姓名。[List.of()] 是一个空列表;
  • 第 20–29 行:页面模型,一个 [ScheduleModel] (参见 [models/ViewModels.java]),以名称 [model] 存放在模板中。[record] 构造函数的实参按其字段的顺序列出:页面标题键、可能存在的错误(一个 [Message]:翻译键及其参数)、医生列表、所选医生、格式为 [yyyy-MM-dd] 的日期、日历、预订窗口等。[condition ? value1 : value2] 在条件为真时等于 [value1] ,否则等于 [value2];
  • 第 28 行:所显示日历的地址,不含预订窗口——这是关闭窗口的按钮的地址;
  • 第 29 行:给已有即将到来预约的患者的提示消息:它解释了为什么他们看不到“预订”按钮。它由文件末尾的方法 [patientInfo] 计算;
  • 第 30 行:视图的名称:[templates/schedule.html]。

11.16.2.4. POST /schedule/book

    // -----------------------------------------------------------------------
    // POST /schedule/book   字段:doctorId、day、slotId、clientId
    //
    // 对于患者(USER),clientId 字段会被忽略:他们总是
    // 为自己预订。信任浏览器发送的字段,
    // 会让聪明的患者得以以他人的名义预订。
    //
    // “Post / Redirect / Get”模式:无论结果如何,我们都不
    // 在这里构建页面——而是放入一条闪现消息,并重定向
    // 到日程(参见示例 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) {
            // -> “请求无效”页面(参见 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) {
                // 没有选择患者:我们重新打开预订对话框
                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 {
                // 规则(不在过去、每位患者只有一个即将到来的预约、
                // 时间段空闲)由业务层检查
                application.addAppointment(req.day(), slot.get(), client.get());
                flash = FlashMessage.success("SCHEDULE.BOOKED");
            } catch (BusinessException e) {
                // 同样的规则,但当预订者是患者本人时,消息使用第二人称
                // (“您已有……”而不是
                // “该患者……”)。其他异常(真正的
                // 异常状况)不会被捕获: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);
    }
  • 第 13 行:[@PreAuthorize] 除了已登录用户之外,还要求具备所列角色之一(参见示例 26)。该注解包含一个表达式,由 [Spring Security] 在调用方法之前求值:如果用户具有这些角色之一,[hasAnyRole('ADMIN', 'DOCTOR', 'USER')] 为真。在这里,它没有施加进一步的限制;它记录了这条规则,并且在出现第四种角色时能起到保护作用;
  • 第 15–18 行:预订窗口中的表单字段(参见示例 11)。[@RequestParam] 将每个方法参数绑定到同名字段;[required = false]:缺失的字段得到 [null] ,而不是 Spring(MVC)的 400 错误。它们以字符串形式接收,然后被谨慎地转换;
  • 第 20 行:[RedirectAttributes] 用于在重定向之前显示闪现消息(参见示例 20);
  • 第 21–26 行:“医生”和“日期”是隐藏的表单字段;它们让用户可以返回所显示的日历。如果它们无效,说明请求不是来自我们的页面——而是被人手动构造的。异常 [ResponseStatusException(HttpStatus.BAD_REQUEST)] 生成 400 响应,服务器将其转换为错误页面(参见 [ErrorController]);
  • 第 29–31 行:对于患者,[clientId] 字段会被忽略——系统始终为患者本人进行预订。如果依赖这个由浏览器发送的字段,恶意患者就可以以他人的名义预订。[Utils.connectedPatient] 通过令牌识别客户;[Optional.of] 将其放入 [Optional] 中,使其与第 39 行的那个具有相同的类型;
  • 第 33–38 行:未选择患者的管理员会被重定向到预订窗口(带有 [book] 的 URL),并附带一条闪现错误消息。[addFlashAttribute] 将消息存入闪现属性,由 [web/CookieFlashMapManager.java] 通过 Cookie 将其携带到下一次请求;
  • 第 42–47 行:患者必须存在,时间段必须存在且属于日历中的那位医生:不能用一位医生的名义预订另一位医生的时间段;
  • 第 52 行:业务规则(不在过去、时间段可用、每位患者只能有一个即将到来的预约)由业务逻辑层验证,在被拒绝时它会抛出 [BusinessException] ;
  • 第 54–62 行:任何 [BusinessException] 都会变成一条闪现错误消息,带有其键和参数。对患者而言,消息“该患者已有一个即将到来的预约”会被替换为第二人称的消息。其他异常不会被捕获:它们是真正的错误,会导致 500 错误页面。([C#] 针对这种情况有异常过滤器 [catch ... when],它在 [Java] 中不存在:条件在 [catch] 块中检查);
  • 第 64–65 行:PRG 模式:无论结果如何,都会显示一条闪现消息,并将用户重定向到日历,由日历显示该消息。

11.16.2.5. POST /schedule/cancel

    // -----------------------------------------------------------------------
    // POST /schedule/cancel   字段:appointmentId、doctorId、day
    // (患者在“我的专区”取消自己的预约,而不是在这里)
    // -----------------------------------------------------------------------
    @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()) {
            // 已被取消(被别人取消,或双击所致)
            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);
    }
  • 第 5–6 行:取消仅限管理员;患者从“我的专区”取消其预约(参见 [PatientAreaController])。发送此请求的患者会收到 403 页面:[Spring Security] 拒绝该方法调用,其拒绝处理器(参见 [SecurityConfig])以 403 错误作出响应,服务器将其转发到 [/error];
  • 第 12–16 行:与预订相同的检查;
  • 第 17–20 行:已被取消的预约(由于双击或被另一位管理者取消)会返回错误消息,而不是错误页面;
  • 第 21–25 行:删除,随后是 PRG 模式。

使用已登录患者的令牌 Cookie(即 Jean MARTIN 先生的令牌,读者可从自己的浏览器中复制;参见“身份验证”;此处缩写为 [...]),请求会被拒绝:

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. 权限、格式化的日历和工具函数

    // -----------------------------------------------------------------------
    // 谁已连接,他们在这个页面上被允许做什么?
    // -----------------------------------------------------------------------
    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());
    }

    // -----------------------------------------------------------------------
    // 医生的日程,已为视图格式化——并按权限过滤
    // -----------------------------------------------------------------------
    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;
            // 是已连接患者的预约吗?
            boolean mine = appointment != null && rights.patient() != null && appointment.getClientId().equals(rights.patient().getId());
            return new ScheduleRowView(
                    slot.getId(),
                    Utils.time(slot),
                    free,
                    // 保密的关键点:患者只会收到自己预约的姓名;
                    // 对其他预约则为 null(视图显示“已预订”)
                    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);
    }

    // —————————————————————————— 工具函数

    // POST 表单的隐藏字段 doctorId / day;如果它们无效则为 null
    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);
    }

    // -----------------------------------------------------------------------
    // 已有即将到来预约的患者的提示消息
    // (为什么没有“预订”按钮),或 null。如果其预约
    // 出现在所显示的日程中(以蓝色显示)则无用:这种情况发生在
    // 患者刚刚预订之后,此时该消息就不合适了。
    // -----------------------------------------------------------------------
    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";
    }
}
  • 第 4–11 行:管理员拥有全部权限;没有即将到来的预约的患者可以进行预订;
  • 第 16–17 行:由业务层计算的日历被转换为数组元素,每个时间段一个([ScheduleRowView]);
  • 第 20 行:传给 [map] 的 lambda 函数在这里跨越多行:其函数体是一个用花括号括起来的块,以 [return] 结尾;
  • 第 25 行:[mine] 判断该预约是否属于已登录的患者;
  • 第 28 行:视图只接收已经格式化的数据([8:00 - 8:20]);它不再需要计算任何东西;
  • 第 32 行:应用的隐私控制。只有对管理员或预约所属的患者,患者的姓名才会包含在模型中。对其他所有人,模型中包含 [null],视图显示“已预订”。姓名不是简单地被视图隐藏:它从未被发送到浏览器,“查看页面源代码”也不会显示它;
  • 第 34–36 行:视图必须显示的内容,由控制器决定:“预订”按钮(时间段可用、日期未过、用户有权预订)、其链接(页面的 URL,加上 [book]),以及“取消”按钮([appointmentId] 仅对管理员填充)。视图不做任何决定:它遵循这些指示;
  • 第 38 行:完整的日程:医生、日期(按请求的语言格式化,“Friday 25 September 2026”)、各行;
  • 第 44–48 行:POST 表单共用的两个隐藏字段的值:一个 [ScheduleRequest],如果它们无效则为 [null] ;
  • 第 50–53 行:某位医生某一天的日程的 URL,可能带有打开的预订窗口。控制器的所有重定向都用这个方法生成它:页面的 URL 只在一处编写;
  • 第 55–57 行:下拉列表的一个选项(ID、标签、是否选中),医生和客户通用:参数的类型为 [Person],即这两个实体的父类;
  • 第 59–71 行:给已有即将到来预约的患者的提示消息。如果该预约出现在所显示的日历中,就不会发送它:蓝色显示的患者姓名就足够了,而这恰好是患者在预订之后立即看到的页面,在那里显示“您已有一个即将到来的预约”这条消息并不合适。第 69 行:[anyMatch] 指示流中是否至少有一行满足条件;[ScheduleRowView::mine] 是一个方法引用:相当于 lambda [r -> r.mine()]。

以下是 Jean 先生(角色 USER)的浏览器针对 PELISSIER 女士的日历(其中有两个已预订的时间段)收到的内容(节选):

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>

8:20 的时间段由另一位患者预订:她的姓名在页面上任何地方都没有出现。9:00 的时间段是 MARTIN 先生的预约:他的姓名以蓝色显示。由于他已经有一个即将到来的预约,因此不显示“预订”按钮。提示消息(“您已有一个即将到来的预约……”)在这里不会出现,因为这个预约就在他眼前;它出现在另一天或另一位医生的日历上,用来解释为什么没有按钮。

11.16.3. controllers/PersonsControllerBase.java

// =========================================================================
// controllers/PersonsControllerBase.java
// -------------------------------------------------------------------------
// 医生的管理和客户的管理(仅限 ADMIN)是
// 相同的:相同的列表、相同的表单、相同的规则。与其
// 把同样的操作写两遍,不如把它们只写一次,放在这个
// 抽象的泛型类中,由 DoctorsController
// (@RequestMapping("/doctors"))和 ClientsController
// (@RequestMapping("/clients"))继承它。每个子类只需提供其
// “配置”:调用哪些方法、显示哪些标签。
//
// 在这里设置的路由(@GetMapping("/add") 等)会被继承,
// 并补全子类的路由。因此对每一个我们得到:
//
//   GET  /doctors                    列表
//   GET  /doctors/add                空表单
//   POST /doctors/add                创建
//   GET  /doctors/{id}/edit          预先填充的表单
//   POST /doctors/{id}/edit          编辑
//   POST /doctors/{id}/delete        删除
//
// (/clients 下也有同样的 URL)。视图也是共用的:
// templates/persons/list.html 和 templates/persons/form.html。
//
// 抽象类永远不是 Bean:只有其带有 @Controller 注解的
// 具体子类才是控制器。
//
// 安全性:@PreAuthorize("hasRole('ADMIN')") 放在这个类上,
// 而不是子类上。为了确定某个
// 操作适用哪条规则,Spring Security 会先看方法的注解,再看
// 声明该方法的类的注解——这里是 PersonsControllerBase。如果只
// 放在 DoctorsController 上,该注解对
// 继承的操作将被忽略:USER 就可以打开 /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> {

    // -----------------------------------------------------------------------
    // 每个子类必须提供的内容。最后五个字段是
    // 函数(java.util.function 的函数式接口):
    // 子类在其中存放方法引用,如 application::getAllDoctors 等
    // -----------------------------------------------------------------------
    protected record PersonsConfig<T>(
            String url, // "/doctors" 或 "/clients"
            PersonKeys keys,
            Supplier<List<T>> list, // () -> 列表
            Function<Integer, Optional<T>> find, // id -> 人员
            Function<PersonData, T> add, // data -> 创建的人员
            BiFunction<Integer, PersonData, T> edit, // (id, data) -> 编辑后的人员
            IntConsumer delete) { // id -> 无
    }

    protected abstract PersonsConfig<T> config();

    // 公共视图
    private static final String LIST_VIEW = "persons/list";
    private static final String FORM_VIEW = "persons/form";

    // -----------------------------------------------------------------------
    // GET /doctors(或 /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] 已由 Spring MVC 填充并验证(@Valid):
    // 紧跟其后的 BindingResult 说明输入是否正确。
    // -----------------------------------------------------------------------
    @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+}:id 必须由数字组成——/doctors/abc/edit
    // 不匹配任何路由(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
    // (在发送表单之前会请求“确定吗?”的确认,
    // 参见 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();
    }

    // —————————————————————————— 私有方法

    // id 为 null:创建表单;否则:编辑表单。
    // errors:字段 -> 消息键;error:页面底部的消息;
    // otherFields:要以红色框出的其他字段
    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;
    }

    // 某条业务规则拒绝了写入:我们重新显示表单,
    // 带上用户的输入和业务层的消息
    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")) {
            // 在此期间已被另一位 ADMIN 删除:返回列表
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error(e.getKey()));
            return "redirect:" + config().url();
        }
        // 消息放在页面底部;所涉及的字段(如果有)会
        // 以红色框出,让用户立即看到需要更正什么
        return showForm(model, id, values, Map.of(), e.getKey(),
                Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
    }

    // 用户输入的内容(不含密码:我们绝不把它
    // 回送到浏览器)
    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());
    }

    // 已验证的表单 -> 业务层所期望的数据
    private static PersonData data(PersonForm f) {
        return new PersonData(f.getTitle(), f.getLastName(), f.getFirstName(), f.getLogin(), f.getPassword(),
                f.getVersion());
    }

    // “已添加 / 已编辑 / 已删除”消息中的 {name} 和 {login}
    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();
    }
}

医生和客户的处理是相同的。与其编写两个相似的控制器,我们不如把它们的操作只写一次,放在一个抽象的泛型父类中。我们来说明这段代码:

  • 第 15–20 行:为医生生成的路由;在 [/clients] 中也有相同的路由;
  • 第 22–23 行:视图同样是共享的(文件 [templates/persons]);
  • 第 25–26 行:该类没有用 [@Controller] 注解,而且由于它是抽象的,反正也不能被实例化:只有它的子类 [DoctorsController] 和 [ClientsController] 是 Bean,并接收请求;
  • 第 28–33 行和第 70 行:将访问限制为角色 ADMIN 的 [@PreAuthorize("hasRole('ADMIN')")] 应用于这个类。应用于类时,该注解适用于它的所有方法。不过,为了确定某个操作适用哪条规则,[Spring Security] 会先检查方法的注解,再检查声明该方法的类的注解。然而,操作 [list]、[add]……是在这里、在 [PersonsControllerBase] 中声明的,只是被 [DoctorsController] 继承。如果将其应用于 [DoctorsController],该注解对这些操作将被忽略:患者(USER)就可以打开 [/doctors]。这与 [ASP.NET Core MVC] 不同,在那里子类的特性 [[Authorize(Roles = "ADMIN")]] 也适用于继承的操作;
  • 第 71 行:该类是抽象的 ([abstract]:不能创建它的对象;它的存在仅仅是为了被派生)并且是泛型的:[T] 是一个类型参数,每个子类将其替换为 [Doctor] 或 [Client]。[T extends Person] 是一个约束:[T] 必须是 [Person] 或其派生类之一;因此代码可以使用 [p.getFirstName()] 或 [p.getUser()],它们是所有个人共有的;
  • 第 78–86 行:每个子类提供的配置,以 [record] 的形式给出:基础 URL、文本(翻译键,归入 [record] [PersonKeys],位于 [models/ViewModels.java] 中),以及用于列出、搜索、添加、修改和删除的五个函数 。存储在变量中的函数,其类型是来自 函数式接口 [java.util.function] 包的类型(参见“业务层”):[Supplier<R>] (无参数,返回一个 [R],方法 [get]),[Function<P, R>] (一个参数:[P];返回一个 [R];方法:[apply]),[BiFunction<P1, P2, R>] (两个参数),[IntConsumer] (一个 [int];无返回值;方法 [accept])。[protected]:[record] 仅对该类及其子类(以及同一个包)可见;
  • 第 88 行:一个抽象方法:每个子类都必须实现它,以指定其配置;
  • 第 91–92 行:两个视图,由它们在 [templates] 文件夹中的路径指定;
  • 第 97–108 行:列表。应用于父类方法的路由注解会被继承:与子类的 [@RequestMapping("/doctors")] 结合后,得到 [GET /doctors]。[config.list().get()] 调用配置中指定的函数。对于每个人,模型中包含其“编辑”和“删除”按钮的 URL 值;
  • 第 113–116 行:空表单。[Map.of()] 是一个空字典:没有错误;
  • 第 123–138 行:添加操作,分三步,如示例 28 所示。参数 [form] 由 Spring MVC 用提交的字段填充,然后根据其注解进行验证 ([@NotBlank]、[@Size]……,参见 [models/Forms.java]),因为它带有 [@Valid] 注解(参见示例 19)。验证结果包含在紧随其后的参数 [BindingResult] 中:无效的输入会重新显示表单,保留输入的值,并在每个错误字段下方显示一条消息;有效的输入会被传给业务层,然后浏览器被重定向到列表,并带有一条闪现消息(PRG);业务层的拒绝(重名、登录名已被使用)会重新显示表单;
  • 第 145–152 行:编辑表单,已预先填充。[{id:\\d+}] 是与正则表达式关联的路径变量:标识符必须由数字组成([\d+],其中 [\] 在 [Java] 字符串中需要重复写两次)。[/doctors/abc/edit] 因此不对应任何路由,会得到 404 页面。不存在的用户同样得到 404:[orElseThrow] 从 [Optional] 中取出值,或者在其为空时抛出由 lambda 生成的异常。版本号是表单中的隐藏字段,将用于乐观锁(参见示例 28);
  • 第 157–172 行:更新,遵循与插入相同的模式;
  • 第 179–191 行:删除。事先检索该人员,以便在成功消息中显示其姓名([orElse(null)]:该人员,或者在其不存在时为 [null] )。业务层的拒绝(有预约的医生)会在列表页面上产生一条闪现错误消息;
  • 第 198–212 行:表单,同时用于创建([id] 等于 [null])和修改:只有称谓和邮寄地址会改变。[Validation.state] 和 [Validation.pageMessage] (文件夹 [web])准备按字段划分的错误、要以红色高亮显示的字段,以及页面底部的消息;
  • 第 216–227 行:此后已被(另一位管理员)删除的人员会显示在列表中;其他业务错误会重新显示表单,带有页脚消息,并以红色高亮显示相关字段([Validation.BUSINESS_ERROR_FIELDS] 将每个错误代码与其对应的字段关联起来:[firstName] 和 [lastName] 对应同名同姓的情况);
  • 第 231–238 行:要重新显示的值——绝不包括密码;
  • 第 241–244 行:传给业务层的数据;
  • 第 247–251 行:成功消息的参数 [{name}] 和 [{login}] :此人的名和姓,以及其登录名;
  • 第 253–255 行:关联账户的登录名(如果账户缺失则为空字符串,作为预防措施:每个人都有账户)。

11.16.4. controllers/DoctorsController.java

// =========================================================================
// controllers/DoctorsController.java
// -------------------------------------------------------------------------
// 医生的管理(仅限 ADMIN 角色)。所有操作都
// 继承自 PersonsControllerBase:这里剩下的只是说明调用什么、
// 显示哪些标签。
//
// 对 ADMIN 角色的限制放在父类上(参见 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:一个“方法引用”,即
        // application 对象的 getAllDoctors 方法,存放在变量中
        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;
    }
}
  • 第 8–9 行:对 ADMIN 角色的限制由父类承担,原因如上所述;
  • 第 20–22 行:一个控制器([@Controller]),其所有路由都以 [/doctors] 开头。它继承([extends])自 [PersonsControllerBase<Doctor>]:父类的类型 [T] 变为 [Doctor];
  • 第 26–45 行:构造函数通过注入接收 [ApplicationModel] ,并一次性创建配置:基础 URL 和医生专用的翻译键;
  • 第 40–44 行:要调用的函数,它们是 ***[ApplicationModel]*** 的方法。***[application::getAllDoctors] 是一个*方法引用:它不调用该方法;它只是引用它。编译器将其转换为 [record] 所期望的函数式接口的值(第一个是 [Supplier<List<Doctor>>] ),其方法 [get] 将调用 [application.getAllDoctors()]。这是 lambda [() -> application.getAllDoctors()] 的简写形式;
  • 第 29 行:[new PersonsConfig<>(...)]:[<>] 运算符,称为“菱形”运算符,让编译器推断泛型类型([Doctor]);
  • 第 47–50 行:父类的抽象方法,在这里写成 [@Override],指示编译器验证它确实重写了父类的某个方法。

正如我们在身份验证中看到的,请求 [/doctors] 的患者会收到 403 页面:这说明设置在父类上的保护是有效的。我们还注意到,这个错误页面的导航栏显示了用户(参见 [currentUser] 方法,位于 [auth/AuthService.java])。使用 Jean MARTIN 先生(角色 USER)的令牌 Cookie:

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
// -------------------------------------------------------------------------
// 客户(诊所的患者)的管理,仅限 ADMIN 角色。
// 原理与 DoctorsController 相同(参见其注释)。
// =========================================================================
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;
    }
}

同样的控制器,用于客户:不同的路由(第 16–18 行)、不同的翻译键、[ApplicationModel] 的不同方法(第 34–38 行)。

11.16.6. controllers/RegistrationController.java

// =========================================================================
// controllers/RegistrationController.java
// -------------------------------------------------------------------------
// “创建客户账户”:尚无账户的患者
// 自己创建账户。非受保护的路由(根据
// 定义,此时还没有账户):
//
//   POST /register/access     身份验证页面的“创建客户账户”按钮:
//                             检查该页面上的验证码,
//                             然后打开表单
//   GET  /register            表单
//   POST /register            创建,然后返回登录页面
//
// 该流程由一个验证码保护以防范机器人,即身份验证页面上的
// 那一个:
//   1. “创建客户账户”按钮将登录表单发送
//      到 /register/access;如果验证码抄写正确,服务器
//      会签发一个通行令牌(参见 auth/RegistrationPassService.java);
//   2. 没有有效通行令牌时,/register 会把用户送回
//      身份验证页面——直接输入 URL 是没有用的;
//   3. 通行令牌在创建时被消费:一个已解答的验证码
//      只能创建一个账户;
//   4. 此外,每小时每个 IP 地址创建的账户数量
//      受到限制(参见 auth/AttemptLimiterService.java)。
//
// 所创建的账户与 ADMIN 从“客户”页面创建的账户完全相同
// (业务层的同一个方法:addClient),只不过
// 患者自己选择登录名和密码(必填,
// 并需确认)。
// =========================================================================
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   字段:captchaId、captcha(身份验证页面的
    // 那些字段;同时发送的登录名和密码会被忽略)
    // -----------------------------------------------------------------------
    @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);

        // 最近从该地址创建的账户过多:无需再继续
        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";
        }

        // 验证码缺失或错误:返回身份验证页面,并显示
        // 新的图片(失败会算作一次登录失败)
        if (!captchaService.verify(captchaId, captcha)) {
            limiter.loginFailure(ip, "");
            redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
            return "redirect:/login";
        }

        // 验证码正确:我们签发通行令牌并打开表单
        response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.cookie(passes.issue()).toString());
        return "redirect:/register";
    }

    // -----------------------------------------------------------------------
    // GET /register
    // @CookieValue:该名称的 Cookie 的值(如果它不存在则为 null)
    // -----------------------------------------------------------------------
    @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
    // [form] 参数在调用之前由 Spring MVC 填充并验证:
    // 验证结果在 [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. 最近从该地址创建的账户过多?
        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. 一次性给出所有输入错误(字段 + 确认):
        //    用户一次全部更正
        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. 创建(客户 + USER 账户,在一个事务中)
        try {
            application.addClient(new PersonData(form.getTitle(), form.getLastName(),
                    form.getFirstName(), form.getLogin(), form.getPassword(), null));
        } catch (BusinessException e) {
            // 登录名或名 + 姓已被占用:通行令牌仍然有效
            return show(model, values, Map.of(), Message.of(e.getKey()),
                    Validation.BUSINESS_ERROR_FIELDS.get(e.getKey()));
        }

        // 4. 通行令牌已被使用:它不会再允许创建第 2 个账户
        passes.consume(pass);
        response.addHeader(HttpHeaders.SET_COOKIE, RegistrationPassService.clearedCookie().toString());
        limiter.registrationSuccess(ip);

        // 5. 返回登录页面,登录名已预先填入
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE,
                FlashMessage.success("REGISTRATION.DONE", Map.of("login", form.getLogin())));
        return "redirect:/login?login=" + UriUtils.encodeQueryParam(form.getLogin(), StandardCharsets.UTF_8);
    }

    // —————————————————————————— 私有方法

    // 没有有效的通行令牌:返回身份验证页面
    private static String backToLogin(RedirectAttributes redirect) {
        redirect.addFlashAttribute(FlashMessage.ATTRIBUTE, FlashMessage.error("ERRORS.CAPTCHA_BEFORE_ACCOUNT"));
        return "redirect:/login";
    }

    // 表单;绝不把密码回送到浏览器
    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";
    }
}

我们来说明这段代码:

  • 第 14–24 行:防范机器人,分四个步骤。验证码(CAPTCHA)和尝试次数限制器已在示例 27 中随身份验证一并介绍;
  • 第 66–81 行:路由 [/register...] 在 [SecurityConfig] ([permitAll()])中被声明为公开,并且控制器没有注解([@PreAuthorize]):其页面对所有人开放。它通过注入接收四个服务;
  • 第 87–90 行:登录页面上的“创建患者账户”按钮将登录表单发送到这个地址(属性 [formaction];参见示例 21)。只读取验证码(CAPTCHA)字段;
  • 第 91 行:浏览器的 IP 地址,通过 [AuthController] 的一个静态方法获得;
  • 第 94–99 行:在过去一小时内从该地址创建的账户过多:重定向到登录页面,并以弹出消息指明需要等待的分钟数。[Map.of("minutes", ...)] 生成消息参数的字典;
  • 第 103–107 行:缺失或错误的验证码(CAPTCHA)算作一次失败的登录尝试(用户名为空):机器人无法无限地尝试下去。返回登录页面会显示一张新图片;
  • 第 110–111 行:验证码(CAPTCHA)正确:一个令牌(参见 [auth/RegistrationPassService.java])通过添加到响应中的 [Set-Cookie] 头存入 Cookie,并将浏览器重定向到表单;
  • 第 118–125 行:表单,但只有持有有效令牌时才可访问。直接输入地址 [/register] 不会有任何效果。[@CookieValue] 将参数 [pass] 绑定到同名 Cookie 的值(如果它不存在则为 [null] ,这归功于 [required = false]);
  • 第 132–136 行:创建。表单 [RegistrationForm] (文件夹 [models])已由 Spring MVC 绑定并验证([@Valid]),结果存放在 [result] 中;
  • 第 137–139 行:再次验证令牌:POST 请求可能是未经过表单就发送的;
  • 第 141–146 行:出错时要重新显示的值,不含密码。默认称谓是 [Mr];
  • 第 149–153 行:时间限制,在创建时再次检查;
  • 第 157–164 行:输入错误,逐字段列出(参见示例 19)。[Validation.errorsOf] 将它们汇集成字典(字段,消息键),并复制到一个 [HashMap] 中以便补充。密码与其确认是否一致——涉及两个字段——在这里手动验证;只有当这两个字段本身都正确时才进行测试。所有错误一并报告:用户可以一次全部更正;
  • 第 167–174 行:使用 ADMIN 所用的业务层方法创建客户及其 USER 账户。如果用户名或“名 + 姓”的组合已被占用,则重新显示表单,并以红色高亮显示相关字段;令牌仍然有效;
  • 第 177–179 行:令牌已被使用:它在服务器端被消费,其 Cookie 被删除。创建操作最终计入每小时的限制;
  • 第 182–184 行:返回登录页面,预先填入用户名,并附带一条成功消息。[UriUtils.encodeQueryParam] 对用户名进行编码,使其可以包含在 URL 中;
  • 第 190–193 行:没有通行令牌时,返回登录页面并附带一条消息;
  • 第 196–201 行:表单,由 [Validation], 准备,与医生和客户的表单类似。名为 [static] 的方法不使用对象的任何字段;不需要对象就可以调用它。

11.16.7. controllers/PatientAreaController.java

// =========================================================================
// controllers/PatientAreaController.java
// -------------------------------------------------------------------------
// 患者(角色 USER)的个人页面,也就是他们在登录之后
// 立即看到的页面:
//
//   GET  /my-area                  主页:[Manage my account],
//                                  [View a schedule],以及其即将到来的预约
//   POST /my-area/cancel           取消其本人的预约
//   GET  /my-account               其账户的编辑表单
//   POST /my-account               编辑
//   POST /my-account/delete        删除账户(及其预约)
//
// 该控制器的黄金法则:所涉及的患者始终是令牌所对应的那一位
// (Utils.connectedPatient),绝不是浏览器发送的标识符。因此患者
// 既不能查看、编辑,也不能取消属于另一位患者的内容,
// 即使他们自己构造请求也不行。
//
// 对账户的任何编辑或删除都需要当前
// 密码:发现一个未关闭会话的人
// 既不能更改密码,也不能删除账户。当前密码的
// 错误会被算作登录失败(适用相同的限制)。
// =========================================================================
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()),
                        // 指向该医生当天日程的链接:患者在其中看到自己的姓名
                        "/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   字段: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);
        // 不存在的预约和属于另一位患者的预约会得到
        // 相同的回答:我们不透露任何关于他人预约的信息
        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);
        }

        // 当前密码
        Message passwordError = checkCurrentPassword(request, patient, form.getCurrentPassword());
        if (passwordError != null) {
            // 密码错误:消息同样显示在字段下方
            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 = 不变
                    form.getVersion()));
            // 登录名和显示名称在令牌中:我们签发
            // 新的令牌,否则导航栏会保留旧的名称
            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   字段:deletePassword
    // 账户、客户及其所有预约会一起消失,
    // 然后患者被登出。
    // -----------------------------------------------------------------------
    @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";
    }

    // —————————————————————————— 私有方法

    // 令牌所对应的患者
    private Client patient(Jwt token) {
        return Utils.connectedPatient(application, Utils.user(token));
    }

    // 如果当前密码正确则为 null;否则为错误消息
    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";
    }
}

我们来分析这段代码:

  • 第 14–17 行:该控制器的黄金法则:所涉及的患者始终是与令牌关联的那一位,绝不是浏览器发送的标识符;
  • 第 63–65 行:仅限患者。这里,类上的 [@PreAuthorize] 适用于所有操作,因为它们都声明在这个类中。该控制器没有 [@RequestMapping] 注解:每个操作都提供其完整的 URL,因为它们没有共同的前缀([/my-area], [/my-account]);
  • 第 81–95 行:“我的专区”页面。[patient] 方法(见下文)根据令牌识别客户;如果该客户的账户在登录之后被删除,它会抛出 [InvalidSessionException] 异常,由 [web/HtmlExceptionHandler.java] 通过将用户重定向回登录页面来处理。日期由 [Utils.formatDay] 按请求的语言进行格式化(参见示例 22);每个预约都包含指向该医生当天日程的链接(第 91 行);
  • 第 100–115 行:取消患者的预约。在第 105 行,无效的标识符会返回空的 [Optional] ([Optional.empty()])。不存在的预约和属于另一位患者的预约(第 108 行)会得到相同的响应:不会泄露任何关于其他患者预约的信息;
  • 第 120–126 行:账户表单,已预先填入版本号(乐观锁);
  • 第 131–134 行:修改过程,分三步:验证、验证当前密码、业务逻辑层;
  • 第 136–141 行:出错时要重新显示的值——绝不包括密码;
  • 第 143–150 行:输入错误。新密码是可选的(留空:保持不变);只有在输入了确认密码时才会检查它;
  • 第 153–160 行:当前密码。错误的密码会在其字段下方和页面底部提示;锁定(尝试次数过多)仅在页面底部指示,并附带分钟数;
  • 第 162–168 行:由业务层执行修改,其适用的规则与 ADMIN 相同(唯一性、乐观锁);
  • 第 169 行:令牌包含登录名和显示名称:修改之后会签发新的令牌;否则导航栏会保留旧名称;
  • 第 172–175 行:业务层的拒绝会重新加载表单,并以红色高亮显示相关字段;
  • 第 183–193 行:删除账户同样需要当前密码。错误会通过账户页面上的弹出消息提示(PRG);
  • 第 194–197 行:删除记录、账户和所有预约(ADMIN 所用的业务层方法),随后登出:令牌 Cookie 被清除;
  • 第 203–205 行:令牌所对应的患者;
  • 第 208–222 行:验证当前密码。如果密码正确,它返回 [null] ;否则返回错误消息(一个 [Message]:键和参数)。当前密码受到与登录相同的限制(参见示例 27):发现一个未关闭会话的人无法更改密码、删除账户,也无法无限次地尝试猜测密码。验证本身由 [AuthService] 负责;失败会被算作一次登录失败;
  • 第 224–229 行:账户表单。

11.16.8. controllers/ErrorController.java

// =========================================================================
// controllers/ErrorController.java
// -------------------------------------------------------------------------
// 错误页面(400、403、404、405、500 等)。
//
// 人们从不通过链接到达这里。当请求以错误结束时
// ——未处理的异常、response.sendError(403)、
// ResponseStatusException(NOT_FOUND) 等——服务器(Tomcat)会把
// 请求转发到 /error 地址,以构建要返回的页面,而不是
// 返回空响应或调用栈(参见示例 24)。它会
// 顺带将错误代码存放在请求的一个属性中。
//
// Spring Boot 已经提供了一个 /error 控制器(BasicErrorController,
// 即“Whitelabel Error Page”);一旦有 Bean 实现了
// ErrorController 接口,例如这个类,它就会让位。
//
// 不带 HTTP 方法的 @RequestMapping:该操作接受所有方法——
// 转发的请求保留其原始方法(被拒绝的 POST 仍然是 POST)。
// =========================================================================
package rdvmedecins.controllers;

import java.util.Map;

// (Spring Boot 的 ErrorController 接口与我们的类同名:下面写出完整名称)
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) {
        // 原始错误代码,由服务器存放在请求中
        Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        int code = status instanceof Integer c ? c : HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
        // 页面保留该代码(404 仍为 404 等);意外的代码
        // (或直接调用 /error)会变成 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";
    }
}

这就是示例 24 中的控制器,只是消息已翻译:

  • 第 6–11 行:你永远不会通过链接到达这个页面。当请求以错误结束时(未处理的异常、[ResponseStatusException]、来自 [response.sendError(403)] 的 [Spring Security] 拒绝处理器……),[Tomcat] 服务器会转发请求到 [/error] 地址,以生成要返回的页面,而不是返回空响应或调用栈;
  • 第 13–15 行和第 34–35 行:[Spring Boot] 已经提供了一个控制器 [/error] ([BasicErrorController]),它生成“Whitelabel Error Page”。一旦有 Bean 实现了 [ErrorController] 接口(在第 24 行导入),例如这个类,它就会被移除;
  • 第 37–40 行:每个错误代码对应的消息键。[static final]:单个字典,在类加载时创建,且永不被替换;[Map.of] 还使其成为只读;
  • 第 42 行:缺少 HTTP 方法的 [@RequestMapping] 接受所有方法:传给 [/error] 的 POST 请求(例如,患者试图执行仅限管理员的取消操作)仍然是 POST 请求;
  • 第 45–46 行:原始错误代码,服务器将其存放在名为 [RequestDispatcher.ERROR_STATUS_CODE] 的请求属性中。该属性的类型为 [Object]:[status instanceof Integer c] 检查它是否确实是 [Integer] ,如果是,则将其存入变量 [c]。否则(手动输入了 [/error] 地址),代码为 500;
  • 第 49–51 行:非错误的 HTTP 代码会被转换为 500 错误;
  • 第 52 行:页面保留原始错误代码(未知的页面仍然是 404 响应);
  • 第 53–55 行:页面模型及其视图的名称。[getOrDefault] 返回与代码关联的键,对于任何其他代码(尤其是 500)则返回 [ERRORS.SERVER_ERROR] 。

11.17. 视图

视图使用 [Thymeleaf] 编写(参见示例 13 至 16)。我们来回顾一下这个概念:视图是真正的 HTML 文件,其中添加了 [th:...] 属性,[Thymeleaf] 在生成页面时替换这些属性。在没有服务器的情况下直接用浏览器打开时,文件仍然可以显示,并带有其示例文本(“Mme Alice DURAND”、“8:00 – 8:20”):这称为“自然模板”。案例研究中使用的属性就是示例中的那些:

属性或表达式
作用
[th:text="${model.day}"]
用转义后的值替换元素的内容([<] 变为 [&lt;])
[th:utext]
与上面相同,但不转义(仅用于验证码(CAPTCHA)图片)
[#{SCHEDULE.FREE}]
已翻译的消息(参见示例 22)
[#{BOOKING_DIALOG.SLOT('time', ${r.time})}]
带有参数 [{time}] 的消息
[#{${error.key}(${error.params})}]
键本身就是一个值、并带有参数字典的消息
[th:if]、[th:unless]
仅当条件为真(假)时才写出该元素
[th:each="row : ${rows}"]
对列表中的每个元素重复该元素
[th:value]、[th:href]、[th:action]
计算得出的属性
[th:selected]、[th:autofocus]
布尔属性:值为真时写出,否则省略
[th:classappend]
在属性 [class] 的已有 CSS 类之外再添加一个 CSS 类
[th:attr="data-confirmation=#{...}"]
任意属性,经计算得出
[th:with="state=${model.state}"]
元素的局部变量
[th:replace="~{fragments/flash :: flash}"]
用片段替换该元素(参见示例 15)
[<th:block>]
不在生成的页面上留下任何痕迹的标签
[<!--/* ... */-->]
注释,会从生成的页面中移除

视图几乎不需要做任何决定:它们的模型已由控制器在 [record] 部分、即 [models/ViewModels.java] 文件中准备好(显示哪些按钮、哪个 URL、哪些翻译键)。每个视图都以一条描述其作用的注释 [<!--/* ... */-->] 开头;这些注释不会出现在发送给浏览器的页面中。与 [Razor] 不同,[Thymeleaf] 不知道模型的类型:[${model.dayy}] 中的拼写错误不会在编译时被发现,而是在渲染页面时才被发现,并导致异常(进而出现 500 错误)。

所有视图都可以访问相同的变量:[model],即控制器存放的页面模型;[user]、[language] 和 [path] (已登录的用户,或 [null]、请求的语言、所请求 URL 的路径),由 [web/CommonModel.java] 的 [@ModelAttribute] 方法为所有操作添加到模板中;以及 [flash],即所有闪现消息:重定向之后,Spring MVC 会自动把闪现属性放入下一次请求的模型中。

11.17.1. 模板与片段

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}}:键为表达式 ${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>
  <!--/* “确定吗?”对话框,在不需要时保持隐藏 */-->
  <div th:replace="~{fragments/confirmation :: confirmation}"></div>
  <script src="/js/app.js"></script>
</body>
</html>

这就是示例 15 中的模板。应用中的每个页面都以 [<html th:replace="~{layout :: page(~{::main})}">] 开头:它被该模板中的片段 替换 [page] 所替换,并把自己的 [<main>] 元素传给它。

  • 第 2–21 行:来自 [Thymeleaf] 的注释:[<!--/*] 和 [*/-->] 之间括起的文本会被 [Thymeleaf] 从生成的页面中移除。在没有服务器的情况下打开该文件的浏览器会把它当作普通的 HTML 注释;
  • 第 22 行:[th:fragment="page(content)"] 将整个 [<html>] 元素变为名为 [page] 的片段,它接收一个参数 [content]。[th:lang] 写出页面的 [lang] 属性:即请求的语言([fr] 或 [en]);
  • 第 27 行:标题,已翻译,例如“Schedule - RdvMedecins”。竖线 [|...|] 界定字面量替换:其中的表达式被替换为其值的文本。[#{${model.pageTitle}}] 是键为 [${model.pageTitle}] 的值的消息:该标题由控制器在每个页面的模型中提供(在示例 15 中,页面把它作为片段参数传入);
  • 第 28–29 行:样式表,由 [Spring Boot] 从 [src/main/resources/static] 文件夹提供:[Bootstrap] ([static/lib/bootstrap])以及应用专用的样式表;
  • 第 33–36 行:导航栏、成功消息(位于顶部)、所请求页面的 [<main>] 元素([th:replace="${content}"]:该元素被作为参数接收的片段所替换),以及错误区域(位于底部);
  • 第 39–40 行:确认窗口(隐藏)及其脚本(参见示例 21),加载于页面底部。

登录页面的开头部分,浏览器收到的内容如下:

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">
...

注释 [<!--/* ... */-->] 已经消失,只留下空行;[th:...] 属性也已经消失。

11.17.1.2. templates/fragments/navbar.html

<!--/* =========================================================================
   templates/fragments/navbar.html - the navigation bar.

   Title, FR/EN, role, name, logout - and a menu whose entries
   depend on the role: "Doctors" and "Patients" appear only for
   the ADMIN. It is only a display convenience: the real protection is
   the @PreAuthorize of the controllers (a USER who types /doctors by hand
   gets a 403 page). A patient (USER) also has their "My area" menu.

   The menu of the current page is highlighted ("active" class):
   [path] is the requested URL (see 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:在 HTML 中不留任何痕迹的 Thymeleaf 标签 */-->
    <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:简单的链接(GET /language/fr),当前语言高亮显示 */-->
    <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>
      <!--/* 登出是 POST:一个只有按钮的表单 */-->
      <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>
  • 第 13–14 行:片段 [navbar],由模板插入;
  • 第 17 行:菜单只对已登录用户显示。在登录页面上,[user] 被设为 [null];
  • 第 18–21 行:“我的专区”,仅限患者。[user.isPatient()] 调用 [record] [ConnectedUser] 的一个方法:[Thymeleaf] 中的表达式可以调用方法;
  • 第 19 行:当前页面的菜单会高亮显示(类 [active])。[#strings.startsWith] 是来自 [#strings] 工具对象的函数,[Thymeleaf] (参见示例 14)。[condition ? 'active']、不带“else”子句,在条件为假时求值为 [null] ,此时 [th:classappend] 不添加任何内容;
  • 第 27–36 行:“医生”和“患者”,仅限 ADMIN。[th:block] 将这两个元素归入同一个条件之下,且不在页面上留下任何标签。这只是为了显示上的方便:真正的保护来自控制器的 [@PreAuthorize] (如我们所见,手动输入 [/doctors] 的 USER 会收到 403 页面);
  • 第 38 行:如果没有用户登录,一个空元素会把 FR / EN 按钮推到导航栏的右侧,就像菜单所起的作用一样;
  • 第 43–44 行:FR / EN 按钮只是指向 [/language/fr] 和 [/language/en] 的链接;当前语言对应的按钮会高亮显示([btn-light])。这里的条件表达式两个分支都有;
  • 第 48–49 行:用户的角色和姓名,从令牌中读取;
  • 第 51–53 行:登出是一个 POST 请求(参见示例 25),由 [Spring Security] 处理(参见 [SecurityConfig]):一个只有单个按钮的表单。放在其他站点上的简单链接(GET)无法在用户不知情的情况下将其登出。

11.17.1.3. templates/fragments/flash.html

<!--/* =========================================================================
   templates/fragments/flash.html - the SUCCESS message put by the previous
   action (appointment saved, doctor added...), displayed only
   once, at the top of the page (see web/CookieFlashMapManager.java).
   An ERROR flash message is displayed at the bottom of the page, by
   fragments/errors.html.

   #{${flash.key}(${flash.params})}: the message whose key is
   flash.key, with as parameter the dictionary of the values of {name},
   {login}... (see 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>
  • 第 12–14 行:上一个操作在重定向之前设置的成功消息的显示。[flash] 是一个 [FlashMessage] (参见 [web/FlashMessage.java]):包含类型(成功或错误)、翻译键和参数。这个片段只显示成功消息;错误由后面的片段显示在页面底部。[role="status"] 会使屏幕阅读器朗读该消息;
  • 第 14 行:[#{${flash.key}(${flash.params})}]:键为 [flash.key] 的消息,以字典 [flash.params] 作为其参数([{name}]、[{login}] 等的值)。在文本中替换这些参数的是 [Translator] 服务(参见“Web 层:公共服务”)。

11.17.1.4. templates/fragments/errors.html

<!--/* =========================================================================
   templates/fragments/errors.html - the error zone, at the BOTTOM of each
   page, on a light pink background (.error-zone class, see static/css/styles.css).

   It gathers the two possible sources of error:
     - model.error: the error of the displayed page (refused form, login
       or first + last name already used, invalid date, wrong password...);
     - an error flash message, put by the previous action before a
       redirect (slot already booked, deletion refused...).

   th:with defines variables local to the element. It is placed on an
   ENCLOSING th:block: on the same element, Thymeleaf evaluates th:if BEFORE
   th:with, and the variables would not exist yet. role="alert": a
   screen reader announces the message as soon as the page is displayed, even if it
   is at the bottom.
   ========================================================================= */-->
<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>
  • 第 5–9 行:错误区域汇集了两个可能的错误来源:页面错误([model.error])和闪现错误消息;
  • 第 17–18 行:[th:with] 定义了两个局部变量。[error] 是页面错误;[flashError] 是闪现消息(如果它是错误),否则为 [null] (一个不带“else”子句的条件表达式,与导航栏中的一样)。这些变量定义在一个 ***[th:block] 上,该元素*包围使用它们的元素。你不能把 [th:with] 和 ***[th:if] 写在同一个元素上:[Thymeleaf]* 按固定顺序处理元素的属性,这个顺序与属性的书写顺序无关,并且 [th:if] 是在 之前*[th:with]* 求值的。条件将会使用尚不存在的变量;
  • 第 19 行:只有至少有一条消息时才写出该字段。[role="alert"]:屏幕阅读器在页面显示时就会立即朗读该消息,即使它位于底部;
  • 第 20–21 行:两条消息,连同其参数一起被翻译。

例如,对于使用无效日期([day=2026-02-30])请求的日历,页面底部包含:

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 - the modal dialog "Are you sure?".

   It replaces the browser's window.confirm() box, which can neither be
   styled, nor translated (its buttons remain in the language of the
   browser, not in that of the page).

   A SINGLE dialog for the whole page, hidden (d-none) at first. Its
   labels are translated here, by the server, like the rest of the page;
   the small script static/js/app.js merely displays it, puts in it
   the message specific to the form (data-confirmation attribute), and sends
   the form if the user confirms.

   Same Bootstrap classes as the booking dialog (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">
          <!--/* "不,返回"而不是"取消":问题有时是
                 "Cancel this appointment?", and a "Cancel" button would be ambiguous */-->
          <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>
  • 第 4–6 行:为什么页面上要有一个窗口,而不是浏览器的 [window.confirm()] 对话框(参见示例 21)?
  • 第 16 行:整个页面只有一个窗口,最初由 [d-none] 类(来自 [Bootstrap] ,[display: none])隐藏。[static/js/app.js] 脚本通过其标识符找到它;
  • 第 17–21 行:模态窗口的 [Bootstrap] 类:变灰的背景([modal-backdrop]),然后是窗口,一旦移除 [show d-block] 类(即 [d-none]),窗口就会变得可见。[role="alertdialog"]、[aria-modal]、[aria-labelledby] 和 [aria-describedby] 向屏幕阅读器描述该窗口;
  • 第 24 行:关闭按钮。其供屏幕阅读器使用的标签([aria-label])已被翻译;[th:attr] 计算某个属性;
  • 第 27 行:每个表单专属消息的位置,由脚本放置在那里;
  • 第 30–33 行:“不,返回”而不是“取消”:有时问题是“取消这个预约吗?”。属性 [data-action] 告诉脚本点击的是哪个按钮。

11.17.1.6. templates/fragments/captcha.html

<!--/* =========================================================================
   templates/fragments/captcha.html - the captcha of the authentication page
   (see auth/CaptchaService.java). It protects both the login and
   the access to account creation ("Create a client account" button).
   Parameter: captcha, a Captcha object (id, svg).

   th:utext: the SVG image is inserted AS IS in the page, without
   escaping. It is harmless here because this SVG is built by the
   server itself and contains nothing that comes from the user - one would
   NEVER do that with an input.

   The hidden field captchaId tells the server WHICH captcha to check; the right
   answer itself is never sent to the browser.
   "Another image" simply reloads the page ([path] = the current URL).
   ========================================================================= */-->
<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>
  • 第 16 行:一个带参数的片段:插入它的页面向它传入对象 [Captcha] (ID 和图片);
  • 第 19 行:验证码(CAPTCHA)的 SVG 图片(参见示例 27)被原样插入页面([th:utext]),不经转义。这里是安全的,因为这个 SVG 由服务器自己生成,不包含任何用户提供的内容;我们绝不会对用户输入这样做。[role="img"] 和 [aria-label] 向屏幕阅读器描述该图片;
  • 第 20 行:“换一张图片”只是重新加载页面([path] 是当前 URL 的路径):每次渲染视图都会生成新的验证码(CAPTCHA);
  • 第 22 行:隐藏字段 [captchaId] 告诉服务器要验证哪个验证码(CAPTCHA);而正确答案则绝不会发送到浏览器;
  • 第 23–24 行:输入字段。[autocomplete="off"]、[autocapitalize="off"]、和 [spellcheck="false"] 可防止浏览器对输入进行提示、自动大写或更正。

11.17.1.7. templates/fragments/person-fields.html

<!--/* =========================================================================
   templates/fragments/person-fields.html - the identity fields (title,
   first name, last name), common to three forms: doctor/client of the ADMIN,
   "Create a client account" and "Manage my account".
   The fragment reads the [model] variable of the page that inserts it (a
   FormView, see models/ViewModels.java): values, message under
   each field, fields outlined in red.

   th:selected: a boolean attribute. Thymeleaf writes selected="selected"
   if the value is true, and OMITS the attribute if it is false.
   th:classappend: adds a class to those already present - here
   "is-invalid" (Bootstrap red outline) for a refused field, or nothing.
   ========================================================================= */-->
<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>

称谓、名和姓字段是三种表单共有的:ADMIN 表单(用于医生和客户)、账户创建表单以及“管理我的账户”表单。它们只在这个片段中写一次。

  • 第 14 行:[fields] 片段是一个 [th:block]:它不会在字段周围添加任何标签。它从插入它的页面中读取 [model] 变量:即实现了 [FormView] 接口的模型(参见 [models/ViewModels.java]),因此它带有值([values])和状态([state])。[th:with] 将状态存入一个更短的变量;同一个元素上没有 [th:if] ;
  • 第 17 行:[th:classappend] 添加由 [state.invalidClass('title')] 返回的类:对于被拒绝的字段是 [is-invalid] (来自 [Bootstrap] 的红色边框),否则为空字符串;
  • 第 18–19 行:称谓([Mr]、[Mme]、[Melle]),由模型的 [titles()] 方法返回,这是 [FormView] 接口的默认方法。每个选项都指明自己是否被选中:如果值为真,[th:selected] 会写出 [selected="selected"] ,如果为假则省略该属性;
  • 第 21–22 行:字段的错误消息(如果有)。[#{${state.errorOf('title')}}]:其键由 [errorOf] 返回的消息。[Bootstrap] 的 [invalid-feedback] 类仅在 [is-invalid] 字段之下显示该消息;
  • 第 25–40 行:名和姓,格式相同,在较宽的屏幕上并排显示([col-sm-6])。[th:value] 重新显示输入的内容;[maxlength] 和 [required] 是为方便用户而设的功能,因为真正的验证由服务器执行。

11.17.1.8. templates/fragments/booking.html

<!--/* =========================================================================
   templates/fragments/booking.html - the booking dialog of the
   schedule.

   The REAL Bootstrap classes of a modal dialog (.modal,
   .modal-backdrop...), made visible "hard-coded" (show d-block) rather than
   by the JavaScript of Bootstrap. It is the SERVER that decides to display it
   (&book=... parameter of the URL), and closing it amounts to following a link
   to the same page without this parameter.

   The fragment directly reads the [model] variable of the page that inserts it
   (a 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>

        <!--/* 除所选患者之外服务器还必须知道的内容 */-->
        <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}">

        <!--/* 患者为自己预订:没有可供选择的列表
               (and the server ignores a possible clientId anyway) */-->
        <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>
  • 第 5–9 行:预订窗口使用来自 [Bootstrap] 的模态窗口的实际类,以“硬编码”的方式使其可见([show d-block]),而不是通过 [Bootstrap] 的 [JavaScript]。由服务器决定是否显示它;
  • 第 14 行:该片段读取页面模型(一个 [ScheduleModel]);[th:with] 将窗口([model.booking])存入变量 [booking];
  • 第 18 行:表单以 POST 方式将预订发送到 [/schedule/book];
  • 第 21 行:关闭按钮是指向日历的链接,不带参数 [book]:关闭窗口就是简单地显示不带该窗口的页面;
  • 第 25 行:“时间段 8:00 - 8:20”:一条带参数的消息。在 [#{BOOKING_DIALOG.SLOT('time', ${booking.time})}] 中,参数以(名称, 值)对的形式给出:[{time}] 被替换为 [booking.time] 的值;
  • 第 28–30 行:隐藏字段:医生、日期(用于返回同一个日历)以及时间段;
  • 第 34–37 行:患者为自己预订:没有列表,只有其姓名(服务器反正会忽略任何 [clientId]);
  • 第 38–45 行:管理员从列表中选择一位患者——必填([required])——该列表在页面打开时获得焦点([autofocus]);
  • 第 49 行:“取消”同样是指向不带弹出窗口的页面的链接。

11.17.2. 页面

11.17.2.1. templates/login.html

<!doctype html>
<!--/* =========================================================================
   templates/login.html - the login form (see AuthController).
   An ordinary HTML <form>: the browser itself sends login,
   password and answer to the captcha in POST /login, without JavaScript. In case
   of failure, the server returns THIS page, with the login already typed, a
   NEW captcha and the error, displayed at the bottom of the page by the layout.

   The whole page is REPLACED by the [page] fragment of the layout, to which we
   pass the <main> block of this page (~{::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:布尔属性,值为真时写出,否则省略 */-->
          <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>

        <!--/* 尚无账户:患者可以自己创建一个。
               It is NOT a simple link: it is a second submit button of
               THIS form, which goes to another address (formaction). The
               server checks the captcha above there before opening the
               account creation page (see RegistrationController).
               formnovalidate: the browser does not require login and password
               (useless to create an account); it is the server that checks
               the captcha. Enter in a field always triggers the FIRST
               button of the form, "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>
  • 第 12 行:该页面被模板中的 [page] 片段所替换,并向其传入自己的 [<main>] 元素。[~{::main}] 指当前文件中的 [<main>] 元素。因此,只使用这个元素:该文件中的 [<html>] 和 [<body>] 标签只是为了使它成为可在浏览器中打开的完整 HTML 文件;
  • 第 14 行:在一次失败的尝试之后,控制器返回此页面,并带有已输入的登录名([model.login]);变量 [loginTyped] 指示登录名是否已知;
  • 第 19 行:标准的 HTML 表单:由浏览器自己提交用户名、密码和验证码(CAPTCHA)答案;
  • 第 23–29 行:[th:autofocus] 在值为真时设置布尔属性 [autofocus] ,否则省略它:两个字段中只有一个会得到它。光标会放在用户名字段中,如果用户名已知,则放在密码字段中。[autocomplete] 的值([username]、[current-password])可帮助浏览器的密码管理器;
  • 第 32 行:验证码(CAPTCHA),一个带参数的片段,接收对象 [model.captcha];
  • 第 45–46 行:第二个按钮将同一个表单提交到 [/register/access] (属性 [formaction],参见示例 21):服务器在那里先验证验证码(CAPTCHA),然后才打开账户创建页面。[formnovalidate]:浏览器不要求填写用户名和密码,因为创建账户并不需要它们。在字段中按 Enter 键始终会触发表单上的第一个按钮:“登录”;
  • 第 50–57 行:演示账户(密码 = 登录名)。

下面是为地址 [/login?login=martin] 生成的表单(验证码图片已被裁剪):

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>

由于登录名已知,只有密码字段被赋予了属性 [autofocus]。“换一张图片”链接指向 [/login]:变量 [path] 只包含 URL 的路径,不含其参数。

11.17.2.2. templates/schedule.html

<!doctype html>
<!--/* =========================================================================
   templates/schedule.html - the main page (see ScheduleController).
   Three blocks:
     1. the choice of the doctor and of the day;
     2. the schedule;
     3. the booking dialog (fragments/booking.html).
   A possible error (invalid date, unknown doctor) is displayed at the
   bottom of the page by the layout (see fragments/errors.html).
   ========================================================================= */-->
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>

  <!--/* 1. 选择医生和日期:一个 GET 表单,它只是
         reloads this page with ?doctorId=...&day=... in the 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>

  <!--/* 已有即将到来预约的患者:为什么没有“预订”按钮 */-->
  <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. 日程;th:object:${schedule} 之后可以写成 *{...} */-->
  <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] 仅在用户被允许时才填充
                   see this name (ADMIN, DOCTOR, or the patient for THEIR
                   appointment) - otherwise, simply "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>
            <!--/* 所显示的按钮已由控制器决定
                   (bookable, appointmentId) according to the role of the user */-->
            <!--/* “预订”是一个简单的链接:它重新打开该页面
                   with the booking dialog of this slot */-->
            <a th:if="${row.bookable}" class="btn btn-sm btn-outline-success"
               th:href="${row.bookUrl}" th:text="#{SCHEDULE.BOOK}">Book</a>
            <!--/* “取消”会修改数据:因此它是 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. 预订对话框,仅当 URL 包含 &book=... 时 */-->
  <th:block th:if="${model.booking != null}">
    <div th:replace="~{fragments/booking :: booking}"></div>
  </th:block>

</main>
</body>
</html>

我们来分析这段代码:

  • 第 17–35 行:选择医生和日期:一个 GET 表单(参见示例 17),它会在 URL 中带上 [?doctorId=...&day=...] 重新加载页面。每位医生都是一个 [OptionView] ,它指明该医生是否被选中([th:selected])。[type="date"] 字段以 [yyyy-MM-dd] 格式发送日期(参见示例 18);
  • 第 38–41 行:给已有即将到来预约的患者的消息:它解释了为什么没有“预订”按钮,并提供指向“我的专区”的链接。当患者的预约出现在所显示的日历中时,控制器不会发送这条消息(参见 [patientInfo])。[#{${model.info}}]:消息键由控制器提供;
  • 第 44 行:日历(如果被请求)。[th:object] 指向一个选择对象:在该元素内部,[*{day}] 代表 [${model.schedule.day}];
  • 第 45 行:标题:“Friday 25 September 2026 - Mme Marie PELISSIER 的日程”,通过字面量替换实现;
  • 第 47 行:仅当日程有行时才写出该表格([th:unless]:除非……);
  • 第 56 行:每个时间段一行。可预订的时间段在鼠标悬停时会变色(类 [free-slot],参见 [styles.css]);
  • 第 62–67 行:三种情况:可预订;已预订并带有患者姓名(如果是已登录患者的预约,则为蓝色,[mine];否则为灰色);已预订但姓名不可见,显示“已预订”。仅当用户有权查看该姓名时,控制器才会填充 [patient] ;
  • 第 74–75 行:“预订”是一个链接:它重新打开该页面,并显示该时间段的预订窗口([bookUrl],由控制器准备);
  • 第 77–83 行:“取消”会修改数据:它是一个带确认的表单(POST)。[th:attr] 设置属性 [data-confirmation],其中包含已翻译的问题;脚本 [app.js] 会拦截带有此属性的表单的提交(参见示例 21)。隐藏字段 [doctorId] 和 [day] 让控制器能够重定向到同一个日历。在循环中,[model] 始终指页面模型;
  • 第 88 行和第 90 行:没有可用时间段的医生,或尚未请求日历;
  • 第 93–95 行:预订窗口,如果控制器已准备好它。条件设置在包含它的 [th:block] 上:读取 [model.booking] 的片段只有在该窗口存在时才会被插入。

11.17.2.3. templates/persons/list.html

<!doctype html>
<!--/* =========================================================================
   templates/persons/list.html - the list of the doctors OR of the clients (ADMIN).
   A single view for both: the labels specific to each one arrive in
   model.keys (see 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:将打开一个确认对话框
                     before the form is sent (see 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>
  • 第 11–12 行:添加按钮的标题和标签:由控制器提供的翻译键([model.keys]),医生和客户的翻译键各不相同;
  • 第 16 行和第 47 行:表格,或者在列表为空时显示消息“没有医生。”(“没有患者。”);
  • 第 27 行:每人一行;
  • 第 31 行:登录名,使用等宽字体([<code>]);
  • 第 34–35 行:“编辑”是指向编辑表单的链接;
  • 第 38–41 行:“删除”会修改数据:它是一个带确认的 POST 表单。确认问题是由控制器提供的键:[#{${model.keys.confirmDelete}}];其地址([th:action])也是如此。

11.17.2.4. templates/persons/form.html

<!doctype html>
<!--/* =========================================================================
   templates/persons/form.html - creation OR edit of a
   doctor or a client (ADMIN). model.creating distinguishes the two cases.

   When the input is refused (empty field, login already taken...), the
   controller returns THIS view with:
     - the values already typed (model.values);
     - the faulty fields outlined in red (Bootstrap class "is-invalid");
     - under a field refused by the validation, its message;
     - the error message of the page, displayed AT THE BOTTOM of the page by the
       layout (see 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:我们让服务器来验证(它才是权威);
             the browser checks (required...) are only a convenience,
             which a user can always bypass */-->
      <form method="post" th:action="${model.action}" novalidate>
        <input type="hidden" name="version" th:unless="${model.creating}" 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="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>
          <!--/* 永不预先填充:密码绝不会回到浏览器 */-->
          <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>
  • 第 16 行:[state]:表单状态,用于公共片段中未包含的部分;
  • 第 19 行:标题:“添加医生”、“编辑患者”等;
  • 第 24 行:邮寄地址,由控制器提供。[novalidate]:浏览器自己不验证这些字段([required]、[maxlength]);由服务器验证它们,服务器才是权威来源(参见示例 19);
  • 第 25 行:记录版本(乐观锁),仅用于修改;
  • 第 28 行:称谓、名和姓字段,通过公共片段实现。[th:replace] 用在 [th:block] 上:片段替换该块;
  • 第 34–39 行:登录名,带有其错误消息,或者在没有错误时带有其帮助文本,后者取决于模式:[${model.creating} ? #{...} : #{...}] 在两条消息之间选择;
  • 第 45–50 行:密码,永远不会预先填充;它从不会被发回浏览器;
  • 第 55 行:返回列表。

11.17.2.5. templates/registration.html

<!doctype html>
<!--/* =========================================================================
   templates/registration.html - "Create a client account" (public page,
   see RegistrationController). Same identity fields as the form of
   the ADMIN (person-fields fragment), but the login and the password
   are mandatory, with confirmation.
   No captcha HERE: one reaches this page only after having copied
   that of the authentication page ("Create a client account" button).

   #{${key}('min', ${model.passwordMin()})}: the message whose key is
   the value of [key], with the parameter {min} (see 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>
  • 第 21 行:表单,以 POST 方式发送到 [/register],由服务器验证([novalidate]);
  • 第 22 行:身份字段,与 ADMIN 表单中的相同;
  • 第 26–33 行:登录名,在这里是必填的;
  • 第 37–43 行:密码。错误消息“密码长度至少为 {min} 个字符”带有一个参数:[#{${key}('min', ${model.passwordMin()})}] 同时传入计算得出的键和一个参数——在 [models/InputRules.java] 中设定的最小长度——该参数由模型中的方法读取;
  • 第 46–50 行:确认密码,由验证器比较;
  • 第 56 行:用户被重定向回登录页面。

11.17.2.6. templates/area.html

<!doctype html>
<!--/* =========================================================================
   templates/area.html - "My area": the home page of the patient
   (role USER), displayed right after their login.
     - two options: [Manage my account] and [View a schedule];
     - their upcoming appointment, if they have one, with the means to cancel it.
   ========================================================================= */-->
<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>
    <!--/* 通常只有一个(规则“同一时间只有一个即将到来的预约”),
           but the page can display several. [status]: an iteration
           variable provided by th:each (status.last: last element?) */-->
    <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>
  • 第 11 行:“Hello Mr Jean MARTIN”:一条带参数 [{name}] 的消息;
  • 第 13–26 行:页面上的两个选项,大号的可点击卡片(链接),对鼠标悬停有响应(类 [option-card],参见 [styles.css]);
  • 第 33–35 行:即将到来的预约。通常只有一个(每位患者一个即将到来的预约),但页面可以显示多个。[th:each="appointment, status : ..."] 在循环变量之后声明了一个由 状态变量 提供的 [Thymeleaf]:[status.last] 指示该元素是否为列表中的最后一个;所有其他元素之间都用分隔线隔开([border-bottom]);
  • 第 37 行:日期和时间,已由控制器格式化;
  • 第 40 行:指向该医生当天日程的链接,患者可在其中看到自己的姓名;
  • 第 43–47 行:取消,一个带确认的 POST 表单;
  • 第 49 行:没有即将到来的预约。

11.17.2.7. templates/account.html

<!doctype html>
<!--/* =========================================================================
   templates/account.html - "Manage my account" (role USER).
   Two independent forms on the same page:
     1. the edit (identity, login, optional new password);
     2. the deletion of the account - which also cancels its appointments.
   Both require the CURRENT password.
   ========================================================================= */-->
<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. 编辑 */-->
    <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. 删除 */-->
    <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>
  • 第 15–68 行:账户修改:身份、登录名、新密码(可选)及其确认;
  • 第 19 行:客户记录的版本(乐观锁);
  • 第 52–61 行:当前密码,任何修改都必须提供;
  • 第 71–83 行:删除,带确认。同一页面上有两个独立的表单:每个只发送自己的字段。因此,这里的密码字段具有不同的名称([deletePassword])和不同的标识符。该表单没有属性 [novalidate]:浏览器甚至在触发事件 [required][submit] 之前——也就是在请求确认之前——就要求填写密码(required)。

11.17.2.8. templates/error.html

<!doctype html>
<!--/* =========================================================================
   templates/error.html - the error page (400, 403, 404, 500...),
   built by 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>
  • 第 11–12 行:由 [ErrorController] 生成的错误页面(400、403、404、500):HTTP 代码和已翻译的消息。它使用与其他页面相同的模板:用户保留其导航栏。

11.18. 字典

字典与 [ASP.NET Core MVC] 版本中的相同,没有任何改动:它们存放在 [src/main/resources/i18n] 中,并在启动时由 [Translator] 服务读取(参见“Web 层:公共服务”)。该服务会“扁平化”其结构:["TITLE"] 这段来自 ["LOGIN"] 部分的文本变成消息键 [LOGIN.TITLE],视图([#{LOGIN.TITLE}])和控制器都使用它。

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"
  }
}
  • 各部分按页面([LOGIN]、[SCHEDULE]、[AREA]……)或按主题([ERRORS]、[CONFIRMATION])对文本进行分组。有些名称([DOCTOR_DAY_PICKER]、[BOOKING_DIALOG])来自应用的早期版本,当时其客户端是使用 [Angular] 编写的;
  • 第 80 行:带有两个参数 [{name}] 和 [{login}] 的文本,它们会在翻译时被替换;
  • 第 98–137 行:错误消息。这些是业务层的 [BusinessException] 、表单验证注解([@NotBlank(message = "ERRORS.FIRSTNAME_REQUIRED")])、控制器和错误页面所使用的键。其中三条带有参数:[{minutes}] (第 124 行和第 126 行)和 [{min}] (第 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"
  }
}

英文字典在相同的行上具有完全相同的键。

11.19. 静态文件

[Spring Boot] 原样提供 [src/main/resources/static] 文件夹中的文件(参见示例 15):[static/css/styles.css] 通过地址 [/css/styles.css] 提供。这些地址在 [SecurityConfig] 中被声明为公开,以便登录页面拥有其样式。文件夹 [static/lib/bootstrap] 包含 [Bootstrap] (其样式表 [css/bootstrap.min.css] 及其许可证),这里不予展示。

11.19.1. static/css/styles.css

/* =========================================================================
   static/css/styles.css - a few settings on top of Bootstrap
   (the same as in the ASP.NET Core MVC version of this application).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -------------------------------------------------------------------------
   .error-zone: the error messages, at the bottom of the page, on a light pink background
   (see templates/fragments/errors.html).
   position: sticky + bottom: if the page is taller than the window (a
   schedule of 12 slots, for example), the zone stays stuck to the bottom of the
   window instead of disappearing below the fold - without ever
   covering the content when the page is short.
   z-index: above the grey background of the booking dialog (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* 浅粉色 */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* 患者“我的专区”页面的两个大选项 */
.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);
}

/* 验证码图片(150 x 50 像素的 SVG) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}
  • 第 10–12 行:可预订的时间段在鼠标悬停时会变色;
  • 第 23–33 行:错误区域,背景为浅粉色。[position: sticky] 和 [bottom: 1rem]:如果页面比窗口高,该区域会停留在窗口底部,而不会滚出屏幕;[z-index] 将其置于预订窗口变灰的背景之上;
  • 第 36–43 行:“我的专区”的两个选项对鼠标悬停有响应;
  • 第 46–50 行:验证码(CAPTCHA)图片的边框。

11.19.2. static/js/app.js

// =========================================================================
// static/js/app.js - 应用中唯一的 JavaScript。
// -------------------------------------------------------------------------
// 整个应用无需 JavaScript 也能工作。该脚本增加了一项
// 便利功能:在发送带有属性
// data-confirmation="..." 的表单之前,会弹出模态对话框询问“确定吗?”
// (对话框本身在页面中:templates/fragments/confirmation.html)。
// 如果禁用了 JavaScript,表单就会不经
// 确认直接发送——不会有任何问题(“渐进增强”原则)。
//
// 为什么不用 window.confirm()?它的对话框无法设置样式,并且其
// 按钮保持浏览器的语言,而不是页面的语言。
// =========================================================================

(() => {
  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; // 用户确认时要发送的表单
  let previousFocus = null; // 关闭时要把焦点还给的元素

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent(而不是 innerHTML):消息作为文本显示,
    // 绝不会被解释为 HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // 焦点放在“否”上:心不在焉地按下 Enter 键不会删除任何东西
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. 我们拦截需要确认的表单的发送
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. 对话框的按钮(是 / 否 / 关闭叉号)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() 发送表单时不会再次触发
      // 'submit' 事件:不会再有新的确认请求
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // 点击灰色背景,即对话框之外
    }
  });

  // 3. 键盘:Escape 关闭对话框;Tab 停留在对话框内部
  //    (否则焦点会移到后面变灰的页面上)
  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();
      }
    }
  });
})();

这是示例 21 中确认窗口的脚本,增加了键盘处理。它遵循相同的渐进增强原则:没有 [JavaScript] 时,表单不经确认直接提交,应用仍然可以工作。

  • 第 15 行:整个脚本被包含在一个立即调用的函数中([(() => { ... })()]):其变量对页面上的其他脚本不可见;
  • 第 16–19 行:没有确认窗口的页面无事可做;
  • 第 24 行:在窗口打开之前拥有键盘焦点 (接收按键的元素)的那个元素:窗口关闭时,焦点会还给它;
  • 第 26–35 行:窗口打开时显示该表单专属的消息([form.dataset.confirmation] 是其 [data-confirmation] 属性的值);焦点放在“不,返回”上:误按 Enter 键不会删除任何东西;
  • 第 37–43 行:窗口被隐藏,焦点被恢复;
  • 第 46–51 行:带有属性 [data-confirmation] 的表单提交会被拦截,如示例 21 所示;
  • 第 54–67 行:“是”、“否”、关闭按钮,以及点击窗口外部。[closest('[data-action]')] 会找到带有该属性的元素,即使你点击的是其内部的某个元素。运算符 [?.] 在找不到元素时返回 [undefined] ,而不是失败;
  • 第 71–86 行:Esc 键关闭窗口;Tab 键(以及 Shift+Tab)使焦点在窗口内的按钮之间循环,而不是让它移到后面变灰的页面上。