FreeMarker快速入门指南
FreeMarker是一个基于模板和数据模型生成文本输出的Java库。它广泛应用于Web开发、代码生成、邮件模板等场景。本文将带你快速上手FreeMarker的核心概念和基本用法。
什么是FreeMarker
FreeMarker是一个模板引擎，它将模板文件（.ftl文件）与数据模型结合，生成最终的文本输出。其核心优势包括：
- 模板与逻辑分离：视图层完全独立于业务逻辑
- 功能强大：支持复杂的表达式、宏定义、继承等特性
- 性能优秀：模板预编译，执行效率高
- 易于学习：语法简洁直观
添加依赖
在Maven项目中添加FreeMarker依赖：
xml
<dependency>
<groupId>org.freemarker</groupId>
<artifactId>freemarker</artifactId>
<version>2.3.32</version>
</dependency>基本概念
FreeMarker的工作流程包含三个核心组件：
- Template（模板）：包含静态文本和FreeMarker指令的文件
- Data Model（数据模型）：Java对象，为模板提供动态数据
- Output（输出）：模板和数据模型合并后的最终结果
第一个示例
让我们通过一个简单示例来理解FreeMarker的基本用法：
1. 创建模板文件
创建一个名为welcome.ftl的模板文件：
html
<!DOCTYPE html>
<html>
<head>
<title>欢迎页面</title>
</head>
<body>
<h1>欢迎 ${userName}!</h1>
<p>今天是 ${currentDate}</p>
<#if isVip>
<p style="color: gold;">您是我们的VIP用户！</p>
<#else>
<p>感谢您的访问！</p>
</#if>
<h2>您的订单</h2>
<ul>
<#list orders as order>
<li>${order.productName} - ¥${order.price}</li>
</#list>
</ul>
</body>
</html>2. Java代码实现
java
import freemarker.template.Configuration;
import freemarker.template.Template;
import freemarker.template.TemplateException;
import java.io.File;
import java.io.IOException;
import java.io.StringWriter;
import java.util.*;
public class FreeMarkerDemo {
public static void main(String[] args) {
try {
// 1. 创建Configuration对象
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
cfg.setDirectoryForTemplateLoading(new File("src/main/resources/templates"));
cfg.setDefaultEncoding("UTF-8");
// 2. 获取模板
Template template = cfg.getTemplate("welcome.ftl");
// 3. 准备数据模型
Map<String, Object> dataModel = new HashMap<>();
dataModel.put("userName", "张三");
dataModel.put("currentDate", new Date());
dataModel.put("isVip", true);
// 创建订单列表
List<Map<String, Object>> orders = new ArrayList<>();
Map<String, Object> order1 = new HashMap<>();
order1.put("productName", "笔记本电脑");
order1.put("price", 5999);
orders.add(order1);
Map<String, Object> order2 = new HashMap<>();
order2.put("productName", "无线鼠标");
order2.put("price", 99);
orders.add(order2);
dataModel.put("orders", orders);
// 4. 生成输出
StringWriter out = new StringWriter();
template.process(dataModel, out);
System.out.println(out.toString());
} catch (IOException | TemplateException e) {
e.printStackTrace();
}
}
}核心语法
变量输出
freemarker
${变量名} // 输出变量值
${user.name} // 输出对象属性
${user.getName()} // 调用方法
${price?string.currency} // 格式化输出条件判断
freemarker
<#if condition>
条件为真时的内容
<#elseif anotherCondition>
另一个条件为真时的内容
<#else>
默认内容
</#if>循环遍历
freemarker
<#list items as item>
${item_index}: ${item.name}
</#list>
// 检查列表是否为空
<#list users as user>
${user.name}
<#else>
没有用户数据
</#list>默认值处理
freemarker
${name!"未知"} // 如果name为null，显示"未知"
${age?c} // 数字格式化
${date?string("yyyy-MM-dd")} // 日期格式化宏定义
freemarker
<#macro greeting name color="blue">
<p style="color: ${color}">你好，${name}!</p>
</#macro>
// 使用宏
<@greeting name="张三" />
<@greeting name="李四" color="red" />实际应用场景
1. Web开发中的视图层
FreeMarker常用于Spring MVC中作为视图解析器，生成动态HTML页面。
2. 邮件模板
java
// 邮件模板示例
public String generateEmailContent(User user, Order order) {
Map<String, Object> model = new HashMap<>();
model.put("user", user);
model.put("order", order);
return processTemplate("email/order-confirmation.ftl", model);
}3. 代码生成
FreeMarker可以根据数据模型生成Java代码、SQL脚本等。
最佳实践
- 模板组织：将模板文件放在统一目录下，使用合理的文件夹结构
- 数据准备：在Controller或Service层准备完整的数据模型，避免在模板中进行复杂逻辑处理
- 错误处理：妥善处理TemplateException和IOException异常
- 性能优化：重用Configuration对象，避免重复创建
- 安全考虑：对用户输入进行适当的转义处理
小结
FreeMarker是一个功能强大且易于使用的模板引擎。通过分离模板和数据，它让代码结构更清晰，维护更容易。掌握了基本语法和核心概念后，你就可以在项目中灵活运用FreeMarker来处理各种文本生成需求。
随着项目复杂度的增加，你还可以深入学习FreeMarker的高级特性，如自定义指令、模板继承、国际化支持等功能。