FreeMarker 详细介绍
一、概念
FreeMarker 是一个基于 Java 的模板引擎,用于生成动态文本内容。它的核心功能是将模板(.ftl
文件)和数据模型结合,生成最终的文本输出。FreeMarker 不仅可以用于 Web 开发中的视图渲染,还广泛应用于代码生成、配置文件生成等场景。
- 模板(Template): FreeMarker 的模板文件,包含静态文本和动态占位符。
- 数据模型(Data Model): 提供给模板的数据,通常是 Java 对象、集合或 Map。
- 模板引擎(Template Engine): FreeMarker 实现模板解析和数据合成的核心组件。
二、使用步骤
-
添加 FreeMarker 依赖
- 在 Maven 项目的
pom.xml
文件中添加 FreeMarker 依赖:<dependency> <groupId>org.freemarker</groupId> <artifactId>freemarker</artifactId> <version>2.3.31</version> </dependency>
- 在 Maven 项目的
-
配置 FreeMarker
- 创建一个
Configuration
对象,设置模板目录等配置:Configuration cfg = new Configuration(Configuration.VERSION_2_3_31); cfg.setDirectoryForTemplateLoading(new File("/path/to/templates")); cfg.setDefaultEncoding("UTF-8");
- 创建一个
-
创建模板
- 编写
.ftl
模板文件,例如welcome.ftl
:<html> <body> <h1>Welcome, ${userName}!</h1> </body> </html>
- 编写
-
加载模板
- 从模板目录中加载模板:
Template template = cfg.getTemplate("welcome.ftl");
- 从模板目录中加载模板:
-
合成数据模型
- 创建数据模型并将其传递给模板:
Map<String, Object> dataModel = new HashMap<>(); dataModel.put("userName", "张三");
- 创建数据模型并将其传递给模板:
-
生成文本
- 将模板和数据模型结合,生成最终的文本输出:
Writer out = new StringWriter(); template.process(dataModel, out); String result = out.toString();
- 将模板和数据模型结合,生成最终的文本输出:
三、功能
-
基本模板功能
- 占位符:
${variable}
用于插入数据模型中的值。 - 注释:
##
用于添加注释,不会出现在输出中。
- 占位符:
-
控制语句
- 条件语句:
#if
,#elseif
,#else
用于执行条件判断。 - 循环语句:
#list
用于遍历集合或数组。
- 条件语句:
-
宏(Macro)
- 定义可复用的模板片段:
<#macro greet name> <p>Hello, ${name}!</p> </#macro>
- 定义可复用的模板片段:
-
导入与包含
- 导入:
<#import "macros.ftl" as m/>
- 包含:
<#include "header.ftl"/>
- 导入:
-
国际化
- 支持根据不同语言环境生成内容。
四、高级功能
-
自定义指令(Directives)
- 通过实现
TemplateDirectiveModel
接口来扩展 FreeMarker 的功能。
- 通过实现
-
自定义数据模型
- 通过实现
TemplateHashModel
或TemplateCollectionModel
接口来自定义数据模型。
- 通过实现
-
自定义异常处理
- 自定义
TemplateExceptionHandler
处理模板异常。
- 自定义
-
缓存控制
- FreeMarker 支持模板缓存,可以通过配置
Configuration
对象来设置缓存策略。
- FreeMarker 支持模板缓存,可以通过配置
-
模板调试
- 开启 FreeMarker 的调试模式,可以帮助开发者发现和解决模板问题。
五、应用场景
-
Web 开发
- 用于动态生成 HTML 页面,结合用户数据渲染页面内容。
-
电子邮件生成
- 动态生成 HTML 或文本格式的电子邮件内容。
-
配置文件生成
- 根据配置模板生成 XML、JSON 等格式的配置文件。
-
代码生成
- 根据模板生成代码文件,如 Java 类、SQL 脚本等。
-
文档生成
- 生成报表、合同等文档内容。
六、优势
-
灵活性高
- 支持多种模板语法和控制语句,满足各种复杂的模板需求。
-
与 Java 紧密集成
- 可以方便地与 Java 项目中的数据模型结合,使用起来非常自然。
-
强大的模板功能
- 支持宏、导入、包含等功能,帮助开发者提高模板的复用性和维护性。
-
国际化支持
- 支持国际化,使得模板能够适应多种语言环境。
-
自定义扩展
- 可以通过自定义指令和数据模型扩展 FreeMarker 的功能,满足特定需求。
七、局限性
-
学习曲线
- 对于初学者来说,FreeMarker 的语法和功能可能需要一定的学习和适应。
-
调试难度
- 模板中的错误可能难以定位,调试和错误处理可能较为复杂。
-
性能
- 在处理大量数据或复杂模板时,可能需要对模板缓存和优化进行额外的配置。
-
与现代框架集成
- 在与一些现代框架(如 Thymeleaf)集成时,可能需要额外的配置和适配。
总结来说,FreeMarker 是一个功能强大的模板引擎,适用于多种文本生成场景。其灵活的模板语法和丰富的功能使得它成为开发者生成动态内容的利器。然而,在使用过程中也需要注意其学习曲线和性能问题。通过合理配置和优化,可以充分发挥 FreeMarker 的优势。