FreeMaker 模板引擎的使用
大家好！今天想跟大家聊聊一个在 Java 后端开发中非常实用的工具——FreeMarker 模板引擎。它是一款简单易用、功能强大的模板引擎，不管是生成 HTML 页面，还是处理静态文件，都能让我们轻松搞定。接下来，我会带大家一步步了解 FreeMarker 的使用方法以及它的实际应用场景。
什么是 FreeMarker？
FreeMarker 是一个模板引擎，简单来说，它可以帮我们把动态数据填充到模板文件里，生成最终的 HTML、XML 或者其他格式的内容。它有几个核心概念：
- 模板引擎：FreeMarker 的工作原理就是通过模板文件（通常是
.ftl文件）和数据模型生成最终内容。 - 模板文件：模板文件里可以包含静态内容和动态占位符，静态内容直接输出，动态部分会用数据模型来填充。
- 数据模型：简单理解就是一个键值对的结构（比如 Map、JavaBean 或集合），用来给模板提供数据。
如何在项目中使用 FreeMarker？
首先，我们得在项目中引入 FreeMarker 的依赖。假如你用的是 Maven 项目，可以在 pom.xml 中添加以下依赖：
<dependency>
<groupId>org.freemarker</groupId>
<artifactId>freemarker</artifactId>
<version>2.3.32</version>
</dependency>
接下来，我们来看一下完整的使用流程：
1. 配置 FreeMarker
配置 FreeMarker 的第一步是创建一个 Configuration 对象，这相当于 FreeMarker 的核心控制台，用来设置模板的加载路径和其他参数。
import freemarker.template.Configuration;
import freemarker.template.TemplateExceptionHandler;
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
cfg.setClassForTemplateLoading(MyClass.class, "/templates"); // 设置模板目录
cfg.setDefaultEncoding("UTF-8");
cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER); // 设置异常处理方式
2. 准备模板文件
然后我们需要创建一个模板文件，比如 example.ftl，它的内容可以是这样的：
DOCTYPE html>
<html>
<head>
<title>${title}title>
head>
<body>
<h1>Hello, ${user}!h1>
<p>欢迎学习 FreeMarker！p>
<#-- 条件语句 -->
<#if user == "张三">
<p>你是 VIP 用户！p>
<#else>
<p>你好，普通用户！p>
#if>
<#-- 循环语句 -->
<ul>
<#list items as item>
<li>${item}li>
#list>
ul>
<#-- 转义和非转义 -->
<p>转义字符示例：${htmlContent}p>
<p>非转义字符示例：${htmlContent?no_esc}p>
body>
html>
3. 准备数据模型
接着，用 Java 代码创建一个数据模型。你可以用 Map 或 JavaBean，这里我们用 Map：
import java.util.HashMap;
import java.util.Map;
import java.util.List;
import java.util.Arrays;
Map<String, Object> dataModel = new HashMap<>();
dataModel.put("title", "FreeMarker 示例");
dataModel.put("user", "张三");
dataModel.put("items", Arrays.asList("苹果", "香蕉", "橘子"));
dataModel.put("htmlContent", "这是加粗的内容");
4. 生成输出
最后，把模板文件和数据模型结合起来，生成最终的内容：
import freemarker.template.Template;
import java.io.StringWriter;
Template template = cfg.getTemplate("example.ftl"); // 加载模板
StringWriter writer = new StringWriter();
template.process(dataModel, writer); // 合成模板和数据
System.out.println(writer.toString()); // 打印输出结果
运行这段代码后，你会看到完整的 HTML 输出，模板中的占位符都被替换成了数据，并正确渲染了条件、循环和转义逻辑。
FreeMarker 的实际应用场景
1. 动态生成 HTML 页面
这是 FreeMarker 最常见的用法，比如在用户管理系统中，根据用户的信息动态生成用户详情页面，轻松实现个性化页面展示。
2. 生成静态文件
电商项目中，为了减轻服务器压力，我们通常会提前生成静态的商品详情页。使用 FreeMarker，很容易就能实现这一需求：
import java.io.File;
import java.io.FileWriter;
File outputFile = new File("output.html");
try (FileWriter fileWriter = new FileWriter(outputFile)) {
template.process(dataModel, fileWriter); // 把生成结果写入文件
}
3. 邮件模板
FreeMarker 还能用来生成邮件内容。比如说，构造一封带动态数据的欢迎邮件：
String emailContent;
try (StringWriter emailWriter = new StringWriter()) {
template.process(dataModel, emailWriter);
emailContent = emailWriter.toString();
}
// 接下来用邮件服务发送 emailContent
4. 自动化文档生成
通过模板结合 API 数据，我们还可以自动生成 HTML 或 Markdown 格式的接口文档，提升开发效率。
使用 FreeMarker 时需要注意什么？
- 模板路径：确认模板文件的路径是否正确。路径设置不对，模板加载时会报错。
- 字符编码：强烈建议统一使用 UTF-8，避免乱码。
- 异常处理：FreeMarker 的模板处理可能会抛出
TemplateException，一定要记得捕获并处理。 - 安全问题：如果数据来自用户输入，注意防止模板注入攻击。
总结
FreeMarker 是一个非常强大的工具，能帮助我们在开发中节省很多时间。不管是生成动态网页、静态文件，还是处理复杂的邮件模板，FreeMarker 都能轻松胜任。如果你还没用过，不妨在下一个项目中尝试一下！
希望这篇文章对你有所帮助！