本文深入探讨如何在Apache FreeMarker模板中，通过实现Java的`TemplateDirectiveModel`或`TemplateMethodModelEx`接口，创建自定义逻辑来处理模板参数。我们将详细介绍如何从Java代码中获取模板变量的值，并根据业务需求（例如数值比较和默认值设置）进行处理，从而扩展FreeMarker的动态渲染能力，实现模板与业务逻辑的有效分离。
1. 引言：扩展FreeMarker的Java能力
Apache FreeMarker作为一款强大的模板引擎，以其简洁的模板语言和高效的数据绑定能力广受欢迎。在多数情况下，模板语言自身足以处理数据的展示逻辑。然而，当面对更复杂的业务规则、数据验证、格式化或需要与后端Java服务深度交互的场景时，直接在模板中实现这些逻辑可能导致模板变得臃肿、难以维护。
为了解决这一问题，FreeMarker提供了两种强大的扩展机制：自定义指令（Custom Directives）和自定义方法模型（Custom Method Models）。它们允许开发者将复杂的Java业务逻辑封装起来，并在模板中以简洁、声明式的方式调用。本文将以一个具体的场景为例：判断一个账户号参数accNo是否大于0，若不满足条件（例如小于等于0、为空或非数字），则将其设置为默认值“0000”。
2. 使用自定义指令 TemplateDirectiveModel
2.1 概念与应用场景
TemplateDirectiveModel接口允许开发者创建自定义的FreeMarker指令。这些指令可以像FreeMarker内置指令（如、）一样，控制模板的渲染流程，或者像一个带有副作用的函数一样处理参数并输出内容。它们通常用于生成HTML片段、执行复杂的条件渲染或在模板中触发特定的Java逻辑。
立即学习“Java免费学习笔记（深入）”；
2.2 参数传递与获取
在FreeMarker模板中，自定义指令可以像XML/HTML标签一样使用，并接受命名参数。例如：。
在Java实现中，TemplateDirectiveModel接口的execute方法会接收到一个Map类型的params参数，其中包含了所有传递给指令的命名参数。参数的值是TemplateModel类型，需要根据实际数据类型进行相应的转换。
示例场景： 我们希望在模板中通过 来处理一个名为accountNumber的模板变量。
使用模板与程序分离的方式构建，依靠专门设计的数据库操作类实现数据库存取，具有专有错误处理模块，通过 Email 实时报告数据库错误，除具有满足购物需要的全部功能外，成新商城购物系统还对购物系统体系做了丰富的扩展，全新设计的搜索功能，自定义成新商城购物系统代码功能代码已经全面优化，杜绝SQL注入漏洞前台测试用户名：admin密码：admin888后台管理员名：admin密码：admin888
2.3 实现步骤与代码示例
- 创建Java类并实现 TemplateDirectiveModel 接口： 在execute方法中，从params获取名为accNo的参数。 对获取到的TemplateModel进行类型检查和转换（预期为TemplateNumberModel）。 执行业务逻辑：判断数值是否大于0。 将处理后的结果通过env.getOut().write()方法写入到模板的输出流中。
import freemarker.core.Environment;
import freemarker.template.*;
import java.io.IOException;
import java.util.Map;
/**
* 自定义FreeMarker指令，用于处理账户号：
* 如果账户号大于0，则输出其值；否则输出"0000"。
*/
public class AccountNumberDirective implements TemplateDirectiveModel {
@Override
public void execute(Environment env, Map params, TemplateModel[] loopVars, TemplateDirectiveBody body)
throws TemplateException, IOException {
// 1. 从params中获取名为"accNo"的参数
TemplateModel accNoModel = (TemplateModel) params.get("accNo");
String processedAccNo = "0000"; // 默认值
// 2. 检查参数类型并执行业务逻辑
if (accNoModel instanceof TemplateNumberModel) {
Number accNo = ((TemplateNumberModel) accNoModel).getAsNumber();
if (accNo != null && accNo.doubleValue() > 0) {
// 如果是有效数字且大于0，则使用其长整型字符串表示
processedAccNo = String.valueOf(accNo.longValue());
}
} else if (accNoModel instanceof TemplateScalarModel) {
// 考虑accNo可能作为字符串传入的情况
String accNoStr = ((TemplateScalarModel) accNoModel).getAsString();
try {
double accNoDouble = Double.parseDouble(accNoStr);
if (accNoDouble > 0) {
processedAccNo = accNoStr; // 如果字符串是有效数字且大于0，则保留原字符串
}
} catch (NumberFormatException e) {
// 字符串无法解析为数字，保持默认值"0000"
}
}
// 如果accNoModel为null或非数字类型，则保持默认值"0000"
// 3. 将处理结果写入模板输出流
env.getOut().write(processedAccNo);
}
}2.4 FreeMarker模板使用示例
<#-- 假设数据模型中存在以下变量 --> <#assign accNoVar = 12345 /> <#assign zeroAccNoVar = 0 /> <#assign negativeAccNoVar = -10 /> <#assign nullAccNoVar = null /> <#assign stringAccNoVar = "abc" />使用自定义指令处理账户号:
- 账户号1 (12345): <@processAccNo accNo=accNoVar />
- 账户号2 (0): <@processAccNo accNo=zeroAccNoVar />
- 账户号3 (-10): <@processAccNo accNo=negativeAccNoVar />
- 账户号4 (null): <@processAccNo accNo=nullAccNoVar />
- 账户号5 ("abc"): <@processAccNo accNo=stringAccNoVar />
2.5 注意事项
- 指令主要用于输出内容或控制渲染流程，不直接返回一个值供模板进行进一步的表达式计算。
- 如果指令不接受参数，但仍需访问模板变量，可以使用env.getVariable("variableName")。但这会增加指令与模板数据模型的耦合度，通常不推荐。
3. 使用自定义方法模型 TemplateMethodModelEx
3.1 概念与应用场景
TemplateMethodModelEx接口允许开发者创建自定义的FreeMarker方法。这些方法可以像FreeMarker内置函数（如size()、substring()）一样被调用，并返回一个值供模板进一步使用。对于需要计算一个值并将其返回给模板进行后续处理的场景，TemplateMethodModelEx通常是更典型和推荐的选择。
3.2 参数传递与获取
在FreeMarker模板中，自定义方法以函数调用的形式使用，例如 ${myMethod(param1, param2)}。
在Java实现中，TemplateMethodModelEx接口的exec方法会接收到一个List类型的arguments参数，其中包含了所有传递给方法的参数（按顺序）。与指令类似，参数的值也是TemplateModel类型，需要进行相应的类型转换。
示例场景： 我们希望在模板中通过 ${formatAccNo(accountNumber)} 来获取处理后的账户号。
3.3 实现步骤与代码示例
- 创建Java类并实现 TemplateMethodModelEx 接口： 在exec方法中，从arguments列表获取参数（通常是第一个）。 执行业务逻辑，判断数值是否大于0。 返回一个TemplateModel（如SimpleScalar、SimpleNumber等）作为结果。
import freemarker.template.*;
import java.util.List;
/**
* 自定义FreeMarker方法，用于格式化账户号：
* 如果账户号大于0，则返回其字符串值；否则返回"0000"。
*/
public class AccountNumberMethod implements TemplateMethodModelEx {
@Override
public Object exec(List arguments) throws TemplateModelException {
// 1. 检查参数数量
if (arguments.isEmpty()) {
throw new TemplateModelException("AccountNumberMethod expects at least one argument (accNo).");
}
// 2. 获取第一个参数
TemplateModel accNoModel = (TemplateModel) arguments.get(0);
String processedAccNo = "0000"; // 默认值
// 3. 检查参数类型并执行业务逻辑
if (accNoModel instanceof TemplateNumberModel) {
Number accNo = ((TemplateNumberModel) accNoModel).getAsNumber();
if (accNo != null && accNo.doubleValue() > 0) {
processedAccNo = String.valueOf(accNo.longValue());
}
} else if (accNoModel instanceof TemplateScalarModel) {
// 考虑accNo可能作为字符串传入的情况
String accNoStr = ((TemplateScalarModel) accNoModel).getAsString();
try {
double accNoDouble = Double.parseDouble(accNoStr);
if (accNoDouble > 0) {
processedAccNo = accNoStr; // 如果字符串是有效数字且大于0，则保留原字符串
}
} catch (NumberFormatException e) {
// 字符串无法解析为数字，保持默认值"0000"
}
}
// 如果accNoModel为null或非数字类型，则保持默认值"0000"
// 4. 返回处理结果，通常是SimpleScalar或SimpleNumber
return new SimpleScalar(processedAccNo);
}
}3.4 FreeMarker模板使用示例
<#-- 假设数据模型中存在以下变量 --> <#assign accNoVar = 54321 /> <#assign zeroAccNoVar = 0 /> <#assign negativeAccNoVar = -10 /> <#assign nullAccNoVar = null /> <#assign stringAccNoVar = "abc" />使用自定义方法模型处理账户号:
- 账户号1 (54321): ${formatAccNo(accNoVar)}
- 账户号2 (0): ${formatAccNo(zeroAccNoVar)}
- 账户号3 (-10): ${formatAccNo(negativeAccNoVar)}
- 账户号4 (null): ${formatAccNo(nullAccNoVar)}
- 账户号5 ("abc"): ${formatAccNo(stringAccNoVar)}
4. 注册自定义指令/方法到FreeMarker配置
无论是自定义指令还是自定义方法模型
