1. 简介
本文档的 PDF 在 |此处|。
本文档的代码在 |此处|。
本文档由 Anthropic 的 AI Claude 创作。它承接文档 “[ASP.NET Core MVC] Web 框架分步入门”(2026 年),而该文档又承接了文档 “[NestJS] Web 框架分步入门”(2026 年)。本文档将 [ASP.NET Core MVC] 课程改编到 [Java] 环境中:
- [ASP.NET Core MVC] 框架和 [C#] 语言被替换为 [Spring MVC] 框架、[Spring Boot] 4 以及 [Java] 21 语言;
- [Razor] 视图被替换为 [Thymeleaf] 视图;
- ORM [Entity Framework Core] 被替换为 [Spring Data JPA] 以及 ORM [Hibernate],数据库仍然基于 [MySQL]。
本文档紧密遵循 [ASP.NET Core MVC] 课程的进度:先是大量小项目,每个项目聚焦于一个概念,然后是一个完整的案例研究——一个用于医疗诊所预约排期的 Web 应用程序,所有文件都带有完整注释。这些示例的编号和主题与 [ASP.NET Core MVC] 课程相同:熟悉该课程的读者可以逐个示例地比较这两个框架。不过这并非必需:本文档自成一体,不要求读者事先了解 [ASP.NET],当然也不要求了解 [Spring]。唯一的先决条件是具备 Web 编程的基本知识(HTTP 协议、HTML 语言)以及 [Java] 语言。
1.1. Spring MVC 在 Web 应用程序中的作用
Web 应用程序通常按层构建,每一层只与相邻的层通信:

- Web 层接收来自浏览器的 HTTP 请求,并向其返回 HTML 页面。[Spring MVC] 帮助我们编写这一层;
- 业务层包含应用程序的业务规则(例如“一位患者只能有一个即将到来的预约”)。它对 Web 一无所知:它同样可以为命令行应用程序提供服务;
- 数据访问层([DAO] 层,即 [Data Access Object])负责读写数据库。我们将使用 [Spring Data JPA],它依赖 ORM [Hibernate]([Object Relational Mapper])将表中的行与 [Java] 中的对象相互映射。
Web 层本身遵循 [MVC] ([Model – View – Controller])模型:
- 控制器(C)是一个类,其方法称为 动作,每个动作处理一种特定类型的请求(例如 [GET /schedule])。动作读取请求参数,调用业务层,然后选择要显示的视图;
- 模型(M)是动作传递给视图的数据集合;
- 视图(V)是一个 [Thymeleaf] 文件(扩展名为 [.html]):这是一个 HTML 页面,其中某些标签带有 [th:...] 属性([th:text]、[th:each]……),[Thymeleaf] 引擎会用模型中的数据替换这些属性。
请求的处理过程遵循图中的编号步骤:
- 1:浏览器发送一个 HTTP 请求,例如 [GET /schedule?doctorId=1&day=2026-09-24];
- 2:由 [Tomcat] Web 服务器(由 [Spring Boot] 嵌入应用程序中)接收请求。请求先经过一系列 过滤器 (读取 Cookie、身份验证等),然后到达 [DispatcherServlet],它是 [Spring MVC] 的唯一入口,负责选择处理该请求的动作:这就是 路由。在到达动作之前,请求还可能经过 拦截器,我们将在后面的章节中探讨;
- 3:动作向业务层请求所需的数据;必要时,业务层会联系 [DAO] 层,由该层用 SQL 查询 [MySQL] 数据库;
- 4:动作构建视图模型 M,并指定应显示该模型的视图;
- 5:视图引擎 [Thymeleaf] 生成页面 HTML,[Spring MVC] 再将其返回给浏览器。
[Spring] 是全球使用最广泛的企业应用开发框架([Java]) 。它免费开源,凡是 [Java] ([Windows]、[Linux]、[macOS])能运行的地方都能运行。[Spring MVC] 是其中的 Web 组件;[Spring Boot] 是一个上层封装,它根据项目中存在的库自动配置整套环境(Web 服务器、JSON 转换、视图引擎、数据访问等),并把应用程序变成一个标准的 [Java] 程序,由 [main] 方法启动。[Spring MVC] 既可以创建向 [JavaScript] 客户端([Angular]、[React]、[Flutter]……)返回 JSON 的服务器,也可以创建传统的 Web 应用程序,即由服务器生成 HTML 页面,浏览器只负责显示。本文档聚焦于后一种用法。与 [ASP.NET Core] 一样,[Spring] 基于两个理念:注解 ([@GetMapping]、[@RequestMapping]、[@PreAuthorize]……)描述类和方法的角色,而 依赖注入 为每个对象提供其所需的依赖。[Spring] 事实上正是推广了第二个理念的框架之一。
1.2. 所用工具
这些示例使用以下工具编写和测试(安装方法见附录):
- [JDK] 21([Java Development Kit]),其中包含 [javac] 编译器和 [java] 虚拟机。[Java] 21 是一个 LTS(长期支持)版本;
- [Maven] 3.9.11 构建工具,无需安装:每个项目都包含一个 Maven Wrapper (脚本 [mvnw] 和 [mvnw.cmd]),首次使用时会自动下载正确版本的 [Maven] ;
- [Visual Studio Code] 编辑器,以及 [Extension Pack for Java] 和 [Spring Boot Extension Pack] 扩展;
- 一款较新的浏览器([Chrome]、[Firefox]、[Edge]);
- 命令行工具 [curl],用于显示原始的 HTTP 响应([Windows] 10 和 11 已自带);
- 数据库管理系统 [MySQL] (或 [MariaDB]),例如 [Laragon] 在 [Windows] 下附带的那个,从数据访问一章开始使用,并用于案例研究。
与包含 [.NET] 的 SDK(其中带有 [ASP.NET Core])不同,[JDK] 并不包含 [Spring]:该框架是一组库,由 [Maven] 在首次编译时从中央仓库 [Maven Central] 下载(因此那一天必须连接互联网),然后存放在本地文件夹中(用户主目录下的 [.m2] )。这些库被归并为 starter:一个 starter 就是一个依赖,它提供某项特定功能所需的一切。所有示例都使用 [spring-boot-starter-webmvc] ([Spring MVC] 和服务器 [Tomcat]);此外还有 [spring-boot-starter-validation] (数据验证,从第 3 章开始)、[spring-boot-starter-thymeleaf] (视图,从第 4 章开始)、[spring-boot-starter-security-oauth2-resource-server] ([Spring Security] 和 JWT 令牌,第 8 章)、[spring-boot-starter-data-jpa] 以及 [mysql-connector-j] 驱动(数据库访问,第 9 章)。所用版本为 [Spring Boot] 4.1.1 所对应的版本:[Spring Framework] 7.0.9、[Spring Security] 7.1.1、[Hibernate] 7.4.5、[Thymeleaf] 3.1.5、[Jackson] 3(JSON 转换)以及 [Tomcat] 11。
1.3. 运行案例研究
审阅者说明:我建议读者按照下面的说明立即完成案例研究。在充分理解这个预约排期应用程序的作用之后,请让你喜欢的 AI 按如下要求修改该应用程序:从现在起,每位医生将可以:
- 在两个日期之间设置自己的预约时段。这样他们可以根据需要调整自己的日程;
- 针对某一天,从日历中移除某些时间段——例如,当他们因个人原因无法出诊时;
这一修改并不简单,因为它涉及数据库结构的变更。请让 AI 为你提供新的应用程序代码以及创建新数据库的 SQL 脚本。为此,你需要向它提供包含完整项目的 ZIP 文件以及旧数据库的 SQL 脚本。
另外,我没有审阅过 Claude 创作的这门课程。他此前已经写出了两门完美的课程:[NestJS] 和 [ASP.NET Core MVC]。我想当然地认为这一门也是如此。如果你在理解某些内容时遇到困难,解决办法始终相同:请你喜欢的 AI 解释你不理解的地方。Claude 就非常擅长这一点。你可能需要把不理解的示例“上传”给它。
说明结束。
本文档末尾的案例研究是一个完整的应用程序。读者很可能希望在深入了解框架细节之前先看到它的运行效果:运行方法如下。它位于 [rdvmedecins2-spring-mvc] 文件夹中,与 [examples] 文件夹并列:
你必须已安装 [JDK] 21、[Visual Studio Code]和 [MySQL] (见附录)。[Maven] 无需安装。然后:
- 通过运行 [dbrdvmedecins2] 数据库的 创建脚本 [rdvmedecins2-spring-mvc/database/dbrdvmedecins2.sql] 来创建该数据库。使用 [Laragon] 时,打开 [HeidiSQL] 工具(Database 按钮),然后通过 File / Run SQL 菜单运行该脚本。在命令行中,在 [rdvmedecins2-spring-mvc] 文件夹下执行:
- 检查数据库连接。应用程序连接到 [MySQL] ,主机为 [localhost],端口 3306,用户为 [root] ,无密码 ([Laragon] 的默认设置)。如果你的 [root] 账户有密码,请将其填写到应用程序的 [src/main/resources/application.properties] 文件中 [spring.datasource.password=] 这一行(例如 [spring.datasource.password=myPassword])。为避免把密码写入项目文件,你也可以通过环境变量 [SPRING_DATASOURCE_PASSWORD] 来指定,它的优先级高于文件:[set SPRING_DATASOURCE_PASSWORD=myPassword] 用于 [Windows] (命令提示符),[export SPRING_DATASOURCE_PASSWORD=myPassword] 用于 [Linux] 和 [macOS];
- 在 [Visual Studio Code] 中打开文件夹 [rdvmedecins2-spring-mvc] (File 菜单 / Open Folder),然后打开终端(Terminal 菜单 / New Terminal);
- 在 [Linux] 和 [macOS] 下启动应用程序:
在 [Windows] 下:
- 首次运行时,Maven Wrapper 会下载 [Maven],然后 [Maven] 下载应用程序的库,这需要几分钟。随后应用程序被编译并启动。控制台会显示 [Spring Boot] 横幅,接着是启动消息(这里只列出了主要的几条):
每一行以日期和时间开头(此处用 [...] 代替),然后是消息级别([INFO]、[WARN]、[ERROR])、进程号和线程名(同样用 [...] 代替),最后是输出该消息的类的缩写名称。输出显示应用程序运行在 [dev] 配置文件下(一组开发专用的设置,其中包括显示 SQL 请求),[Tomcat] 服务器正在监听 8081 端口,数据库连接成功([HikariCP] 连接“池”已就绪),并且应用程序已经读取了医生和客户的列表(两条 SQL 请求)。在使用 [MariaDB] 时,[Hibernate] 还会显示一条警告 [HHH000511],它不会造成任何影响;
- 在浏览器中打开 URL [http://localhost:8081] :

- 使用其中一个演示账户登录,其密码与用户名相同:[admin] (管理员)、[pelissier]、[tatou]、[dupont] (医生)、[martin]、[durand]、[bistrou]、[german] (患者)。你还必须输入图片中的字符,大小写均可。
应用程序启动时会读取数据库:如果 [MySQL] 无法访问,应用程序会立即停止,控制台会显示原因。如果消息是 [Communications link failure] (或 [Connection refused]),说明 [MySQL] 尚未启动;如果是 [Access denied for user 'root'@'localhost'],说明密码不正确;如果是 [Unknown database 'dbrdvmedecins2'],说明 SQL 脚本尚未执行;如果是 [Port 8081 was already in use],说明 8081 端口已被占用(例如被该应用程序的 [ASP.NET Core] 版本占用);如果是 [release version 21 not supported] (或 [invalid target release: 21]),说明所安装的 [JDK] 版本低于 21。应用程序的 [README.md] 文件描述了其他情况。在终端中使用 [Ctrl-C] 停止应用程序。
本文档的最后一章说明如何使用该应用程序,然后逐一讨论它的每个文件。
1.4. 示例
示例存放在 [examples] 文件夹中,每个示例对应一个子文件夹:
每个示例都是一个可以独立编译和运行的 [Maven] 项目。[Maven] 项目由一个 [pom.xml] ([Project Object Model])文件描述:它的标识、所依赖的库(即其 依赖)以及构建方式。这 28 个项目是一个父项目的 模块 ,由文件 [examples/pom.xml] 描述。脚本 [mvnw] ([Linux]、[macOS])和 [mvnw.cmd] ([Windows])就是 Maven Wrapper;文件 [.mvn/wrapper/maven-wrapper.properties] 指定它必须下载的 [Maven] 版本(3.9.11)。
[common/bootstrap] 文件夹包含 CSS 和 [Bootstrap] 框架,由需要排版页面的示例共享(从示例 15 开始)。
每个示例都具有 [Maven] 项目的标准结构:
- [src/main/java]:[Java] 代码,按 包 组织([example13]、[example13/controllers]……文件夹)。[Java] 中的包相当于 [C#] 中的命名空间;包名反映其文件夹的路径([example13.controllers]);
- [Example13Application.java]:应用程序的启动类,包含 [main] 方法(见示例 01);
- [controllers]:控制器;
- [models]:描述模型的类(动作和视图的模型);
- [src/main/resources]:不属于 [Java] 代码的文件;
- [templates]:[Thymeleaf] 视图(从第 4 章开始);
- [application.properties]:应用程序配置(监听端口,以及之后的数据库连接等);
- [pom.xml]:项目文件,描述如何构建应用程序。
编译时,[Maven] 会在每个示例中创建一个名为 [target] 的文件夹,用于存放编译后的类;该文件夹可以放心删除。
要运行示例,请在示例文件夹中打开终端(在 [Visual Studio Code] 中:右键单击示例文件夹,然后选择“Open in the built-in terminal”),并在 [Linux] 和 [macOS] 下输入以下命令:
在 [Windows] 下:
Maven Wrapper 位于 [examples] 文件夹中,它是示例文件夹的父文件夹:因此使用 [../] (或 [..\])。命令 [spring-boot:run] 会编译示例(输出到其 [target] 文件夹),然后启动应用程序。所有示例都监听 5000 端口:同一时间只能运行一个。在终端中按 [Ctrl-C] 停止服务器。你也可以在 [examples] 文件夹中一次性编译所有示例,以验证安装是否完整:
(在 [Windows] 下使用 [mvnw compile] )。
在 [Visual Studio Code] 中打开 [examples] 文件夹时,[Extension Pack for Java] 扩展会找到父级 [pom.xml] 文件并导入所有模块(它们显示在“Java Projects”窗格中):这样每个文件中都有语法高亮、代码补全和错误提示。在默认设置下,它还会在你保存每个 [.java] 文件时立即编译它。[Spring Boot Extension Pack] 扩展增加了一个“Spring Boot Dashboard”窗格,它列出找到的应用程序,并允许你无需使用终端即可启动或停止它们(这些窗格的具体外观取决于扩展的版本)。最后,所有示例都依赖 [Spring Boot DevTools] (见下文):只要某个类被重新编译,正在运行的应用程序就会在一两秒内自动重启。因此在 [Visual Studio Code] 中,原则上只需保存修改过的文件,应用程序就会将其纳入。
父项目 [pom.xml] 文件 [examples/pom.xml]:
下面对该文件逐一说明:
- 第 14–19 行:父项目自身又继承自一个父项目 [spring-boot-starter-parent],版本为 4.1.1。该项目设定了 [Spring] 的所有库以及它们所用库的版本,这些版本经过挑选,可以协同工作:这就是后面的依赖都不需要指定版本的原因。它还控制编译过程(源代码的 UTF-8 编码、[Java] 的版本等)。空元素 [<relativePath/>] 表示该父项目不在相邻文件夹中,而必须到 [Maven] 仓库中查找;
- 第 22–24 行:项目的标识,包括组([groupId])、名称([artifactId])和版本。各模块使用这一标识来引用其父项目;
- 第 26 行:类型为 [pom] 的项目既不生成类,也不生成归档文件;它负责汇集各模块,并把自己的设置传递给它们;
- 第 28–31 行:[Java] 的目标版本:[Java] 21;
- 第 34–63 行:逐个列出各模块,例如它们的文件夹名称。在 [Maven] 文件夹 [examples] 中运行的命令会作用于所有模块;
- 第 66–78 行:所有示例共有的依赖,由每个模块继承;
- 第 68–71 行:starter [spring-boot-starter-webmvc] 提供 [Spring MVC]、嵌入应用程序中的 [Tomcat] Web 服务器(无需安装任何服务器),以及将 [Jackson] 库用于把 [Java] 对象转换为 JSON;
- 第 73–77 行:[Spring Boot DevTools],开发工具:类重新编译时自动重启应用程序、禁用缓存(如视图缓存),以及提供更详细的错误消息。它们仅用于开发:[Spring Boot] 插件(第 80–88 行)不会把它们打包进用于生产环境的可执行归档文件([.jar]),而且如果应用程序通过 [java -jar] 启动,它们会被自动禁用;
- 第 80–88 行:用于 [Maven] 的 [Spring Boot] 插件。该插件提供 [spring-boot:run] 命令,以及可执行归档文件的创建([mvnw package])。
示例中的 [pom.xml] 文件非常简短。例如 [01-structure/pom.xml]:
- 第 6–10 行:父项目——即 [examples] 项目,通过其 ID 标识。该模块继承它的依赖和设置,并通过它继承 [spring-boot-starter-parent] 的依赖和设置;
- 第 11 行:模块的名称。它的组和版本与父项目相同。
需要额外库的示例会在自己的 [pom.xml] 中声明它。例如 [13-first-view/pom.xml],它使用视图引擎 [Thymeleaf]:
- 第 3–6 行:依赖由其组和名称标识;它的版本由 [spring-boot-starter-parent] 设定。
在所有示例中,文件 [src/main/resources/application.properties] 的开头都是相同的:
- 第 2 行:服务器的监听端口。如果没有这一行,[Spring Boot] 会监听 8080 端口;我们选择了 5000 端口,即 [ASP.NET Core MVC] 课程中使用的端口;
- 第 4 行:请求失败时,[Spring Boot] 会返回一个错误响应(我们将在下一章讨论)。这个设置确保响应中永远不包含 调用栈 (出错时正在执行的方法列表),因为它会向攻击者暴露应用程序代码的信息。
每一行的形式为 [key=value];以 [#] 开头的行是注释。有些示例会在这两行之后加入自己的键。
最后,使用 [Bootstrap] 的示例是在 [common/bootstrap] 文件夹中找到它,而不是在自己的文件夹中:因此该文件只存在一份。这些示例中的每一个都有一个配置类,把这个文件夹发布在 URL [/bootstrap/...] 之下。例如 [15-layout/src/main/java/example15/config/WebConfig.java]:
- 第 8–9 行:[Spring MVC] 的配置类(示例 06 和 12 将解释这一机制);
- 第 14–18 行:以 [/bootstrap/] 开头的 URL 文件从相对于当前文件夹的 [../common/bootstrap/] 文件夹提供——也就是按上述方式启动时示例所在的文件夹。因此页面可以使用样式表 [/bootstrap/css/bootstrap.min.css]。第二个文件夹 [common/bootstrap/] 用于从 [examples] 文件夹而不是示例文件夹启动应用程序的情况。
1.5. 文档内容
本文档的结构如下:
章 | 内容 | 示例 |
控制器、动作与 | 从浏览器到动作:路由、响应、重定向、服务与依赖注入 | 01–06 |
动作模型 | 请求参数:绑定、转换、验证、POST 表单 | 07 至 12 |
视图及其模板 | Thymeleaf、模板、片段、表单、验证、PRG | 13 至 21 |
国际化 | 法语和英语双语应用程序 | 22 |
数据作用域 | 应用程序、请求、会话、客户端 | 23 |
请求的生命周期 | Servlet 过滤器、拦截器、[@ControllerAdvice]、模板绑定、错误页面 | 24 |
身份验证与授权 | Spring Security、Cookie 中的 JWT、角色、验证码(CAPTCHA)、尝试次数限制 | 25–27 |
分层架构 | 使用 Spring Data JPA 和 MySQL 的 Web / 业务 / DAO 分层 | 28 |
案例研究 | RdvMedecins 应用程序,逐个文件讲解 | - |
每个示例只引入少量新概念,各章前后衔接:最好按顺序阅读。而案例研究则运用了前面各章的 所有 概念:只要相关,它的讲解都会指向该概念首次出现的示例。附录介绍如何安装各种工具:[JDK] 21、[Visual Studio Code] 及其扩展、Maven Wrapper、[MySQL] 与 [Laragon],以及 [curl]。