FreeMarker 入門指南：模板引擎核心概念與基本語法詳解

FreeMarker 入門指南：模板引擎核心概念與基本語法詳解

初次接觸 FreeMarker 時，許多人會問：它究竟是什麼？根據百度百科的定義，FreeMarker 是一款模板引擎。但什麼是模板引擎呢？簡單來說，模板引擎（特別是用於 Web 開發的）旨在將用戶界面與業務數據分離，能夠生成特定格式的文檔，例如標準的 HTML 頁面。換句話說，FreeMarker 就是一個結合了網頁模板與數據模型、用於生成標準 HTML 文檔的工具。正如資深開發者所言：「FreeMarker 其實是一種比較簡單的網頁展示技術，說白了就是網頁模板和數據模型的結合體。」其工作流程為：網頁模板中嵌入了數據模型的數據、FreeMarker 自定義的流程控制語言及操作函數；當頁面被加載時，FreeMarker 會自動從數據模型提取數據，並將整個模板解析為我們熟悉的 HTML 頁面。

FreeMarker 基礎知識

首先必須明確：FreeMarker 並非 Web 應用程序框架，而是一個適用於 Web 框架中的組件。它不感知 HTTP 協議或 Java Servlet 的存在，僅專注於生成文本內容。作為 MVC 框架視圖層的組件，它為如 Struts 這類 Model 2 應用框架提供了解決方案。

FreeMarker 的核心運算公式為：模板 + 數據模型 = 輸出。在 HTML 文件中插入 FreeMarker 指令元素，即可賦予靜態頁面動態效果。對比如下：

原始 HTML 頁面

<h1>Welcome Big Joe!</h1>
<p>Our latest product: green mouse!</p>

FreeMarker 模板

<h1>Welcome ${user}!</h1>
<p>Our latest product: ${latestProduct.name}!</p>

該模板存放於 Web 服務器上，當用戶訪問頁面時，FreeMarker 介入執行，動態替換 ${...} 部分。值得注意的是，模板中未指定如何獲取數據值，這正是 FreeMarker 的特點：作為視圖層組件，其核心思想是表現邏輯與業務邏輯分離。它不關心數據如何獲取，默認數據已準備就緒，數據獲取由程式語言（如 Java）實現。FreeMarker 將所需數據封裝為 data-model（數據模型）。

數據模型結構：樹狀結構

數據模型的基本結構是樹狀的，官方手冊將其比喻為計算機文件系統。可以理解為一個類擁有屬性，例如 latestProduct 擁有 url 和 name 兩個屬性。

圖中變量扮演目錄角色（根 root、animal、mouse、elephant、Python、whatnot）稱為 Hash 哈希表。哈希表通過可查找的名稱（如 "animal"、"mouse"、"price"）訪問存儲的子變量。

關鍵概念（藍色標註部分）：

• Scalars 標量：僅存儲單值的變量（如 size、price、text、because），包含字符串、數字、日期/時間、布爾值類型。
• 路徑訪問：在模板中使用子變量時，需從根 root 開始指定路徑，層級間用點分隔。例如訪問 price：animals.mouse.price。
• Sequences 序列：按順序存儲子變量，不存儲名稱，使用數字索引訪問（索引從 0 開始）。例如獲取第一個動物名稱：animals[0].name。

模板語法詳解

最簡單的模板即 HTML 文件。若需動態效果，需在 HTML 中放置 FreeMarker 可解析的特殊部分：

• ${...} 插值：用於輸出數據模型中的值。
• FTL Tags 標簽：類似 HTML 標簽，但指令不會輸出內容。以 # 開頭（用戶自定義指令用 @）。
• Comments 註釋：格式為 <#-- 註釋內容 -->。
• Directives 指令：FTL 標簽的具體實現（關係類似 HTML 的 table 標簽與 table 元素）。

常用指令示例

if 指令

若判斷 user 不是 "Big Joe"，將跳過 <#if condition> 與標簽間的內容。

list 指令

用於遍歷集合內容：

輸出結果：

通用格式：<#list sequence as loopVariable>repeatThis</#list>

include 指令

可在當前模板插入其他文件內容，例如版權聲明：

輸出內容：

指令聯合使用

例如遍歷動物集合，用大號字體打印大型動物名稱：

處理不存在的變量

FreeMarker 預設不容忍引用不存在的變量（null 值同樣不被容忍），需顯式指定處理方式：

1. 指定默認值：變量名後加 ! 和默認值。例如 ${user!'Anonymous'}，若 user 缺失則使用 "Anonymous"。
2. 判斷變量是否存在：變量名後加 ??。若不存在則忽略整段代碼。例如：

   <#if user??>
     <h1>Welcome ${user}!</h1>
   </#if>