FreeMarker快速入门指南

FreeMarker是一个基于模板和数据模型生成文本输出的Java库。它广泛应用于Web开发、代码生成、邮件模板等场景。本文将带你快速上手FreeMarker的核心概念和基本用法。

什么是FreeMarker

FreeMarker是一个模板引擎，它将模板文件（.ftl文件）与数据模型结合，生成最终的文本输出。其核心优势包括：

模板与逻辑分离：视图层完全独立于业务逻辑
功能强大：支持复杂的表达式、宏定义、继承等特性
性能优秀：模板预编译，执行效率高
易于学习：语法简洁直观

添加依赖

在Maven项目中添加FreeMarker依赖：

<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的模板文件：

<!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代码实现

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();}}
}

核心语法

变量输出

${变量名}              // 输出变量值
${user.name}           // 输出对象属性
${user.getName()}      // 调用方法
${price?string.currency} // 格式化输出

条件判断

<#if condition>条件为真时的内容
<#elseif anotherCondition>另一个条件为真时的内容
<#else>默认内容
</#if>

循环遍历

<#list items as item>${item_index}: ${item.name}
</#list>// 检查列表是否为空
<#list users as user>${user.name}
<#else>没有用户数据
</#list>

默认值处理

${name!"未知"}          // 如果name为null，显示"未知"
${age?c}               // 数字格式化
${date?string("yyyy-MM-dd")} // 日期格式化

宏定义

<#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. 邮件模板

// 邮件模板示例
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);
}