Spring Boot 集成 Thymeleaf 与 FreeMarker 模板渲染详解

清欢

发布时间：2026-10-16| 8人浏览过

原创

在开发 Web 应用时，将后端数据渲染到前端页面是核心需求。本文以 Spring Boot 为基础，详细演示如何使用 Thymeleaf 和 FreeMarker 两种模板引擎实现这一目标。通过新建项目模块、引入依赖、编写 Controller 与 HTML 模板，并结合浏览器访问验证，帮助开发者快速掌握基于模板引擎的数据渲染流程。

模板引擎概述

Spring Boot 提供了多种预设配置的模板引擎，其中最常用的包括：

Thymeleaf
FreeMarker
Velocity
Groovy
Mustache

本文将重点介绍 Thymeleaf 和 FreeMarker 的集成与使用方法。

新建 Spring Boot 模块

首先，创建一个新的 Spring Boot 项目模块（或在新建项目中勾选相关组件）。

在选择 Starter 依赖时，请确保勾选以下选项：

Developer Tools 下的 Spring Boot DevTools（用于热部署优化）
Web 下的 Spring Web
Template Engines 下的 Thymeleaf

若手动管理 Maven 依赖，也可以在 pom.xml 中添加以下内容：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

实现 Thymeleaf 模板渲染

第1步：创建 HTML 模板文件

目的：定义前端的静态结构与数据占位符。

入口：在 src/main/resources/templates/ 目录下创建 index.html（注意：为区分后续 FreeMarker 示例，此处实际文件名在代码中需对应，下文代码块演示为通用结构，实际文件名建议命名为 thymeleaf.html 以匹配 Controller 返回结果）。

动作：编写包含 th:text 属性的 HTML 代码，用于显示从后台传入的数据：

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Thymeleaf Demo</title>
</head>
<body>
    <p th:text="'名字:'+${name}"></p>
    <p th:text="'网址:'+${url}"></p>
</body>
</html>

重要参数：xmlns:th="http://www.thymeleaf.org" 必须在 html 标签中声明，否则 Thymeleaf 语法可能无法解析。

第2步：编写 Controller

目的：将数据放入 Model 并指定返回视图名称。

入口：创建 Java 类 com.rumenz.lession4.controller.ThymeleafRumenController。

动作：使用 @Controller 注解，并返回模板文件名（不含后缀）：

package com.rumenz.lession4.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

@Controller
@RequestMapping("/")
public class ThymeleafRumenController {
    @RequestMapping(value = "/index", method = RequestMethod.GET)
    public String index(ModelMap m) {
        // 模拟从数据库查询数据
        m.addAttribute("name", "入门小站");
        m.addAttribute("url", "https://rumenz.com");
        // 返回资源路径下的模板文件名（默认前缀 templates/ 和后缀 .html）
        return "thymeleaf";
    }
}

第3步：启动与验证

目的：确认渲染结果符合预期。

动作：启动 Spring Boot 应用，并在浏览器访问 http://127.0.0.1:8080/index。

完成状态：页面成功显示 “名字:入门小站” 和对应的网址链接，说明数据已正确渲染至 HTML。

实现 FreeMarker 模板渲染

第1步：引入 FreeMarker 依赖

目的：替换或额外支持 FreeMarker 模板引擎。

在 pom.xml 中添加：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-freemarker</artifactId>
</dependency>

第2步：创建模板文件

目的：定义 FreeMarker 语法的页面结构。

入口：在 src/main/resources/templates/ 下创建 freemarker.html。

动作：使用 ${变量名} 语法：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>FreeMarker Demo</title>
</head>
<body>
FreeMarker案例
<p>名字:${name}</p>
<p>网址:${url}</p>
</body>
</html>

第3步：配置模板后缀

目的：明确模板文件的扩展名。

入口：src/main/resources/application.properties。

动作：添加配置项：

spring.freemarker.suffix=.html

第4步：编写 Controller

目的：处理请求并传递数据给 FreeMarker 模板。

入口：创建 com.rumenz.lession4.controller.FreeMarkerRumenController。

动作：

package com.rumenz.lession4.controller;

import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.RequestMapping;

@Controller
@RequestMapping("/")
public class FreeMarkerRumenController {
    @RequestMapping("/index2")
    public String index2(ModelMap m) {
        m.addAttribute("name", "入门小站");
        m.addAttribute("url", "https://rumenz.com");
        return "freemarker"; // 对应 freemarker.html
    }
}

第5步：启动与验证

动作：重启应用（若修改了 pom.xml 或配置文件），访问 http://127.0.0.1:8080/index2。

完成状态：页面显示 FreeMarker 渲染后的数据内容。

注意事项与排错

视图解析器冲突： 如果同时引入多个模板引擎依赖，Spring Boot 会根据优先级自动选择默认的一个。若希望同时使用，需根据 URL 路径分别映射到不同的 Controller，如上文所示通过不同接口路径 /index 和 /index2 区分。

缓存问题： 在生产环境中，模板引擎通常会缓存编译后的模板以提高性能。开发阶段建议关闭缓存以便即时修改生效，或在每次修改后重启应用。对于 Thymeleaf，可在配置文件中设置 spring.thymeleaf.cache=false；对于 FreeMarker，可设置 spring.freemarker.cache=false。

总结

通过以上步骤，我们分别在 Spring Boot 项目中实现了 Thymeleaf 和 FreeMarker 的数据渲染方案。Thymeleaf 因其天然 HTML 兼容性和强大的 Spring 集成备受青睐，而 FreeMarker 则在生成非 HTML 文本或复杂逻辑处理上具有优势。开发者可根据具体场景选择合适的模板引擎。以上就是 Spring Boot 中 Web 模版数据渲染展示的详细流程，更多关于 Spring Boot 模板引擎的资料请关注本站其它相关文章！