Apache FreeMarker 2.3.35 介绍与选型指南

目标：基于官方文档与官方发布渠道（查询日期 2026-10-18），介绍 Apache FreeMarker 2.3.35 的定位、核心概念、功能特性与同类模板引擎选型建议。本文为认知篇，全部论断溯源至官方来源，不做本地安装实测。

一、信息基准

• 查询日期：2026-10-18（Asia/Shanghai）。
• 本次介绍的版本：Apache FreeMarker 2.3.35。

1.1 版本依据

1.2 官方来源清单

• 官网：https://freemarker.apache.org/
• 下载页：https://freemarker.apache.org/freemarkerdownload.html
• 官方手册（Template Author's Guide / Programmer's Guide）：https://freemarker.apache.org/docs/
• 版本历史：https://freemarker.apache.org/docs/app_versions.html
• GitHub（只读副本，Issue 不在 GitHub 处理）：https://github.com/apache/freemarker
• 在线试用：https://try.freemarker.apache.org/

💡 说明：FreeMarker 自 2.3.24-pre01（2015-09-02）起归 Apache 软件基金会所有；更早版本版权归属不同。官网下载页原注。

二、软件概述

Apache FreeMarker 2.3.35 是一个 Java 模板引擎：一个用来基于模板与变化的数据生成文本输出（HTML 网页、电子邮件、配置文件、源代码等）的 Java 库。模板使用 FreeMarker 模板语言（FTL）编写，它是一门简单、专用的语言，而非 PHP 那样的完整编程语言；数据通常由 Java 等通用语言准备（查库、业务计算），FreeMarker 负责用模板把准备好的数据「展示」出来（官网首页定位原文，2026-10-18 实查）。

这一「模板 + 数据模型 = 输出」的思路常与 MVC 模式结合，用于动态页面，也广泛用于非 Web 场景（代码生成、邮件、报表文本）。FreeMarker 是纯 Java 库，无独立进程，除 Java SE 外无必须依赖（官网下载页明示），许可为 Apache License 2.0。

版本基线方面，2.3.x 系列以向后兼容为最高优先级：官方下载页明示「2.3.x 系列对向后兼容非常保守，替换 freemarker.jar 二进制不应破坏既有应用」。2.3.35 于 2026-08-27 发布，是 2.3.x 当前最新版；另有聚焦下一代引擎的 3.x 开发分支（官网版本历史页）。GitHub 同步副本仓库（apache/freemarker）1,116 stars，最近推送 2026-09-05（GitHub API 实查）。

三、核心概念

3.1 模板、数据模型与输出

FreeMarker 的基本等式是「Template + data-model = output」。模板即静态 HTML（或其他文本）加上 ${...} 插值与 FTL 指令；数据模型是程序准备好的数据总和；引擎在每次渲染时把两者合并为输出。以下引自官方手册《Template + data-model = output》（https://freemarker.apache.org/docs/dgui_quickstart_basics.html）：

<html>
<head>
 <title>Welcome!</title>
</head>
<body>
 <h1>Welcome ${user}!</h1>
 <p>Our latest product:
 <a href="${latestProduct.url}">${latestProduct.name}</a>!
</body>
</html>

对应数据模型（官方手册示意图，树状）：

(root)
 |
 +- user = "Big Joe"
 |
 +- latestProduct
      |
      +- url = "products/greenmouse.html"
      |
      +- name = "green mouse"

3.2 数据模型的三类节点

官方手册把数据模型可视化为树，定义了三类变量：

• hash：像目录一样存放其他变量的节点（user、latestProduct 所在的根与子树）。
• scalar：存放单一值，可为字符串、数值、日期/时间、布尔。
• sequence：无名子变量的有序列表，用数字下标访问（animals[0].name）。

来源：https://freemarker.apache.org/docs/dgui_quickstart_datamodel.html

3.3 Configuration：应用级单例

Configuration 实例承载模板加载路径、编码、异常处理器等全局设置，官方建议在整个应用生命周期只创建一次（配合模板缓存复用）。来源：官方手册《Putting all together》。

3.4 对象适配

Java 对象通过可插拔适配器暴露给模板：模板看到的是数据模型树，而根对象可以是带 getter 的 bean 或 Map。ObjectWrapper 决定「模板如何看见 Java 对象」，这一机制让既有对象模型无需改造即可渲染。来源：官网首页「Versatile data-model」。

四、功能特性

以下特性清单摘译自官网首页「Features」（2026-10-18 实查）：

• 强大的模板语言：条件块、迭代、赋值、字符串与算术运算及格式化、宏与函数、模板 include、默认转义（可选关闭）等。
• 多用途且轻量：零依赖，任意输出格式，模板可从任意位置加载（可插拔），配置项丰富。
• 国际化/本地化感知：按 locale 的数字与日期时间格式化、本地化模板变体。
• XML 处理能力：把 XML DOM 放入数据模型即可遍历，或声明式处理。
• 多变的数据模型：通过可插拔适配器把 Java 对象暴露为变量树。

此外，官网下载页提供 GAE（Google App Engine）兼容变体（freemarker-gae 构件），并强调 2.3.x 替换 jar 的二进制兼容承诺。

五、快速上手

以下完整示例引自官方程序员指南《Putting all together》（https://freemarker.apache.org/docs/pgui_quickstart_all.html ，2026-10-18 实查，示例中版本常量以 2.3.35 为准）：

import freemarker.template.*;
import java.util.*;
import java.io.*;

public class Test {

 public static void main(String[] args) throws Exception {

 /* 在整个应用生命周期内只做一次 */

 /* 创建并调整配置单例 */
 Configuration cfg = new Configuration(Configuration.VERSION_2_3_34);
 cfg.setDirectoryForTemplateLoading(new File("/where/you/store/templates"));
 // 新项目的推荐设置：
 cfg.setDefaultEncoding("UTF-8");
 cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
 cfg.setLogTemplateExceptions(false);
 cfg.setWrapUncheckedExceptions(true);
 cfg.setFallbackOnNullLoopVariable(false);
 cfg.setSQLDateAndTimeTimeZone(TimeZone.getDefault());

 /* 通常在应用生命周期内执行多次 */

 /* 创建数据模型 */
 Map root = new HashMap();
 root.put("user", "Big Joe");
 Product latest = new Product();
 latest.setUrl("products/greenmouse.html");
 latest.setName("green mouse");
 root.put("latestProduct", latest);

 /* 获取模板（内部自带缓存） */
 Template temp = cfg.getTemplate("test.ftlh");

 /* 合并数据模型与模板 */
 Writer out = new OutputStreamWriter(System.out);
 temp.process(root, out);
 }
}

配套模板 test.ftlh 即上文 3.1 的欢迎页模板。官方同页还给出 Product bean 的完整定义。Maven 坐标（官网下载页原文）：

<dependency>
 <groupId>org.freemarker</groupId>
 <artifactId>freemarker</artifactId>
 <version>2.3.35</version>
</dependency>

六、适用场景与限制

6.1 适用场景

• 服务端 HTML 渲染：传统 MVC Web 应用的视图层（含 Spring MVC 集成生态）。
• 动态文本生成：邮件正文、通知/报告文本、配置文件与源代码生成器。
• 非 Web 环境的纯文本模板：无 servlet 依赖，批处理、CLI 工具中同样可用（官网明示不绑定 servlet/HTML）。
• 与设计/开发分工配合的团队：模板聚焦展示，逻辑在 Java 侧准备，改版不改代码。

6.2 限制与注意

• 模板即文本：需要 HTML 自然可读原型（浏览器直接打开可见）的场景，Thymeleaf 的「自然模板」体验更好。
• 2.3.x 为维护性演进：官方把激进创新放在 3.x 方向，2.3.x 以兼容为先（官网版本历史），不要期待大特性。
• 模板内逻辑约束：FTL 是专用语言，复杂业务计算应留在 Java 侧，模板只做展示。
• 安全：模板可执行任意复杂逻辑，不要把不可信来源的模板直接交给引擎渲染（官方在线试用页也仅用于测试自有模板）。

七、同类选型对比

对比口径说明：社区活跃度为 GitHub 仓库 stars（2026-10-18 经 GitHub API 实查），版本为各官方渠道实查的最新稳定版。

选型建议：新建 Spring Boot Web 应用且团队重视 HTML 原型可读性，选 Thymeleaf；已有 FTL 资产、或需要成熟稳定且零依赖的通用文本模板（邮件/代码生成），FreeMarker 2.3.35 仍是低风险选择；从 Jinja2/HubSpot 生态迁移或需要 Jinja 语法兼容，选 Jinjava；Velocity 适合维护存量系统，新项目已少有首选理由。

八、参考链接

• 官网：https://freemarker.apache.org/
• 下载页（版本与许可说明）：https://freemarker.apache.org/freemarkerdownload.html
• 官方手册：https://freemarker.apache.org/docs/
• Quick Start（数据模型）：https://freemarker.apache.org/docs/dgui_quickstart_basics.html
• Programmer's Guide《Putting all together》：https://freemarker.apache.org/docs/pgui_quickstart_all.html
• 版本历史：https://freemarker.apache.org/docs/app_versions.html
• GitHub 仓库（只读副本）：https://github.com/apache/freemarker
• 在线试用模板：https://try.freemarker.apache.org/