FreeMarker 入門：最簡單模板引擎示例詳解

FreeMarker 核心概念

FreeMarker 是基於模板的文本生成工具：模板 + 數據模型 = 輸出文本。廣泛用於代碼生成、靜態頁生成、郵件模板、配置文件生成等場景。

依賴獲取

• Maven: org.freemarker:freemarker:2.3.32 (最新穩定版)
• 官網: freemarker.apache.org

方式一：字符串模板 (無文件依賴)

import freemarker.template.Configuration;
import freemarker.template.Template;
import java.io.StringReader;
import java.io.StringWriter;
import java.util.HashMap;
import java.util.Map;

public class StringTemplateDemo {
    public static void main(String[] args) throws Exception {
        // 1. 創建配置 (2.3.32 版本需指定版本)
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
        
        // 2. 從字符串創建模板
        String templateStr = "用戶名：${user}；網址：${url}；站點：${name}";
        Template template = new Template("inline", new StringReader(templateStr), cfg);
        
        // 3. 準備數據模型
        Map model = new HashMap<>();
        model.put("user", "lavasoft");
        model.put("url", "https://www.example.com");
        model.put("name", "示例站點");
        
        // 4. 執行合並輸出
        StringWriter out = new StringWriter();
        template.process(model, out);
        System.out.println(out.toString());
    }
}

輸出：用戶名：lavasoft；網址：https://www.example.com；站點：示例站點

方式二：文件模板 (生產常用)

public class FileTemplateDemo {
    private Configuration cfg;
    
    public void init() throws IOException {
        cfg = new Configuration(Configuration.VERSION_2_3_32);
        // 設置模板加載目錄 (類路徑、文件系統均可)
        cfg.setDirectoryForTemplateLoading(new File("src/main/resources/templates"));
        cfg.setDefaultEncoding("UTF-8");
        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
    }
    
    public void process() throws Exception {
        Map model = new HashMap<>();
        model.put("user", "lavasoft");
        model.put("url", "https://www.example.com");
        model.put("name", "示例站點");
        
        Template template = cfg.getTemplate("welcome.ftl");
        template.process(model, new OutputStreamWriter(System.out, "UTF-8"));
    }
    
    public static void main(String[] args) throws Exception {
        FileTemplateDemo demo = new FileTemplateDemo();
        demo.init();
        demo.process();
    }
}

模板文件 welcome.ftl

<html>
<head><title>Welcome!</title></head>
<body>
<h1>Welcome ${user}!</h1>
<p>Latest product: <a href="${url}">${name}</a>!</p>
<hr>
尊敬的用戶您好：
用戶名：${user}； URL：${url}； 站點：${name}
</body>
</html>

FreeMarker 核心語法速查

最佳實踐建議

• 配置單例：Configuration 線程安全，應用全局共享一個實例。
• 模板緩存：FreeMarker 內建模板緩存，生產環境無需手動緩存。
• 異常處理：設置 RETHROW_HANDLER 讓異常拋出，由上層統一處理。
• 編碼統一：模板文件、輸出流、配置默認編碼全部 UTF-8。
• 安全性：輸出 HTML 時務必使用 ?html 或配置 auto_escaping_policy 防 XSS。

常見問題排查

• TemplateNotFoundException：檢查 setDirectoryForTemplateLoading 路徑、模板文件名大小寫、後綴 .ftl。
• NullPointerException 在 ${var}：變量未放入模型，使用 ${var!} (默認值) 或 ${var??} (判空)。
• 中文亂碼：模板文件保存為 UTF-8、輸出流指定 UTF-8、Configuration 設置 UTF-8。