董云舟1. Thymeleaf是什么？为什么选择它？
Thymeleaf是一个现代化的Java服务器端模板引擎，它允许开发者在Web和非Web环境中处理HTML、XML、JavaScript、CSS甚至纯文本。与传统的JSP或Freemarker相比，Thymeleaf最大的特点是它支持"自然模板"的概念——模板文件可以直接在浏览器中打开和显示，而不需要启动服务器。
我第一次接触Thymeleaf是在2015年，当时正在为一个电商项目寻找替代JSP的方案。JSP的编译问题和与前端协作的困难让我们团队苦不堪言。Thymeleaf的出现彻底改变了这种状况——它的模板就是普通的HTML文件，前端开发者可以直接在浏览器中查看静态效果，而后端开发者又能通过Thymeleaf的属性动态填充数据。
1.1 Thymeleaf的核心优势
-
自然模板：Thymeleaf模板是有效的HTML5文档，可以直接在浏览器中预览，无需服务器渲染。这是通过Thymeleaf的特殊属性（如
th:text）实现的，这些属性在静态预览时会被忽略，在服务器渲染时才会生效。 -
强大的表达式语言：Thymeleaf使用OGNL（Object-Graph Navigation Language）和Spring EL（Expression Language）作为表达式引擎，支持复杂的对象图导航和方法调用。
-
与Spring生态无缝集成：作为Spring官方推荐的模板引擎，Thymeleaf与Spring MVC、Spring Boot深度集成，配置简单，功能强大。
-
模块化设计：Thymeleaf由多个模块组成，可以单独使用模板解析引擎，也可以使用完整的标准方言，还可以自定义方言扩展功能。
-
国际化支持：内置强大的国际化功能，支持消息表达式和区域解析。
1.2 适用场景分析
Thymeleaf特别适合以下场景：
- 前后端协作开发：前端可以独立开发静态页面，后端只需添加Thymeleaf属性即可实现动态渲染。
- 传统MVC架构应用：特别是基于Spring框架的Web应用。
- 需要SEO友好的页面：因为Thymeleaf最终输出的是标准的HTML。
- 邮件模板：Thymeleaf可以很好地处理HTML邮件模板。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Thymeleaf与其他模板引擎的对比
在选择模板引擎时，我们通常会考虑JSP、Freemarker、Velocity等选项。下面是一个详细的对比表格：
| 特性 | Thymeleaf | JSP | Freemarker | Velocity |
|---|---|---|---|---|
| 学习曲线 | 中等 | 中等 | 简单 | 简单 |
| 性能 | 良好 | 优秀 | 优秀 | 良好 |
| 自然模板支持 | 是 | 否 | 否 | 否 |
| Spring集成 | 优秀 | 良好 | 良好 | 一般 |
| 模板缓存 | 支持 | 支持 | 支持 | 支持 |
| 国际化支持 | 优秀 | 一般 | 良好 | 一般 |
| 可扩展性 | 优秀 | 一般 | 良好 | 一般 |
从实际项目经验来看，Thymeleaf在开发效率和团队协作方面有明显优势。我曾经在一个大型电商项目中同时使用Thymeleaf和Freemarker，Thymeleaf模板的开发速度比Freemarker快约30%，主要得益于它的自然模板特性减少了前后端联调的时间。
3. Thymeleaf的核心语法与使用
3.1 基本语法结构
Thymeleaf通过特殊的HTML属性来实现模板功能。这些属性都以th:为前缀，例如：
html复制<p th:text="${message}">这是默认显示的静态文本</p>
这段代码在静态预览时会显示"这是默认显示的静态文本"，而在服务器渲染时会被message变量的值替换。
3.2 常用Thymeleaf属性
-
th:text：设置元素的文本内容，会进行HTML转义
html复制<span th:text="${user.name}">用户名</span> -
th:utext：设置元素的文本内容，不进行HTML转义
html复制<div th:utext="${htmlContent}"></div> -
th:value：设置表单元素的值
html复制<input type="text" th:value="${product.price}"> -
th:each：循环迭代
html复制<tr th:each="user : ${users}"> <td th:text="${user.id}"></td> <td th:text="${user.name}"></td> </tr> -
th:if/th:unless：条件判断
html复制<div th:if="${user.isAdmin}">管理员面板</div> <div th:unless="${user.isAdmin}">普通用户面板</div> -
th:object：表单绑定
html复制<form th:object="${user}"> <input type="text" th:field="*{name}"> <input type="text" th:field="*{email}"> </form>
3.3 表达式类型
Thymeleaf支持多种表达式：
-
变量表达式：
${...}- 访问模型中的变量html复制<p th:text="${user.name}"></p> -
选择表达式：
*{...}- 在th:object上下文中选择属性html复制<div th:object="${user}"> <p th:text="*{name}"></p> </div> -
消息表达式：
#{...}- 国际化消息html复制<p th:text="#{welcome.message}"></p> -
链接表达式：
@{...}- URL生成html复制<a th:href="@{/users/{id}(id=${user.id})}">查看用户</a> -
片段表达式：
~{...}- 模板片段引用html复制<div th:insert="~{commons :: footer}"></div>
4. Thymeleaf与Spring Boot集成实战
4.1 基本配置
在Spring Boot中使用Thymeleaf非常简单，只需添加starter依赖：
xml复制<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
Spring Boot会自动配置Thymeleaf，默认模板位置是src/main/resources/templates/，文件后缀是.html。
4.2 自定义配置
可以在application.properties中自定义Thymeleaf配置：
properties复制# 关闭缓存，开发时使用
spring.thymeleaf.cache=false
# 设置模板编码
spring.thymeleaf.encoding=UTF-8
# 设置模板模式为HTML5
spring.thymeleaf.mode=HTML5
# 前缀和后缀
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html
4.3 控制器示例
java复制@Controller
public class UserController {
@GetMapping("/users")
public String listUsers(Model model) {
List<User> users = userService.findAll();
model.addAttribute("users", users);
return "user/list"; // 对应templates/user/list.html
}
@GetMapping("/users/{id}")
public String showUser(@PathVariable Long id, Model model) {
User user = userService.findById(id);
model.addAttribute("user", user);
return "user/detail";
}
}
4.4 模板示例
templates/user/list.html:
html复制<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>用户列表</title>
</head>
<body>
<h1>用户列表</h1>
<table>
<thead>
<tr>
<th>ID</th>
<th>姓名</th>
<th>邮箱</th>
</tr>
</thead>
<tbody>
<tr th:each="user : ${users}">
<td th:text="${user.id}"></td>
<td th:text="${user.name}"></td>
<td th:text="${user.email}"></td>
</tr>
</tbody>
</table>
</body>
</html>
5. Thymeleaf高级特性与最佳实践
5.1 布局与模板复用
Thymeleaf支持通过th:insert、th:replace和th:include实现模板复用。推荐使用布局方言（需要额外依赖）：
xml复制<dependency>
<groupId>nz.net.ultraq.thymeleaf</groupId>
<artifactId>thymeleaf-layout-dialect</artifactId>
</dependency>
定义布局模板layout.html:
html复制<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<head>
<title layout:title-pattern="$CONTENT_TITLE - $LAYOUT_TITLE">默认标题</title>
</head>
<body>
<header>
<h1>网站标题</h1>
</header>
<section layout:fragment="content">
<p>默认内容</p>
</section>
<footer>
<p>版权信息</p>
</footer>
</body>
</html>
使用布局的页面page.html:
html复制<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
layout:decorate="~{layout}">
<head>
<title>页面标题</title>
</head>
<body>
<section layout:fragment="content">
<h2>页面内容</h2>
<p>这是具体的页面内容</p>
</section>
</body>
</html>
5.2 表单处理与验证
Thymeleaf与Spring的表单绑定功能完美配合：
html复制<form th:action="@{/users}" th:object="${user}" method="post">
<div>
<label>姓名:</label>
<input type="text" th:field="*{name}">
<span th:if="${#fields.hasErrors('name')}" th:errors="*{name}"></span>
</div>
<div>
<label>邮箱:</label>
<input type="email" th:field="*{email}">
<span th:if="${#fields.hasErrors('email')}" th:errors="*{email}"></span>
</div>
<button type="submit">提交</button>
</form>
5.3 实用工具对象
Thymeleaf提供了一系列实用的工具对象：
-
#dates：日期格式化
html复制<span th:text="${#dates.format(user.createTime, 'yyyy-MM-dd')}"></span> -
#strings：字符串操作
html复制<span th:text="${#strings.toUpperCase(user.name)}"></span> -
#lists：集合操作
html复制<span th:text="${#lists.size(users)}"></span> -
#arrays：数组操作
html复制<span th:text="${#arrays.length(user.roles)}"></span> -
#messages：国际化消息
html复制<span th:text="${#messages.msg('welcome.message')}"></span>
5.4 性能优化建议
-
启用模板缓存：生产环境一定要启用缓存
properties复制spring.thymeleaf.cache=true -
合理使用片段：将重复的部分提取为片段
-
避免复杂的表达式：复杂的逻辑应该放在控制器中处理
-
使用内联JavaScript：避免在JavaScript中混合Thymeleaf表达式
html复制<script th:inline="javascript"> var userId = [[${user.id}]]; var userName = [[${user.name}]]; </script>
6. 常见问题与解决方案
6.1 表达式不生效
问题现象：Thymeleaf表达式如${...}在页面上原样显示，没有被解析。
解决方案：
- 确保HTML标签添加了Thymeleaf命名空间：
html复制<html xmlns:th="http://www.thymeleaf.org"> - 检查模板文件是否放在
src/main/resources/templates/目录下 - 确保控制器返回的视图名称正确
- 检查是否添加了
spring-boot-starter-thymeleaf依赖
6.2 静态资源无法加载
问题现象：CSS、JavaScript等静态资源无法加载。
解决方案：
- 使用Thymeleaf的URL表达式引用资源：
html复制<link th:href="@{/css/style.css}" rel="stylesheet"> - 确保静态资源放在
src/main/resources/static/目录下 - 检查Spring Security配置是否允许访问静态资源
6.3 表单绑定失败
问题现象：表单提交后，后台无法正确接收数据。
解决方案：
- 确保表单使用
th:object绑定对象 - 表单字段使用
th:field而不是th:value - 检查控制器方法参数是否有
@ModelAttribute注解 - 确保表单的
action属性使用Thymeleaf的URL表达式
6.4 性能问题
问题现象：页面渲染速度慢。
解决方案：
- 生产环境启用模板缓存
- 减少模板中的复杂逻辑
- 使用片段缓存（需要额外配置）
- 考虑使用Thymeleaf的
th:block标签减少DOM元素
7. Thymeleaf在实际项目中的应用技巧
7.1 动态CSS类
Thymeleaf可以动态设置元素的class：
html复制<div th:class="${user.active} ? 'active' : 'inactive'"></div>
或者更复杂的条件：
html复制<div th:classappend="${user.admin} ? 'admin' : ''"></div>
7.2 条件属性
可以基于条件添加或移除HTML属性：
html复制<input type="checkbox" th:checked="${user.active}">
<a th:href="${user.website}" th:if="${user.website}">个人网站</a>
7.3 内联文本
对于简单的文本，可以使用内联表达式：
html复制<p>欢迎, [[${user.name}]]!</p>
这种方式比th:text更简洁，但要注意HTML转义问题。
7.4 处理null值
Thymeleaf提供了安全导航操作符?.和处理null的默认值：
html复制<p th:text="${user?.address?.street} ?: '未提供地址'"></p>
7.5 国际化处理
Thymeleaf的国际化支持非常强大：
-
定义消息文件
messages.properties：code复制welcome.message=Welcome, {0}! -
在模板中使用：
html复制<p th:text="#{welcome.message(${user.name})}"></p> -
支持多语言切换，只需创建对应的
messages_xx.properties文件
7.6 与JavaScript集成
Thymeleaf可以很好地与JavaScript集成：
html复制<script th:inline="javascript">
var user = {
id: [[${user.id}]],
name: [[${user.name}]]
};
function showUser() {
alert([[#{user.welcome(${user.name})}]]);
}
</script>
这种方式比直接在JavaScript中拼接字符串更安全、更易维护。
8. Thymeleaf的未来发展与学习资源
Thymeleaf目前已经发展到3.1版本，持续保持着活跃的更新。根据我的观察，Thymeleaf未来的发展方向可能包括：
- 更好的性能优化：特别是对大模板的解析和渲染优化
- 更紧密的Spring集成：特别是与Spring WebFlux的深度整合
- 增强的前端工具链支持：如与Webpack等现代前端工具的集成
- 更丰富的扩展点：让开发者可以更灵活地扩展功能
8.1 推荐学习资源
-
官方文档：Thymeleaf官方文档是最权威的学习资源，特别是"Tutorial"部分非常适合入门。
-
《Thymeleaf实战》：这本书详细介绍了Thymeleaf的各个方面，包括高级特性和最佳实践。
-
Spring官方指南：Spring官网有专门的Thymeleaf指南，展示了与Spring框架的最佳集成方式。
-
GitHub示例：Thymeleaf官方GitHub仓库中有大量示例项目，涵盖了各种使用场景。
8.2 社区与支持
Thymeleaf有一个活跃的社区：
- Stack Overflow：大多数Thymeleaf问题都能在这里找到答案
- GitHub Issues：可以报告bug或提出功能请求
- Gitter聊天室：开发者可以直接交流
在实际项目中采用Thymeleaf后，我发现团队的前后端协作效率显著提高，模板的可维护性也大大增强。特别是在需要频繁调整UI的项目中，Thymeleaf的自然模板特性让修改和预览变得非常方便。