在Java开发中，将FTL（FreeMarker Template Language）嵌入Java代码是一种常见的技术实践，主要用于实现动态页面生成、邮件模板渲染、报告生成等场景，FreeMarker作为一种模板引擎，通过将Java数据与模板文件分离，实现了业务逻辑与展示逻辑的解耦，本文将详细介绍FTL如何嵌入Java代码，包括环境搭建、核心配置、数据传递、模板语法及实战案例等内容。
环境搭建与依赖引入
要在Java项目中使用FTL，首先需要添加FreeMarker的依赖，以Maven项目为例，在pom.xml文件中引入以下依赖：
<dependency>
<groupId>org.freemarker</groupId>
<artifactId>freemarker</artifactId>
<version>2.3.32</version>
</dependency>
引入依赖后，需创建FreeMarker的配置实例，这是连接Java代码与FTL模板的核心桥梁，配置过程中需指定模板加载路径、编码格式及全局设置，
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
cfg.setDirectoryTemplateLoader(new FileTemplateLoader(new File("templates")), "UTF-8");
cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
上述代码中，DirectoryTemplateLoader负责从指定目录加载模板文件，TemplateExceptionHandler定义了模板解析错误的处理策略。
模板加载与数据模型绑定
Java代码通过Configuration实例加载FTL模板文件，并创建Template对象,加载模板时需处理文件不存在或语法错误等异常情况，
try {
Template template = cfg.getTemplate("example.ftl");
} catch (IOException e) {
throw new RuntimeException("模板加载失败", e);
}
加载模板后，需构建数据模型（Data Model）并传递给模板，数据模型通常是Map或自定义Java对象,用于存储模板中需要动态渲染的数据。
Map<String, Object> dataModel = new HashMap<>();
dataModel.put("username", "张三");
dataModel.put("age", 25);
dataModel.put("hobbies", Arrays.asList("阅读", "编程", "旅行"));
模板语法与Java数据交互
FTL模板通过特定的语法引用Java数据模型中的数据，基础语法包括变量插值、条件判断、循环遍历等,变量插值使用语法，
欢迎您，${username}！您今年${age}岁。
条件判断通过if标签实现，支持gt（大于）、lt（小于）等比较运算符：
<#if age gt 18> 您已成年。 <#else> 您未成年。 </#if>
循环遍历使用list或foreach标签，
您的爱好：
<#list hobbies as hobby>
- ${hobby}
</#list>
对于复杂对象，可通过点语法访问属性，如${user.address.city}，若需调用Java方法，可通过后缀实现，例如${date?string("yyyy-MM-dd")}将日期格式化为指定字符串。
高级特性：自定义指令与宏
FreeMarker支持通过自定义指令（Macro）封装可复用的模板片段，在Java代码中，可通过put方法将宏定义注入数据模型，
dataModel.put("renderList", new SimpleScalar(""));
在模板中定义宏并调用：
<#macro renderList items>
<#list items as item>
${item}
</#list>
</#macro>
<@renderList items=hobbies/>
FreeMarker支持命名空间、函数扩展等高级功能，可通过Configuration的setSharedVariable方法设置全局变量，
cfg.setSharedVariable("dateUtils", new DateUtils());
在模板中直接调用：${dateUtils.formatNow()}。
实战案例：动态生成HTML邮件
以下是一个完整的实战案例，展示如何通过Java代码嵌入FTL模板生成HTML邮件，首先创建模板文件email.ftl：
<!DOCTYPE html>
<html>
<head>欢迎邮件</title>
</head>
<body>
<h1>尊敬的${username}，您好！</h1>
<p>您的注册信息如下：</p>
<ul>
<li>用户名：${username}</li>
<li>邮箱：${email}</li>
<li>注册时间：${registerTime?string("yyyy年MM月dd日 HH:mm:ss")}</li>
</ul>
<#if isVip>
<p>您是我们的VIP用户，享受专属特权！</p>
</#if>
</body>
</html>
在Java代码中加载模板并渲染：
public class EmailGenerator {
public static String generateEmail(String username, String email, boolean isVip) {
try {
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
cfg.setDirectoryTemplateLoader(new FileTemplateLoader(new File("templates")), "UTF-8");
Map<String, Object> dataModel = new HashMap<>();
dataModel.put("username", username);
dataModel.put("email", email);
dataModel.put("registerTime", new Date());
dataModel.put("isVip", isVip);
Template template = cfg.getTemplate("email.ftl");
StringWriter writer = new StringWriter();
template.process(dataModel, writer);
return writer.toString();
} catch (Exception e) {
throw new RuntimeException("邮件生成失败", e);
}
}
}
调用EmailGenerator.generateEmail()方法即可生成完整的HTML邮件内容。
性能优化与最佳实践
在实际开发中，为提升FreeMarker的性能，需注意以下几点：
- 重用Configuration实例：避免频繁创建
Configuration对象，建议在应用启动时初始化并全局共享。 - 模板缓存：FreeMarker默认启用模板缓存，开发环境可通过
cfg.setTemplateUpdateDelayMilliseconds(0)关闭缓存以便调试。 - 避免复杂逻辑：模板中应尽量少包含复杂的业务逻辑，保持模板的简洁性。
- 异常处理：合理配置
TemplateExceptionHandler，避免将异常信息直接暴露给模板。
通过以上方法，可有效实现FTL与Java代码的深度集成，提升开发效率并保证系统的可维护性,FreeMarker的灵活性与强大功能使其成为Java项目中动态内容生成的理想选择。
