在现代Java Web开发领域，选择合适的模板引擎是提升开发效率和维护性的关键一步。作为Spring Boot官方推荐的视图技术，Thymeleaf凭借其“自然模板”特性（HTML原生语法、无需编译即可预览）以及与Spring生态的无缝集成，已成为构建动态页面的首选方案。本文将从实战角度出发，深入剖析Thymeleaf的核心机制、高级特性与最佳实践，助你全面掌握这一强大工具。

一、Spring Boot与Thymeleaf的无缝整合

与传统的JSP或Freemarker相比，Thymeleaf在Spring Boot中的集成堪称“开箱即用”。其核心优势在于对HTML5的完全兼容，模板文件本身就是标准的HTML，这为前后端协作和静态原型预览带来了极大便利。对于习惯使用TypeScript或JavaScript进行前端开发的工程师来说，这种不破坏HTML结构的特性使得模板逻辑更清晰。

整合的第一步是在项目的构建文件中添加依赖。在Maven项目的pom.xml中，只需引入Spring Boot的Thymeleaf启动器，版本管理由Spring Boot自动完成：


    org.springframework.boot
    spring-boot-starter-thymeleaf

Spring Boot通过自动配置类ThymeleafAutoConfiguration为Thymeleaf设置了合理的默认值。了解这些默认配置有助于后续的定制化开发。核心配置参数如下表所示：

配置项默认值说明
模板文件存放路径
模板文件后缀
UTF-8模板编码
true（生产）/false（开发）模板缓存（开发时关闭避免重启）
HTML模板解析模式（支持 HTML5、XML 等）

在实际开发中，我们通常需要在application.properties中进行一些调整，例如关闭缓存以确保模板修改实时生效：

# 关闭模板缓存（开发必备）
spring.thymeleaf.cache=false
# 自定义模板前缀（默认 classpath:/templates/）
spring.thymeleaf.prefix=classpath:/templates/views/
# 自定义模板后缀（默认 .html）
spring.thymeleaf.suffix=.html
# 编码格式
spring.thymeleaf.encoding=UTF-8
# 解析模式（HTML5 兼容非严格语法）
spring.thymeleaf.mode=HTML5

一个最小化的示例能快速验证整合是否成功。首先，在resources/templates目录下创建模板文件hello.html，并务必引入Thymeleaf命名空间：




    
    Thymeleaf 示例


    
默认欢迎语

接着，编写一个简单的Controller来向模板传递数据：

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class ThymeleafController {
    @GetMapping("/success")
    public String success(Model model) {
        // 向模板传递数据（Model 本质是请求域）
        model.addAttribute("welcomeMsg", "Hello Thymeleaf!");
        // 返回模板名称（无需后缀，自动拼接 prefix + 名称 + suffix）
        return "success";
    }
}

启动应用并访问对应路径，页面将成功渲染出“Hello, Thymeleaf!”。这个简单的流程展示了Thymeleaf与Spring MVC协同工作的基本模式。

二、核心语法：表达式体系与常用标签

Thymeleaf的动态渲染能力核心在于其丰富的表达式，这些表达式均写在以th:开头的属性中。它主要支持五大类表达式，构成了模板逻辑的基石：

表达式类型语法作用
变量表达式读取 Model/Request/Session/Application 中的数据（Spring EL 语法）
选择表达式基于 选择对象，简化属性访问
国际化表达式读取国际化配置文件（.properties）中的文本
URL 表达式生成绝对 / 相对 URL，自动拼接上下文路径（无需手动加项目名）
片段表达式引用模板片段（布局复用）

其中，变量表达式（${...}）和选择表达式（*{...}）最为常用。变量表达式用于读取各种作用域中的数据，其查找优先级为：Request > Session > Application。选择表达式则通常与th:object绑定，用于简化表单对象属性的访问。



默认用户名



默认年龄



默认应用名



默认状态

    
    用户名
    
    年龄
    
    性别

对于需要国际化的项目，消息表达式（#{...}）至关重要。它使得文本内容与代码分离，管理多语言资源文件变得轻松。而链接表达式（@{...}）能智能处理上下文路径，彻底解决了URL硬编码的部署难题。

spring.messages.basename=i18n.messages
spring.messages.encoding=UTF-8


默认欢迎语



默认问候

用户列表

用户详情

百度

表达式内部并非简单的变量占位，它支持强大的语法扩展，包括算术运算、逻辑比较、三元运算符等，足以应对复杂的渲染逻辑：

类型语法示例
字面量文本：、数字：、布尔：、空：
文本操作拼接：、替换：`姓名：${user.name}（更简洁）
算术运算（如 ）
布尔运算（如 ）
比较运算、（如 ）
条件运算三元：、默认值：

示例：

除了表达式，Thymeleaf提供了一系列th:标签来覆盖原生HTML标签的行为，实现条件渲染、循环遍历等功能。以下是开发中的高频标签列表：

标签核心作用实战示例
替换文本（转义 HTML）（ 会被转义为 ）
替换文本（不转义 HTML）（ 会渲染为标题）
循环遍历（集合 / 数组）（stat 是状态变量）
条件渲染（为 true 时显示）
条件渲染（为 false 时显示）
/多分支判断
设置表单元素 value
设置下拉框选中状态
设置 CSS 类名（支持动态判断）
设置图片 / 脚本路径（结合 @{}）
设置点击事件（支持动态参数）
定义模板片段（复用）
替换标签引入片段（推荐）

这里重点剖析两个最强大的标签。th:each循环标签支持状态变量，为列表渲染提供了丰富的上下文信息，如索引、计数、奇偶行判断等，非常适合制作表格：


    

        序号
        用户名
        密码

布局复用标签（th:insert/th:replace/th:include）是实现页面组件化的关键。三者都用于引入模板片段，但行为略有不同：th:replace会替换当前标签，th:insert将片段插入当前标签内部，而th:include已被标记为废弃。通常推荐使用语义最清晰的th:replace。




    
    

        
网站页眉

        
    

    
    

        
默认版权信息

    






    
    布局示例


    
    

    
页面主体内容
[AFFILIATE_SLOT_1]

三、高级特性与Spring深度集成

Thymeleaf的高级特性使其超越了简单的模板渲染，成为Spring生态中的得力助手。例如，它可以直接在模板中操作Web作用域，无需完全依赖Controller中转：

此外，Thymeleaf内置了功能强大的工具类（以#为前缀），覆盖了字符串、日期、集合、数组等常见操作。这类似于Python或Go语言标准库提供的工具函数，允许开发者在视图层直接处理数据，减少后端逻辑的复杂度：

工具类作用示例
字符串操作、
日期格式化
数字格式化（保留 2 位小数）
集合操作、
对象操作

工具类使用示例：












暂无数据

与Spring MVC的表单绑定是Thymeleaf的杀手锏之一。它能自动完成数据回显、绑定校验错误，极大简化了表单开发流程。其背后的原理与Spring的数据绑定机制深度集成。

public class UserForm {
    private String username;
    private String password;
    private Integer age;
    // getter/setter 省略
}
@GetMapping("/form")
public String form(Model model) {
    // 初始化表单对象（用于回显）
    UserForm form = new UserForm();
    form.setUsername("默认用户名");
    model.addAttribute("userForm", form);
    return "form";
}
@PostMapping("/form/save")
public String save(@ModelAttribute UserForm userForm) {
    // 处理表单提交
    System.out.println(userForm);
    return "success";
}

    
    

        用户名：
    

    
    

        密码：
    

    
    

        年龄：

在错误处理方面，Thymeleaf能与Spring Boot的错误页面机制完美结合。在resources/templates/error/目录下创建如404.html、5xx.html的模板，Spring Boot会自动将其用作对应状态码的错误页面。在模板中，可以通过${status}等变量获取详细的错误信息。




    
    404


    
页面找不到啦 

    
错误码：

    返回首页

四、实战技巧、性能优化与避坑指南

掌握基础语法后，一些实战技巧能让你事半功倍。 开发调试阶段，务必设置spring.thymeleaf.cache=false并考虑使用spring-boot-devtools实现热部署，避免频繁重启。引用静态资源（CSS、JS、图片）时，应使用@{...}表达式指向/static、/public等标准目录。

在开发过程中，开发者常会遇到一些“坑”：⚠️ 忘记在HTML根标签添加Thymeleaf命名空间，导致所有表达式失效；⚠️ 需要渲染HTML内容时错误使用了th:text（会转义），而应该使用th:utext；⚠️ 在th:each中声明状态变量时，顺序应为“迭代变量 : 状态变量”。

当应用进入生产环境，性能优化成为重点。✅ 必须开启模板缓存（spring.thymeleaf.cache=true），这是最重要的性能提升手段。✅ 积极使用th:replace或th:insert复用页头、页脚、导航栏等公共片段，减少代码冗余。✅ 遵循“控制器处理复杂逻辑，模板专注渲染”的原则，避免在模板中编写过于复杂的表达式或业务逻辑，这与C++或大型JavaScript项目中提倡的关注点分离思想一致。

[AFFILIATE_SLOT_2]

五、完整项目实战示例

为了将上述知识融会贯通，这里提供一个完整的用户信息展示与表单提交的实战示例。该示例涵盖了实体类、控制器和模板的完整代码，展示了Thymeleaf在实际项目中的典型应用。

1. 实体类（User.java）：定义数据模型。

public class User {
    private String username;
    private String password;
    private Integer age;
    private Integer score;
    private Integer gender;
    private Date birthday;
    // getter/setter 省略
}

2. 控制器（ThymeleafDemoController.java）：处理请求和业务逻辑。

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
@Controller
public class ThymeleafDemoController {
    @GetMapping("/demo")
    public String demo(Model model) {
        // 单个用户
        User user = new User();
        user.setUsername("张三");
        user.setPassword("123456");
        user.setAge(20);
        user.setScore(88.5);
        user.setGender(1);
        user.setBirthday(new Date());
        // 用户列表
        List userList = new ArrayList<>();
        for (int i = 0; i < 5; i++) {
            User u = new User();
            u.setUsername("用户" + i);
            u.setPassword("pwd" + i);
            u.setAge(18 + i);
            u.setScore(60 + i * 5);
            u.setGender(i % 2);
            u.setBirthday(new Date());
            userList.add(u);
        }
        model.addAttribute("user", user);
        model.addAttribute("userList", userList);
        return "demo";
    }
}

3. 模板（demo.html）：负责数据的最终渲染和展示。




    
    Thymeleaf 实战示例
    


    
单个用户信息

    

        
用户名：

        
年龄：（）

        
性别：
            男
            女
        

        
分数：

        
生日：

    

    

    
用户列表

    

        

            序号
            用户名
            年龄
            分数等级

总结

Thymeleaf作为Spring Boot生态的首选模板引擎，其价值在于“自然模板”的友好性和与Spring的深度集成。开发者需要掌握其核心表达式（变量、选择、链接、片段）和高频标签（条件、循环、替换），并善用内置工具类简化前端逻辑。从开发到部署，牢记关闭/开启缓存的配置区别，积极复用模板片段以提升可维护性。通过本文的深度解析与实战指南，相信你已具备运用Thymeleaf高效构建现代Java Web应用的能力，足以应对绝大多数企业级开发场景。

prefixclasspath:/templates/suffix.htmlencodingcachemode${...}*{...}th:object#{...}@{...}~{...}'张三'18true/falsenull'姓名：' + ${user.name}+、-、*、/、%${user.age + 1}and/or/not${user.age > 18 and user.gender == 1}>、<、>=、<=（gt/lt/ge/le）==、!=（eq/ne）${user.score ge 60}${user.age > 18 ? '成年' : '未成年'}${user.nickname ?: '匿名'}th:text<p th:text="${user.desc}">默认描述</p><h1>&lt;h1&gt;th:utext<p th:utext="${user.htmlDesc}">默认描述</p><h1>th:each<tr th:each="u, stat : ${userList}">th:if<div th:if="${user.age > 18}">成年</div>th:unless<div th:unless="${user.age > 18}">未成年</div>th:switchth:case<div th:switch="${user.role}"><p th:case="admin">管理员</p></div>th:value<input th:value="${user.username}" />th:selected<option th:selected="${u.id eq selectedId}">${u.name}</option>th:class<div th:class="${user.age > 18 ? 'adult' : 'teen'}">th:src<img th:src="@{/img/avatar.png}" />th:onclick<button th:onclick="editUser(${user.id})">编辑</button>th:fragment<div th:fragment="header">页眉</div>th:replace<div th:replace="~{common :: header}"></div>#strings#strings.isEmpty(user.name)#strings.toUpperCase(user.name)#dates#dates.format(user.birthday, 'yyyy-MM-dd')#numbers#numbers.formatDecimal(user.score, 1, 2)#lists#lists.isEmpty(userList)#lists.size(userList)#objects#objects.nullSafe(user.nickname, '匿名')