Apache FreeMarker 常用 CLI 命令与工具详解

FreeMarker 核心是一个 Java 类库，同时提供命令行工具 freemarker-cli 以及 freemarker.template.utility 下的若干工具类。本文汇总这些命令与工具类的用法，并给出配套 Maven 命令，全部基于 FreeMarker 2.3.35 实测。

一、命令行工具 freemarker-cli

1.1 获取与版本

org.freemarker:freemarker-cli 并未发布到 Maven 中央仓库（查询返回 404）。可用的命令行工具为 Apache 许可的独立发行版 freemarker-cli，以压缩包形式提供：

curl -sL -o fmcli.tgz https://github.com/sgoeschl/freemarker-cli/releases/download/v2.0.0-BETA-5/freemarker-cli-2.0.0-BETA-5-app.tar.gz
tar xzf fmcli.tgz
cd freemarker-cli-2.0.0-BETA-5
./bin/freemarker-cli --version

真实回显：

version=2.0.0-BETA-5, time=2019-12-23T16:28:24+0100, commit=79bd04cac1a257718550fe7f9f31a29c9341db6e

1.2 命令语法

./bin/freemarker-cli (-t=<template> | -i=<interactiveTemplate>) [-EhV]
                     [--stdin] [-b=<baseDir>] [--config=<configFile>]
                     [-e=<inputEncoding>] [--include=<include>] [-l=<locale>]
                     [-o=<outputFile>] [--output-encoding=<outputEncoding>]
                     [--times=<times>] [-D=<String=String>]... [<sources>...]

1.3 参数详解

参数	含义
`-t, --template=<template>`	指定要渲染的 FreeMarker 模板文件
`-i, --interactive=<template>`	使用交互式模板（自带 `?ask` 等交互能力）
`-o, --output=<outputFile>`	输出文件路径；缺省输出到标准输出
`-b, --basedir=<baseDir>`	模板基础目录
`<sources>...`	输入数据文件或目录（支持 JSON/YAML/CSV/XML 等）
`--stdin`	从标准输入读取输入文档
`--include=<include>`	目录输入时按模式过滤文件
`-e, --input-encoding`	输入文件编码
`--output-encoding`	输出文件编码
`-l, --locale=<locale>`	输出使用的 Locale，如 `en_US`
`--config=<configFile>`	指定 CLI 配置文件
`-D=<String=String>`	设置系统属性
`-E, --expose-env`	向模板暴露环境变量与系统属性
`--times=<times>`	重复运行指定次数，用于性能压测
`-h, --help`	显示帮助
`-V, --version`	显示版本

1.4 使用示例（真实回显）

准备数据文件 users.json：

[
  {"name": "Alice", "email": "alice@example.com"},
  {"name": "Bob", "email": "bob@example.com"}
]

准备模板 demo.ftl（CLI 提供 Documents、JsonPathTool、SystemTool 等内置对象）：

Users via freemarker-cli:
<#assign json = JsonPathTool.parse(Documents.get(0))>
<#assign users = json.read("$[*]")>
<#list users as u>
- ${u.name} <${u.email}>
</#list>

执行渲染：

./bin/freemarker-cli -t /root/cli-t/demo.ftl /root/cli-t/users.json -o /root/cli-t/out.txt

输出文件 out.txt 内容：

Users via freemarker-cli:
- Alice <alice@example.com>
- Bob <bob@example.com>

同时可使用发行包自带的 HTML 样例验证：

./bin/freemarker-cli -t templates/json/ftl/customer-user-products.ftl site/sample/json/customer-user-products.json -o /root/cli-out.html

二、内置工具类 freemarker.template.utility.*

以下类随 freemarker-2.3.35.jar 一同发布，放入数据模型即可在模板中调用（除注明需谨慎者外）。

2.1 Execute（执行系统命令，需谨慎）

签名：public class Execute implements TemplateMethodModel，方法 exec(List)。
用途：在模板中执行 shell 命令并返回其标准输出。示例：

Map<String, Object> root = new HashMap<String, Object>();
root.put("exec", new freemarker.template.utility.Execute());

Result of Execute: ${exec("echo hello-from-freemarker")}

真实回显：

=== Execute output ===
Result of Execute: hello-from-freemarker

安全提示：Execute 可执行任意系统命令，等同于远程命令执行入口。除非经过严格沙箱与审计，切勿将其暴露给不可信模板或用户可控模板，生产环境应完全禁用。

2.2 DateUtil

用途：ISO 8601 / XS（XML Schema）日期时间的解析与格式化。
常用成员：
- 精度常量 ACCURACY_HOURS/MINUTES/SECONDS/MILLISECONDS；
- getTimeZone(String)：按名称取时区（UTC 常量可直接用）；
- dateToISO8601String(Date, ...)、dateToXSString(Date, ...)：格式化为 ISO/XS 字符串；
- parseISO8601Date(String, TimeZone, ...)、parseXSDate/parseXSTime：反向解析。

2.3 ObjectConstructor

用途：在模板中按类名实例化对象，常作为「对象包装工具」暴露给模板。属于高权限能力，需配合 SecurityUtilities 或在可信模板中使用。

2.4 StringUtil 与 NumberUtil

StringUtil 提供转义方法：HTMLEnc、XHTMLEnc、XMLEnc、XMLEncNA、XMLEncQAttr、XMLEncNQG、RTFEnc 等，可在不启用自动转义时手工转义。
NumberUtil 提供数字处理辅助方法（如类型判断与转换）。

2.5 NormalizeNewlines / HtmlEscape / XmlEscape / StandardCompress

NormalizeNewlines：把不同平台的换行统一为 \n。
HtmlEscape / XmlEscape：可放入数据模型作为转义方法（效果类似 <#escape> 指令）。
StandardCompress：压缩输出中多余的空白，减小产物体积。

2.6 CaptureOutput / DeepUnwrap / ClassUtil / JythonRuntime

CaptureOutput：捕获模板片段的输出到变量。
DeepUnwrap：把 FreeMarker 模板模型深度还原为普通 Java 对象。
ClassUtil：类加载相关的辅助方法。
JythonRuntime：调用 Jython 脚本（需额外引入 Jython 依赖，非核心功能）。

2.7 关于 XMLRPC

历史版本曾提供 freemarker.template.utility.XMLRPC，但在 2.3.35 的 jar 中已不存在（经核查完成移除）。若需 XML-RPC 能力，应改用独立的第三方库，不要依赖此类。

三、Maven 常用命令

3.1 依赖管理

# 查看依赖树，确认 freemarker 版本
mvn -B dependency:tree

# 导出运行时 classpath 到文件，便于直接用 java -cp 运行
mvn -B dependency:build-classpath -Dmdep.outputFile=cp.txt

# 单独下载某坐标构件
mvn -B dependency:get -Dartifact=org.freemarker:freemarker:2.3.35

# 检查依赖是否有可升级版本
mvn -B versions:display-dependency-updates

3.2 构建与运行

# 清理并编译
mvn -B clean compile

# 打包为 jar
mvn -B clean package

# 直接运行主类（工作目录为工程根）
mvn -B exec:java -Dexec.mainClass=Demo

mvn exec:java 实测回显：

Hello quzuo!
Items (3.00):
- ALPHA
- BETA
- GAMMA
-- generated for QUZUO --
Price: 1234.50
Active: yes
Now: 2026-10-11 / 2026-10-11 23:49:40
Version: 2.3.35
=== render to file: out.html ===
bytes written: 157

3.3 直接以 java 运行

java -Xms256m -Xmx256m -cp "target/classes:$(cat cp.txt)" Demo

-Xms256m -Xmx256m 将 JVM 堆限定为 256MB，符合 256–512MB 的推荐区间，适合模板渲染这类低内存占用场景。

四、安全与使用建议

优先自动转义：输出 HTML/XML 时通过 setOutputFormat 启用自动转义，只有确需原样输出时才使用 ?no_esc。
禁用 Execute：Execute 与 ObjectConstructor 属于高权限能力，生产环境应在 Configuration 层限制可用类（setNewBuiltinClassResolver / TemplateClassResolver），或彻底不注入。
模板来源可信：FreeMarker 模板可访问数据模型中的任意对象方法，模板本身应来自可信来源，避免用户上传模板直接渲染。
沙箱：SecurityUtilities 可在白名单机制下读取系统属性，配合类解析白名单可显著收敛攻击面。