FreeMarker快速入门指南

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

什么是FreeMarker

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

模板与逻辑分离：视图层完全独立于业务逻辑

功能强大：支持复杂的表达式、宏定义、继承等特性

性能优秀：模板预编译，执行效率高

易于学习：语法简洁直观

添加依赖

在Maven项目中添加FreeMarker依赖：

xml

复制代码

org.freemarker

freemarker

2.3.32

基本概念

FreeMarker的工作流程包含三个核心组件：

Template（模板）：包含静态文本和FreeMarker指令的文件

Data Model（数据模型）：Java对象，为模板提供动态数据

Output（输出）：模板和数据模型合并后的最终结果

第一个示例

让我们通过一个简单示例来理解FreeMarker的基本用法：

1. 创建模板文件

创建一个名为welcome.ftl的模板文件：

html

复制代码

欢迎 ${userName}!

今天是 ${currentDate}

<#if isVip>

您是我们的VIP用户！

<#else>

感谢您的访问！

您的订单

<#list orders as order>

• ${order.productName} - ¥${order.price}

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 dataModel = new HashMap<>();

dataModel.put("userName", "张三");

dataModel.put("currentDate", new Date());

dataModel.put("isVip", true);

// 创建订单列表

List> orders = new ArrayList<>();

Map order1 = new HashMap<>();

order1.put("productName", "笔记本电脑");

order1.put("price", 5999);

orders.add(order1);

Map 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>

默认内容

循环遍历

freemarker

复制代码

<#list items as item>

${item_index}: ${item.name}

// 检查列表是否为空

<#list users as user>

${user.name}

<#else>

没有用户数据

默认值处理

freemarker

复制代码

${name!"未知"} // 如果name为null，显示"未知"

${age?c} // 数字格式化

${date?string("yyyy-MM-dd")} // 日期格式化

宏定义

freemarker

复制代码

<#macro greeting name color="blue">

你好，${name}!

// 使用宏

<@greeting name="张三" />

<@greeting name="李四" color="red" />

实际应用场景

1. Web开发中的视图层

FreeMarker常用于Spring MVC中作为视图解析器，生成动态HTML页面。

2. 邮件模板

java

复制代码

// 邮件模板示例

public String generateEmailContent(User user, Order order) {

Map 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的高级特性，如自定义指令、模板继承、国际化支持等功能。