Apache FreeMarker自定义指令与方法：使用Java代码处理模板参数

苏承栈

2026-10-04 • 👁 0人浏览过

本文深入探讨如何在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内置指令（如<#if>、<#list>）一样，控制模板的渲染流程，或者像一个带有副作用的函数一样处理参数并输出内容。它们通常用于生成HTML片段、执行复杂的条件渲染或在模板中触发特定的Java逻辑。立即学习 “ Java免费学习笔记（深入） ”； 2.2 参数传递与获取在FreeMarker模板中，自定义指令可以像XML/HTML标签一样使用，并接受命名参数。例如：<@myDirective paramName=paramValue />。在Java实现中，TemplateDirectiveModel接口的execute方法会接收到一个Map类型的params参数，其中包含了所有传递给指令的命名参数。参数的值是TemplateModel类型，需要根据实际数据类型进行相应的转换。 Eclipse导入Android或其他的JAVA项目的正确方法 WORD版本文档主要讲述的是Eclipse导入Android或其他的JAVA项目的正确方法；希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看下载示例场景：我们希望在模板中通过 <@processAccNo accNo=accountNumber /> 来处理一个名为accountNumber的模板变量。 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 />

<#-- 预期输出:
账户号1 (12345): 12345
账户号2 (0): 0000
账户号3 (-10): 0000
账户号4 (null): 0000
账户号5 ("abc"): 0000
-->

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

<#-- 预期输出:
账户号1 (54321): 54321
账户号2 (0): 0000
账户号3 (-10): 0000
账户号4 (null): 0000
账户号5 ("abc"): 0000
-->

4. 注册自定义指令/方法到FreeMarker配置无论是自定义指令还是自定义方法模型

相关文章