# SpringBoot4系列28 - 集成Thymeleaf服务端渲染
公司内部的运营后台十有八九长一个样：商品录入、审批列表、参数配置页，页面结构简单，交互以表单提交加刷新列表为主。这种页面用前后端分离去做，我要维护两套代码、一条接口约定，还得排一次联调，投入产出比实在不划算。说实话，把页面拼装放回服务端，一个工程、一套部署就能交付，这类内部工具我一律上 Thymeleaf。Spring 官方对模板技术的推荐位很多年前就给了它：自然的 HTML 原型（直接双击就能打开）、与 Spring MVC 的表单绑定、开箱即用的 Bean Validation 错误回显，都是我需要的东西。
本篇我在 Spring Boot 4.1.1（Spring Framework 7.0.9、JDK 21.0.10）上从 starter 组成与自动配置包名取证开始，搭一个商品运营后台：列表分页、新增/编辑表单带六种校验注解、提交后重定向闪属性。文里的状态码与页面片段全部来自同一份端到端验证脚本打出来的原始记录，关键证据我都留了底，你可以照着复算；配套工程 springboot4-thymeleaf，端口 18280。
## 依赖与自动配置事实
工程只引三个 starter，我先把依赖贴出来：
```xml
org.springframework.boot
spring-boot-starter-webmvc
org.springframework.boot
spring-boot-starter-thymeleaf
org.springframework.boot
spring-boot-starter-validation
```
`spring-boot-starter-thymeleaf` 在 Boot 4.1.1 里没有改名，但它的 POM 实测只有两项 compile 依赖：`spring-boot-starter`（日志、自动配置基础）与 `spring-boot-thymeleaf`（模板引擎适配）。`spring-webmvc` 和内嵌 Tomcat 都不在其中，做 MVC 页面应用必须像上面这样叠加 `spring-boot-starter-webmvc`，只引 thymeleaf starter 起来的进程没有任何 Web 端点。这个坑我踩过一回：进程起来了，端口死活不通，翻了半天配置才发现 starter 没配对。
我解包 `spring-boot-thymeleaf-4.1.1.jar` 确认了三件事。其一，自动配置类在 `org.springframework.boot.thymeleaf.autoconfigure` 包下，`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 里注册的就是 `ThymeleafAutoConfiguration`，`ThymeleafProperties` 同包，找配置类按这个包名来。其二，属性前缀 `spring.thymeleaf.*` 保留，`prefix` 默认 `classpath:/templates/`、`suffix` 默认 `.html`，`cache`、`mode`、`check-template` 等字段照旧；例外是 `spring.thymeleaf.enabled` 已废弃，元数据标注 error 级别，给出的理由是直接依赖 Thymeleaf 本身即可关闭自动配置。其三，模板引擎与 Spring 的桥接件是 `thymeleaf-spring6:3.1.5.RELEASE`，Boot 4.1 官方就用它与 Framework 7.0.9 搭配，没有单独的 spring7 桥接包，这个组合是我从依赖树里实测确认的。
BOM 管理的版本线如下（`spring-boot-dependencies:4.1.1` POM 实测），做依赖仲裁时我直接查这份表：
| 项 | 版本 |
|---|---|
| thymeleaf / thymeleaf-spring6 | 3.1.5.RELEASE |
| thymeleaf-extras-springsecurity6 | 3.1.5.RELEASE |
| thymeleaf-layout-dialect | 4.0.1 |
| hibernate-validator | 9.1.3.Final |
| jakarta.validation-api | 3.1.1 |
表单校验这条线全部走 Bean Validation 标准：`spring-boot-starter-validation` 传递引入 `hibernate-validator:9.1.3.Final` 与 `jakarta.validation-api:3.1.1`，注解写在 `jakarta.validation.constraints` 包下。测试侧有个拆分要注意，BOM 里有 `spring-boot-starter-thymeleaf-test`，但它只携带 `spring-boot-starter-test` 的纯 JUnit 设施；要用 MockMvc 做页面断言，测试 starter 得换 `spring-boot-starter-webmvc-test`。我第一次就引错了，测试上下文里视图解析直接报失败，九成是这个原因。
`mvn dependency:tree` 打出来的 thymeleaf 分支值得贴一段，starter 的组成一目了然，挺有意思的是分支里连一个 servlet 容器节点都没有：
```text
+- org.springframework.boot:spring-boot-starter-thymeleaf:jar:4.1.1:compile
| +- org.springframework.boot:spring-boot-starter:jar:4.1.1:compile
| \- org.springframework.boot:spring-boot-thymeleaf:jar:4.1.1:compile
| \- org.thymeleaf:thymeleaf-spring6:jar:3.1.5.RELEASE:compile
| \- org.thymeleaf:thymeleaf:jar:3.1.5.RELEASE:compile
```
看完这棵树，「必须叠加 webmvc starter」的结论就是铁证了。Boot 把自动配置从单体 jar 拆到各模块之后，每个 starter 的真实内容都要以依赖树为准，POM 描述与名字容易给人过时的印象，我现在的习惯是先跑 tree 再下结论。
模板文件的存放位置默认在 `src/main/resources/templates/`，静态资源在 `src/main/resources/static/`。本工程的完整布局是模板三页加一个片段库：
```text
src/main/resources/
├── templates/
│ ├── fragments/layout.html # head / nav / footer 三个片段
│ └── products/
│ ├── list.html # 列表页
│ └── form.html # 新增与编辑共用
├── static/css/style.css
├── messages.properties # typeMismatch 中文文案
└── application.yml
```
控制器返回的视图名 `products/list` 会按 `spring.thymeleaf.prefix + 视图名 + spring.thymeleaf.suffix` 解析成 `classpath:/templates/products/list.html`。记住这一条解析规则，后面排查模板找不到的问题全靠它。
## 模板组织：片段复用与布局
页面不多时我不引 thymeleaf-layout-dialect，用 `th:fragment` 加 `th:replace` 自己拼布局就够。工程把公共骨架放进 `templates/fragments/layout.html`：
```html
商品管理
```
`th:fragment="head(title)"` 声明了一个带参数的片段，`title` 是参数名；`th:href="@{/css/style.css}"` 是链接表达式，部署在带 context-path 的路径下时会自动补前缀。导航条里的 `appName` 来自一个 `@ControllerAdvice` 的 `@ModelAttribute` 方法，所有视图不用重复传这个属性：
```java
@ControllerAdvice
public static class GlobalPageAdvice {
@ModelAttribute("appName")
public String appName() {
return "商品运营后台";
}
}
```
控制器 advice 在每个请求渲染前执行 `@ModelAttribute` 方法，返回值以 `appName` 为 key 放进模型，任何模板里都能直接取，我不必在每个控制器方法里手写一遍。
列表页复用这三个片段的方式：
```html
商品管理
```
`th:replace` 把当前标签整体替换成目标片段，`~{fragments/layout :: head('商品列表')}` 的意思是取 layout.html 里名为 head 的片段并传入标题参数。被替换的标签写什么内容都无所谓，我一律写空标签，让模板文件保持安静。表格主体是模板引擎的经典用法：
```html
| 1 |
商品名 |
0.00 |
编辑 |
```
`th:each` 遍历模型里的分页切片，`th:text` 输出前做 HTML 转义，商品名称里出现尖括号也不会破坏页面；要输出未转义的富文本才用 `th:utext`。`#numbers` 是内置工具对象，`formatDecimal(p.price, 1, 2)` 把价格固定成两位小数。翻页链接带查询参数：
```html
上一页
```
`@{/products(page=..., keyword=...)}` 的括号语法生成带查询参数的 URL 并做 URL 编码，`th:if` 控制页码越界时不渲染无效链接。
翻页链接背后的分页切片在服务里完成，模板拿到的永远是收敛过的安全值：
```java
public Page page(int page, int size, String keyword) {
int safeSize = Math.max(1, Math.min(size, MAX_PAGE_SIZE));
List all = search(keyword);
int totalPages = Math.max(1, (all.size() + safeSize - 1) / safeSize);
int safePage = Math.max(1, Math.min(page, totalPages));
int from = (safePage - 1) * safeSize;
int to = Math.min(from + safeSize, all.size());
return new Page(all.subList(from, to), safePage, safeSize, all.size(), totalPages);
}
```
页码与页大小两个入参都被夹进有效区间，用户手输 `page=999` 或 `size=0` 时页面照常渲染最后一页。我的原则是查询参数的防御放在服务层，模板表达式不适合承担判断逻辑。
分类下拉框是另一个模板常用形态，选项列表来自服务的常量：
```html
```
`th:field` 挂在 select 上时自动给匹配当前值的 option 补 `selected` 属性，编辑页打开时下拉框停在已选分类上。`T(...)` 是 SpringEL 的静态成员语法，选项列表固定时用它免去每个请求手工传模型；选项动态变化时就得改成控制器放进模型再传。
## 表单绑定与校验
服务端渲染的表单校验分三层：注解校验、类型转换、业务校验，三层失败都走同一条回显通道。表单对象我让它独立于实体定义，模板只面对它做绑定：
```java
public class ProductForm {
private Long id;
@NotBlank(message = "商品名称不能为空")
@Size(min = 2, max = 20, message = "商品名称长度需在 {min} 到 {max} 个字符之间")
private String name;
@NotBlank(message = "商品分类不能为空")
@Pattern(regexp = "DIGITAL|BOOKS|CLOTHING|FOOD", message = "商品分类必须是预置的四类之一")
private String category;
@NotNull(message = "售价不能为空")
@DecimalMin(value = "0.01", message = "售价必须大于 0")
private BigDecimal price;
@NotNull(message = "库存不能为空")
@Min(value = 0, message = "库存不能为负数")
private Integer stock;
@Size(max = 50, message = "简介不能超过 {max} 个字符")
private String summary;
}
```
六个注解覆盖了常用形态：`@NotBlank` 管非空，`@Size` 管长度区间，`@Pattern` 管正则枚举，`@NotNull` 与 `@DecimalMin` 管数值，`@Min` 管整数下限。注解消息里的 `{min}`、`{max}` 占位符由校验实现自动替换。表单对象与实体分离还有个实际好处：新增和编辑共用一个类型，字段增减只改一处。
控制器里 POST 方法把校验结果和表单对象一起接住：
```java
@PostMapping
public String create(@Valid @ModelAttribute("form") ProductForm form,
BindingResult binding,
RedirectAttributes redirectAttributes) {
if (productService.existsByName(form.getName(), null)) {
binding.rejectValue("name", "Duplicate", "同名商品已存在");
}
if (binding.hasErrors()) {
return "products/form";
}
Product created = productService.create(form);
redirectAttributes.addFlashAttribute("message", "已新增商品：" + created.getName());
return "redirect:/products";
}
```
这段代码有三个细节要说清。`@Valid` 与紧随其后的 `BindingResult` 参数必须成对出现且顺序相邻，Spring 把校验失败收集进 `BindingResult` 而不抛异常；漏写这个参数，校验失败会直接抛 `BindException` 变成 400 白页。`rejectValue` 是注解之外的补充通道，重名检查要查仓储才能下结论，检查完把错误挂到 `name` 字段上，模板侧的回显代码与注解错误完全一致。`hasErrors()` 为真时返回表单页视图名，这就是「校验失败回显」的落点，状态码保持 200。
模板侧的绑定与错误展示：
```html
```
`th:object="${form}"` 声明表单对象后，`th:field="*{name}"` 用选择表达式取字段，一次性完成三件事：生成 `name="name"` 与 `id="name"` 属性、把当前值渲染成 `value` 属性、在字段出错时把错误信息注册进 `#fields` 上下文。`th:errorclass` 在该字段有错时才追加上去的样式类，输入框自动标红。`th:errors="*{name}"` 输出该字段的全部错误消息，注解校验、类型转换、`rejectValue` 挂上去的错误都在其中。
类型转换失败的处理容易被漏掉：价格输入框传上来的是字符串，`abc` 转不成 `BigDecimal`，Spring 会把 `typeMismatch` 错误码挂到字段上，默认消息是英文，直接漏出去就是一屏英文报错。把消息解析接到 Spring 的 `MessageSource`，再补一个资源文件就能中文化：
```java
@Bean
public MessageSource messageSource() {
ReloadableResourceBundleMessageSource source = new ReloadableResourceBundleMessageSource();
source.setBasename("classpath:messages");
source.setDefaultEncoding("UTF-8");
return source;
}
@Bean
public LocalValidatorFactoryBean validator(MessageSource messageSource) {
LocalValidatorFactoryBean factoryBean = new LocalValidatorFactoryBean();
factoryBean.setValidationMessageSource(messageSource);
return factoryBean;
}
```
`LocalValidatorFactoryBean` 把 Bean Validation 的消息解析委托给 Spring 容器，`typeMismatch` 与注解消息走同一套解析。
```properties
typeMismatch.java.math.BigDecimal=售价格式不正确，请输入数字
typeMismatch.java.lang.Integer=库存格式不正确，请输入整数
```
错误码按「类型转换错误码 + 目标类型全限定名」匹配，`price` 字段收到 `abc` 时回显「售价格式不正确，请输入数字」。
编辑页的进入逻辑与新增页对称，区别在于要把实体字段拷进表单对象：
```java
@GetMapping("/{id}/edit")
public String editForm(@PathVariable Long id, Model model) {
Product product = productService.getById(id);
ProductForm form = new ProductForm();
form.setId(product.getId());
form.setName(product.getName());
form.setCategory(product.getCategory());
form.setPrice(product.getPrice());
form.setStock(product.getStock());
form.setSummary(product.getSummary());
model.addAttribute("form", form);
return "products/form";
}
```
字段拷贝看着笨拙，表单对象与实体分离的工程里这一步躲不掉，字段多时用 BeanUtils 之类工具类收敛。拷贝之后 `th:field` 在渲染时从表单对象取值，输入框的 `value` 属性自动带上实体现值，实测编辑页 `value="无线鼠标"` 就是这么来的。
工程配置极简，`application.yml` 只有端口与两个开发期属性：
```yaml
server:
port: ${SERVER_PORT:18280}
spring:
application:
name: springboot4-thymeleaf
thymeleaf:
cache: false
encoding: UTF-8
```
`cache: false` 只为改模板后刷新即见，生产环境保持默认。`encoding` 指定模板读取编码，中文页面固定 UTF-8。
## 提交-重定向-闪属性
表单提交成功后直接渲染列表页会有一个经典的重复提交问题：提交后的浏览器停留在 POST 响应上，刷新一次就重复入库一次。Post-Redirect-Get 模式是标准解法，Spring MVC 里一行返回值：
```java
redirectAttributes.addFlashAttribute("message", "已新增商品：" + created.getName());
return "redirect:/products";
```
返回值以 `redirect:` 开头时，Spring MVC 返回 302 状态码并把目标地址写进 `Location` 头，浏览器对列表页重新发起 GET。`addFlashAttribute` 把属性放进 FlashMap，FlashMap 在重定向前暂存于会话，目标请求被控制器处理前取出合并进模型，用完即焚，刷新列表页不会再看到成功提示。列表页的消费端只有一行：
```html
操作成功
```
`th:if` 判空，没有闪属性时这个提示块不会出现在 HTML 里。新增与编辑共用 `form.html`，提交地址按 `form.id` 区分：
```html