Thymeleaf 是 Spring Boot 官方推荐的服务端模板引擎。它最大的优势是：HTML 既是静态原型，又是动态模板——前端可以直接在浏览器打开调试，后端启动后又能自动注入数据，极大提升协作效率。
下面通过几个典型场景，带你快速上手 Thymeleaf 的日常用法。
- 注意：别用 @RestController！
使用 Thymeleaf 渲染页面时，Controller 必须使用 @Controller，而不是 @RestController。
java
@Controller // ✅ 正确
public class PageController {
@GetMapping("/home")
public String home() {
return "index"; // 返回 templates/index.html
}
}
❌ 如果用了 @RestController，Spring 会把 "index" 当作字符串直接返回，而不是去加载 index.html 页面。
- 自定义错误页（404 / 500）
Spring Boot 会自动识别 templates/error/ 目录下的错误页面：
404.html → 路径不存在
500.html → 服务器内部错误
例如：
html
<!DOCTYPE html>
页面走丢了 😢
只要放在正确目录，无需额外配置，系统会自动跳转。
- 渲染单个对象
后端通过 Model 传递数据：
java
@GetMapping("/blogger")
public String getBlogger(Model model) {
Blogger blogger = new Blogger(1L, "张三", "123456");
model.addAttribute("blogger", blogger);
return "blogger";
}
前端页面（blogger.html）使用 Thymeleaf 表达式取值：
html
<!DOCTYPE html>
姓名：默认名
取值方式对比：
写法 说明
${blogger.name} 推荐，直接访问属性（支持 getter）
${blogger.getName()} 调用方法（不常用）
{name} 需配合 th:object="${blogger}" 使用，适用于表单绑定
⚠️ {} 语法仅在 th:object 作用域内有效。
- 遍历 List 列表
后端传一个列表：
java
@GetMapping("/bloggers")
public String getList(Model model) {
List list = Arrays.asList(
new Blogger(1L, "张三", "xxx"),
new Blogger(2L, "李四", "yyy")
);
model.addAttribute("bloggers", list);
return "list";
}
前端用 th:each 遍历：
html
ID:
姓名:
❌ 在 th:each 循环中*不能使用 {}，因为没有 th:object 上下文。
- 常用 Thymeleaf 属性速查
属性 用途 示例
th:text 替换元素文本 默认
th:value 设置 input 值
th:href 动态链接 个人中心
th:src 图片/资源路径
th:if 条件显示
th:unless 反向条件
th:each 循环
th:action 表单提交地址
所有 @{...} 表示 URL 表达式，会自动处理上下文路径。
- 开发小贴士
关闭缓存**（开发时必须）：
yaml
spring:
thymeleaf:
cache: false
模板文件默认放在 src/main/resources/templates/；
静态资源（CSS/JS/图片）放在 src/main/resources/static/；
浏览器可直接打开 HTML 查看静态效果，Thymeleaf 属性会被忽略。
结语
Thymeleaf 不追求炫技，而是解决实际问题：
✅ 让前端写原型无依赖，
✅ 让后端渲染数据无负担，
✅ 让团队协作更顺畅。
