Thymeleaf

定义

Thymeleaf 是 Java 生态中的服务端模板引擎，用 Java 编写，能够处理 XML、XHTML、HTML5 以及纯文本等格式^[1][3]。它最常用于 MVC 架构 Web 应用的视图层，将业务数据填充进模板并输出最终页面，同时也能在离线环境中处理任意 XML 文件^[1]。

与 JSP 等把逻辑写成标签或脚本的模板技术不同，Thymeleaf 的语法依附于 HTML 标签属性，逻辑以 th 前缀的扩展属性形式出现，因此模板本身仍是合法的 HTML 文档^[4]。这一思路被称为自然模板，是它区别于同期多数 Java 模板引擎的主要特征^[2]。

原理

Thymeleaf 的工作过程可以概括为解析模板、求值表达式、输出结果三步。引擎读入模板文档后，识别其中的 th 属性与表达式，在运行时用模型数据替换静态占位内容，浏览器端最终收到的是普通 HTML。由于浏览器会忽略无法识别的自定义属性，未经处理的模板在浏览器中依然能正确显示，这构成了静态原型与动态模板共用同一份文件的基础^[5]。

表达式体系包含变量表达式 ${...}、选择表达式 *{...}、消息表达式 #{...} 与链接表达式 @{...} 等类型，分别承担取值、对象内选取、国际化文本读取和 URL 生成。变量表达式在标准方言下基于 OGNL，在与 Spring 集成时改用 Spring EL，与 Spring 的模型数据、消息源和安全表达式衔接^[4]。

引擎的处理能力以方言机制组织。方言(dialect) 由一组处理器构成，处理器绑定到模板的标签、属性或注释上执行求值、迭代等逻辑^[1]。默认提供 Standard 与 SpringStandard 2 种方言，两者的语法一致，后者面向 Spring MVC 应用；开发者也可以扩展或新建方言，因此该库在需要时可充当模板引擎框架使用^[1][3]。

模板模式在 3.0 中扩为多种，包括 HTML、XML、TEXT、JAVASCRIPT、CSS 与 RAW，覆盖网页、邮件正文、脚本与样式文件等输出场景^[6]。为减少重复解析开销，引擎提供可配置的已解析模板缓存，将解析后的模板结构复用，从而降低输入输出与解析成本^[1]。

flowchart LR

A[请求到达 Controller] --> B[准备模型数据]

B --> C[视图解析器定位模板]

C --> D{缓存中存在已解析模板}

D -- 是 --> F[表达式求值]

D -- 否 --> E[解析模板文档] --> F

F --> G[生成 HTML 响应]

发展历程

2011 年 7 月 17 日，Thymeleaf 1.0.0 作为首个稳定版本发布，以 Apache License 2.0 授权的开源 Java 库形式提供，作者 Daniel Fernández 此前曾开发 Java 加密库 Jasypt。初版即提供 Standard 与面向 Spring MVC 3 的 SpringStandard 2 种方言，并允许通过自定义方言扩展功能。

2.x 系列延续了基于 XML 与 DOM 的解析路线，这一架构在带来规范性的同时也带来性能负担，成为社区讨论较多的短板。根据项目版本记录，2.1.4 版于 2014 年 12 月 22 日发布^[7]。

3.0 系列是一次架构级重写：解析基础设施不再依赖 XML，完整支持 HTML5 标记，处理引擎改为事件驱动，并重建了方言与核心 API，官方同时给出从 2 到 3 的迁移指引，强调模板层面的兼容性。该版本还引入了片段表达式与以下划线表示的无操作令牌，并支持将模板逻辑与模板本体解耦。

此后版本以 3.1.x 为主线迭代，官方下载页显示 3.1.5.RELEASE 为该系列的最新版本，发布日期为 2026 年 4 月 21 日，运行要求为 Java SE 8 或更高版本^[8]。项目源码托管在 GitHub，并按模块拆分出 Spring Security 集成、测试库等附属构件^[8]。

应用

在 Web 开发中，Thymeleaf 主要用于 Spring MVC 与 Spring Boot 项目的视图渲染。引入对应的 starter 依赖后，模板默认从类路径下的 templates 目录读取，控制器返回视图名即可完成页面输出，配置项涵盖缓存开关、编码、模板模式与路径前缀等^[9]。开发阶段通常关闭模板缓存，以便修改后立即看到页面变化^[10]。

页面复用依靠片段机制实现。开发者用 th:fragment 定义可带参数的片段，再以 th:insert 或 th:replace 在其它模板中引用，从而把公共头部、导航、页脚等抽为独立单元^[4]。条件渲染、集合遍历与多分支选择分别由 th:if、th:unless、th:each 与 th:switch 等属性完成。

除网页之外，引擎也适合生成邮件正文一类的 HTML 文本，因为输出格式不限于浏览器页面^[11]。国际化场景中，消息表达式配合属性文件按用户区域读取对应文案，可支撑多语言界面^[4]。错误页也是常见用途，Spring Boot 会自动识别模板目录下的 404 与 500 页面文件^[10]。

局限

性能是 Thymeleaf 受到较多讨论的方面。多项对比测试显示，其在同等条件下的渲染吞吐低于 FreeMarker 等引擎，响应时间偏长，差距在模板复杂或并发升高时更明显^[12][13]。一部分原因在于基于标记与 DOM 的处理方式需要构建并维护文档结构，内存占用相对更高。

功能定位也带来边界。该引擎面向标记型文档，官方文档建议不要用它处理体量很大的 XML 文件；生成报表、代码等与 HTML 无关的多格式文本时，通用型引擎更为合适^[11]。模板中若堆积递归、多级嵌套等复杂逻辑，表达式层难以承担，通常需要把计算前移到服务层^[14]。

使用门槛方面，属性式语法与 JSP 的标签式写法差异较大，习惯旧技术的团队需要适应期，工具对象与表达式上下文也需要额外学习^[4]。此外，关于它是 Spring Boot 默认模板引擎的说法并不准确，官方文档只是并列介绍多种模板引擎，并在示例中较多采用它^[9]。

参见

• Java —— Thymeleaf 以 Java 语言编写，运行于 Java 虚拟机之上。

• Spring Boot —— 提供 Thymeleaf 的自动配置与 starter 依赖，是其最常见的运行环境。

• JSP —— 传统的 Java 服务端页面技术，Thymeleaf 常被视为其替代方案。

• FreeMarker —— 同为 Java 模板引擎，常与 Thymeleaf 在功能与性能上作对比。

• MVC —— Thymeleaf 通常承担该架构中视图层的渲染职责。