Freemarker 模板引擎入门

1. 一句话简介

FreeMarker 是 Apache 基金会的开源 Java 模板引擎，核心作用是把「数据」与「页面展现」分离：模板文件（.ftl）只描述页面结构和占位符，渲染时由服务端注入数据后输出 HTML。在本模块 demo-template-freemarker 中，控制器通过 ModelAndView.addObject(user) 把用户对象放入模型，模板用 ${user.name} 做变量插值、用 <#include> 复用公共片段，最终在 templates/ 目录下生成完整的网页。它解决的核心问题是服务端渲染（SSR）：无需前端框架，Java 后端一个请求就能产出可被搜索引擎收录、可直接展示的 HTML 页面。

2. 什么时候使用

✅ 服务端渲染（SSR）的 Web 页面：需要后端直接生成 HTML 返回浏览器，如本模块的登录页、欢迎页，无需异步刷新。
✅ 对 SEO 有要求的页面：搜索引擎能直接抓取渲染后的 HTML 内容，适合官网、门户、博客等页面。
✅ 页面结构以套用模板为主、数据在服务端组装：登录、表单、报表、静态化页面等场景，模板语言足够表达。
✅ 追求渲染性能：FreeMarker 模板编译后缓存，性能高，适合高并发读取型页面。
✅ 需要公共片段复用的多页面站点：通过 <#include> 抽取公共 <head>、导航栏等，维护方便，正如本模块 common/head.ftl 被多个页面复用。
❌ 前后端分离的 SPA 应用：页面数据交互为主、渲染交给 Vue/React 的体系，SSR 模板引擎价值有限，应改用 JSON API + 前端框架。
❌ 模板需要深度逻辑控制：FreeMarker 模板语言能力偏静态、可调试性弱，复杂业务逻辑应放在 Java 层，否则难维护。
❌ 高度交互、频繁局部更新：需要 WebSocket、增量更新、复杂状态管理时，模板引擎并不擅长。
❌ 对 HTML 兼容性有强约束的团队：FreeMarker 语法（# 指令、${} 插值）不是标准 HTML 属性，前端人员需额外学习，脚本化语法在视觉上不像 Thymeleaf 那样贴近 HTML。

3. 常见业务场景

服务端渲染的登录与鉴权页面：本模块演示了经典流程——访问首页时从 Session 读取用户，未登录则重定向到登录页，登录成功后写入 Session 再回到首页展示欢迎信息。这类「判断登录态、按权限出页面」的场景，后端渲染由 Java 直接操控转向逻辑，天然贴合 FreeMarker。

模板插值展示动态数据：${user.name}、${list} 等变量插值把 Java 对象的属性直接呈现到页面，本模块欢迎页正是借此输出用户名。报表、详情页、编辑器联动等「数据变、结构不变」的页面都适用。

公共页面片段复用：用 <#include> 把 <head>、导航栏、页脚等公共部分抽成独立 .ftl 文件，多个页面一处维护。本模块的 common/head.ftl 就被登录页与欢迎页共同引入，避免重复代码。

页面静态化 / 内容导出：FreeMarker 可将模板与数据渲染成静态 HTML 文件，用于高并发内容页面（数据变化不频繁的新闻、商品详情）或导出邮件/报表内容，减轻服务端渲染压力。

复杂页面结构用宏（macro）组织：当页面包含重复的列表块、卡片组件时，FreeMarker 的 <#macro> 可参数化复用，简化多模块页面的模板组织。

4. 同类技术对比

维度	FreeMarker	Thymeleaf	Beetl	Enjoy
归属生态	Apache 老牌项目，成熟稳定	Spring/Thymeleaf 官方主推	国产开源，中文文档好	JFinal 框架自带
Spring Boot 集成	官方 starter，零配置	官方 starter，零配置	第三方 starter	需手动配置 ViewResolver
模板语法	`${var}`、`<#include>`、`/#>` 指令，独立于 HTML	`th:text` 等基于 HTML 属性	`${var}`、`<% %>`，类 JSP	`#(var)`、`#include`，JFinal 风格
HTML 兼容性	低，模板本身不是合法 HTML	高，模板即合法 HTML，可被浏览器/FE 直接编辑	低	中
渲染性能	高	中	高	高
学习成本	中等，独立语法需专门学	低，前端人员上手快	低，类 JSP	低，语法简洁
社区与维护	成熟、长期维护	Spring 官方背书，社区活跃	国内生态	绑定 JFinal 生态

选型建议：若团队重视「模板即合法 HTML、前端可直接协作编辑」，或项目正深度绑定 Spring 生态，选 Thymeleaf，这也是 Spring 官方推荐方向；若更看重渲染性能、且页面结构和数据都在服务端由 Java 掌控，选 FreeMarker（Apache 老牌、性能高、生态成熟）最稳妥；若团队倾向类 JSP 的轻量语法且看重中文文档，可选 Beetl；Enjoy 仅在基于 JFinal 的项目中才值得考虑。整体上：Spring 官方团队 + 前端协作为重选 Thymeleaf，后端主导 + 性能优先选 FreeMarker。