当前位置： 首页 > article >正文

FreeMarker模版引擎入门及实战

article 2024/11/6 5:20:31

什么是模板引擎?

模板引擎是一种用于生成动态内容的库或框架，它通过将预定义的模板和特定数据结合，生成最终的输出内容。模板引擎的使用有许多优点。首先，它提供了模板文件的语法和解析功能。开发者只需按照特定格式（例如 ${参数} 的语法）编写模板文件，模板引擎就能自动将数据注入模板，生成完整的文件，而不需要手动编写解析逻辑。

其次，模板引擎能够将数据和模板分离，便于团队分工。后端开发者可以专注于提供数据，前端开发者可以专注于模板的设计，使系统更易于维护。另外，模板引擎通常还具备一些安全功能，比如防范跨站脚本攻击。因此，建议大家至少掌握一种模板引擎的使用方法。

目前有很多现成的模板引擎，例如 Java 的 Thymeleaf、FreeMarker、Velocity 以及前端的 Mustache。在本项目中，我将使用知名且稳定的模板引擎 FreeMarker，向大家展示模板引擎的使用方法。

什么是 FreeMarker?

FreeMarker 是 Apache 开发的一个开源模板引擎，具有上手容易、灵活且易于扩展的特点。它不依赖于 Spring 框架、Servlet 环境或其他第三方依赖，因此可以用于任何 Java 项目。我个人建议学习 FreeMarker 时直接参考官方文档，尽管是英文的，但每个部分基本都配有代码示例，理解起来相对简单。

FreeMarker 官方文档:https://freemarker.apache.org/docs/index.html

在这里插入图片描述
在这里插入图片描述

看不懂英文也没关系，下面就带大家学习 FreeMarker，只讲常用的特性，主打一个快速入门!

模板引擎的作用

上面已经讲过了模板引擎的作用，这里就再用 FreeMarker 官网的一张图，强化下大家的理解如下图，FreeMarker 模板引擎的作用就是接受模板和 Java 对象，对它们进行处理，输出完整的内容。
在这里插入图片描述
下面我们先依次来学习 FreeMarker 的核心概念(模板和数据模型)，然后通过一个 Demo 快速入门。

模板

FreeMarker 拥有自己的模板编写规则、，一般用 FTL 表示 FreeMarker 模板语言。比如 myweb.html.ftl 就是一个 FreeMarker 的模板文件。

模板文件由 4 个核心部分组成

  1. 文本:固定的内容，会按原样输出。
  2. 插值:用 ${..}语法来占位，尖括号中的内容在经过计算和替换后，才会输出。
  3. FTL 指令:有点像 HTML的标签语法，通过 <#xxx...>来实现各种特殊功能。比如 <#list elements as element> 实现循环输出。
  4. 注释:和 HTML 注释类似，使用 <#-- ... -->语法，注释中的内容不会输出。

让我们举一个 FreeMarker 模板文件的例子：学过前端开发框架的同学应该会觉得很眼熟～

<!DOCTYPE html>
<html>
  <head>
    <title>玦尘</title>
  </head>
  <body>
    <h1>欢迎来到我的官网</h1>
    <ul>
      <#-- 循环渲染导航条 -->
      <#list menuItems as item>
        <li><a href="${item.url}">${item.label}</a></li>
      </#list>
    </ul>
    <#-- 底部版权信息（注释部分，不会被输出）-->
      <footer>
        ${currentYear} 玦尘官网. All rights reserved.
      </footer>
  </body>
</html>

数据模型

我们把为模板准备的所有数据整体统称为 数据模型。
在 FreeMarker 中，数据模型一般是树形结构，可以是复杂的 Java 对象、也可以是 HashMap 等更通用的结构，可能是这样的:

{
  "currentYear": 2024,
  "menuItems": [
    {
      "url": "https://juechen.cn",
      "label": "玦尘编程导航",
    },
    {
      "url": "https://chat2db.ai",
      "label": "AI数据库",
    }
  ]
}

Demo 实战

在了解模板和数据模型后，让我们通过 FreeMarker 对二者进行组合处理。

1、引入依赖

首先创建一个 Maven 项目(这里就用我们的 juechen-generator-basic 项目)，在 pom.xml 中引入 FreeMarker依赖，代码如下：

<!-- https://freemarker.apache.org/index.html -->
<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>2.3.32</version>
</dependency>

如果是SpringBoot项目，则可以直接引入starter依赖：

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

2、创建配置对象

在 test/java 目录下新建一个单元测试类 FreeMarkerTest ，在Test方法中创建一个 FreeMarker 的全局配置对象，可以统一指定模板文件所在的路径、模板文件的字符集等。
示例代码如下:

// new 出 Configuration 对象，参数为 FreeMarker 版本号
Configuration configuration = new Configuration(Configuration.VERSION_2_3_32);

// 指定模板文件所在的路径
configuration.setDirectoryForTemplateLoading(new File("src/main/resources/templates"));

// 设置模板文件使用的字符集
configuration.setDefaultEncoding("utf-8");

3、准备模版并加载

我们将上述模板代码保存为 myweb.html.ftl 文件，存放在上面指定的目录下。
在这里插入图片描述
准备好模版文件后，通过创建 template 对象来加载该模版。示例代码如下：

// 创建模板对象，加载指定模板
Template template = configuration.getTemplate("myweb.html.ftl");

4、创建数据模型

如果想保证数据的质量和规范性，可以使用对象来保存"喂"给模板的数据;反之，如果想更灵活地构造数据模型，推荐使用 HashMap 结构。
比如我们想构造《玦尘官网》的数据模型，需要制定当前年份和导航菜单项，示例代码如下:

	// 创建数据模型
	Map<String, Object> dataModel = new HashMap<>();
	dataModel.put("currentYear", 2024);
	
	// 创建菜单项列表
	List<Map<String, Object>> menuItems = new ArrayList<>();
	
	// 添加第一个菜单项
	Map<String, Object> menuItem1 = new HashMap<>();
	menuItem1.put("url", "https://juechen.cn");
	menuItem1.put("label", "玦尘编程导航");
	menuItems.add(menuItem1);
	
	// 添加第二个菜单项
	Map<String, Object> menuItem2 = new HashMap<>();
	menuItem2.put("url", "https://chat2db.ai");
	menuItem2.put("label", "AI数据库");
	menuItems.add(menuItem2);
	
	// 将菜单项列表添加到数据模型中
	dataModel.put("menuItems", menuItems);

5、指定生成的文件

可以直接使用 FileWriter 对象指定生成的文件路径和名称：

Writer out = new FileWriter("myweb.html");

6、生成文件

一切准备就绪，最后只需要调用 template 对象的 process 方法，就可以处理并生成文件了
示例代码如下:

template.process(dataModel, out);

// 生成文件后别忘了关闭哦
out.close();

7、完整代码

组合上面的所有代码并执行，发现在项目的根路径下生成了网页文件，至此 Demo 结束，很简单吧~

在这里插入图片描述

FreeMarkerTest.java 文件的完整代码：

import freemarker.template.Configuration;
import freemarker.template.Template;
import freemarker.template.TemplateException;
import org.junit.Test;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * @author Juechen
 * @version : FreeMarkerTest.java
 */
public class FreeMarkerTest {

    @Test
    public void test() throws IOException, TemplateException {
        // new 出 Configuration 对象，参数为 FreeMarker 版本号
        Configuration configuration = new Configuration(Configuration.VERSION_2_3_32);

        // 指定模板文件所在的路径
        configuration.setDirectoryForTemplateLoading(new File("src/main/resources/templates"));

        // 设置模板文件使用的字符集
        configuration.setDefaultEncoding("utf-8");

        // 创建模板对象，加载指定模板
        Template template = configuration.getTemplate("myweb.html.ftl");

        // 创建数据模型
        Map<String, Object> dataModel = new HashMap<>();
        dataModel.put("currentYear", 2024);

        // 创建菜单项列表
        List<Map<String, Object>> menuItems = new ArrayList<>();

        // 添加第一个菜单项
        Map<String, Object> menuItem1 = new HashMap<>();
        menuItem1.put("url", "https://juechen.cn");
        menuItem1.put("label", "玦尘编程导航");
        menuItems.add(menuItem1);

        // 添加第二个菜单项
        Map<String, Object> menuItem2 = new HashMap<>();
        menuItem2.put("url", "https://chat2db.ai");
        menuItem2.put("label", "AI数据库");
        menuItems.add(menuItem2);

        // 将菜单项列表添加到数据模型中
        dataModel.put("menuItems", menuItems);

        // 生成
        Writer out = new FileWriter("myweb.html");
        template.process(dataModel, out);

        // 生成文件后别忘了关闭哦
        out.close();
    }
}

常用语法

学会了 FreeMarker 的基本开发流程后，我们来学习一些 FreeMarker 中的实用特性注意，FreeMarker 的语法和特性非常多，本文仅带大家学习常用的、易用的语法。无需记忆，日后需要用到 FreeMarker 时，再去对照官方文档查漏补缺即可。

1、插值

在上面的 Demo 中，已经给大家演示了差值的基本语法( ${xxx})。但插值还有很多花样可以玩，比如支持传递表达式:

表达式:${100 + money}

不过个人不建议在模板文件中写表达式，为什么不在创建数据模型时就计算好要展示的值呢?

2、分支和判空

和程序开发一样，FreeMarker 模板也支持分支表达式(if … else)，示例代码如下:

<#if user == "玦尘">
  我是玦尘
<#else>
  我是SY
</#if>

分支语句的一个常用场景就是判空，比如要判断 user 参数是否存在，可以用下面的语法:

<#if user??>
  存在用户
<#else>
  用户不存在
</#if>

3、默认值

FreeMarker 对变量的空值校验是很严格的，如果模板中某个对象为空，FreeMarker 将会报错而导致模板生成中断。
为了防止这个问题，建议给可能为空的参数都设置默认值。使用 表达式!默认值 的语法，示例代码如下:

${user!"用户为空"}

上述代码中，如果 user 对象为空，则会输出“用户为空”字符串。

4、循环

在上述 Demo 实战部分，已经给大家演示了循环的用法。即<#list items as item>表达式，可以遍历某个序列类型的参数并重复输出多条内容。

示例代码如下:

<#list users as user>
  ${user}
</#list>

其中，users 是整个列表，而 user 是遍历列表每个元素时临时存储的变量，跟 for 循环一样，会依次输出每个 user 的值。

5、宏定义

学过 C 语言和 C++ 的同学应该对 "宏"这个词并不陌生。可以把"宏"理解为一个预定义的模板片段。支持给宏传入变量，来复用模板片段。

其实类似于前端开发中组件复用的思想

在 FreeMarker 中，使用 macro 指令来定义宏。

让我们来定义一个宏，用于输出特定格式的用户昵称，比如:

<#macro card userName>     
---------    
${userName}
---------
</#macro>

其中，card 是宏的名称，userName 是宏接受的参数可以用 @ 语法来使用宏，示例代码如下

<@card userName="玦尘"/>
<@card userName="欧文"/>

实际生成的输出结果为:

---------    
玦尘
---------
---------    
欧文
---------

宏标签中支持嵌套内容，不过还是有些复杂的(再讲下去就成前端课了)，大家需要用到时查看官方文档就好。

自定义指令:http://freemarker.foofun.cn/dgui_misc_userdefdir.html

6、内建函数

内建函数是 FreeMarker 为了提高开发者处理参数效率而提供的的语法糖，可以通过 ?来调用内建函数比如将字符串转为大写:

${userName?upper_case}

比如输出序列的长度:

${myList?size}

把内建函数想象成调用 Java 对象的方法，就很好理解了。

内建函数是 FreeMarker 非常强大的一个能力，比如想在循环语法中依次输出元素的下标，就可以使用循环表达式自带的 index 内建函数:

<#list users as user>
  ${user?index}
</#list>

内建函数种类丰富、数量极多，因此不建议大家记忆，需要用到的时候去查阅官方文档即可

内建函数大全参考:http://freemarker.foofun.cn/ref_builtins.html

7、其他

还有更多特性，比如命名空间，其实就相当于 Java 中的包，用于隔离代码、宏、变量等,不过没必要细讲，因为掌握上述常用语法后，基本就能够开发大多数模板文件了。更多内容自主查阅官方文档学习即可。

问题解决示例

给大家分享一个通过查阅官方文档解决具体问题的例子，比如之前生成的网站文件中，我们发现数字中间加了一个逗号分割符，如下图:

在这里插入图片描述

这是因为 FreeMarker 使用 Java 平台的本地化敏感的数字格式信息，如果想把分割符取消掉，怎么办呢?
我们可以通过查阅官方文档看到以下信息:

地址：http://freemarker.foofun.cn/app_faq.html#faq_number_grouping

在这里插入图片描述

按照文档的提示，修改 configuration 配置类的 number format 设置，即可调整默认生成的数字格式啦。

在这里插入图片描述

更多学习资源

官方文档：https://freemarker.apache.org/docs/index.html

中文教程：http://freemarker.foofun.cn/toc.html


http://www.kler.cn/a/381116.html

相关文章：

  • 帆软报表新增一行数据后保存，删除选中数据
  • 分布式事务的几种方式 2PC,3PC,Distributed Lock,TCC
  • spring ai 入门 之 结构化输出 - 把大模型llm返回的内容转换成java bean
  • 你知道Mac也能拥有丰富的右键菜单栏吗？
  • Spring Boot 注解大全：全面解析 Spring Boot 常用注解及其应用场景
  • 使用正则表达式验证积累
  • 人工智能学习--归一化（Normalization）
  • 编译工具与文件学习(一)-YAML、repos、vcstoolcolcon
  • 【大模型LLM面试合集】大语言模型架构_chatglm系列模型
  • STM32移植RT-Thread---时钟管理
  • 【MyBatis源码】CacheKey缓存键的原理分析
  • 【AI照片数字人整合包及教程】EchoMimic：开启照片数字人的新纪元
  • 【启明智显技术分享】开发Model系列遇到像素时钟Pclk与接口时钟SCL相关问题
  • macOS 开发环境配置与应用开发指南
  • 使用 OpenCV 读取和显示图像与视频
  • Flutter鸿蒙next中封装一个输入框组件
  • 数据结构--二叉树_链式（下）
  • Node.js：Express 中间件 CORS 跨域资源共享
  • ETLCloud怎么样？深度解析其在数据管理中的表现
  • 小菜家教平台（二）：基于SpringBoot+Vue打造一站式学习管理系统
  • 数据结构与算法——Java实现 54.力扣1008题——前序遍历构造二叉搜索树
  • C语言中如何实现动态内存分配
  • Unity网络开发基础（part5.网络协议）
  • 软硬链接与动静态库
  • [N-155]基于springboot,vue宿舍管理系统
  • Java项目实战II基于Spring Boot的交通管理在线服务系统设计与实现（开发文档+数据库+源码）