您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 綜合教學

FreeMarker 程序開發實戰：從模板引擎到通用代碼生成器的核心原理與最佳實踐

編輯：Java 綜合教學

FreeMarker 核心定位

FreeMarker 是一個基於模板的文本生成引擎，最初為 Web 視圖層設計（替代 JSP），憑藉強大的宏系統、指令體系、數據模型抽象，早已超越 Web 領域，廣泛應用於：

代碼生成器（MyBatis Mapper、Entity、Controller 骨架）
配置文件生成
靜態頁面預渲染
郵件/報表/文檔模板化輸出

本文系統梳理 FreeMarker 核心概念、配置體系、模板語法進階與非 Web 場景集成方案。

核心架構三大支柱

Configuration：全局單例，持有模板加載器、緩存策略、共享變量、輸出編碼、數據模型包裝器等應用級設置。
Template：預解析後的模板對象，線程安全，可重復 process(dataModel, writer)。
Data Model：鍵值映射（Map/POJO/自定義 TemplateModel），為模板提供動態數據。

快速上手：最小化集成示例

// 1. 構建 Configuration（僅在應用啟動時執行一次）
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
cfg.setDirectoryForTemplateLoading(new File("/path/to/templates"));
cfg.setDefaultEncoding("UTF-8");
cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
cfg.setLogTemplateExceptions(false);
cfg.setWrapUncheckedExceptions(true);
cfg.setSharedVariable("siteName", "MyApp");  // 全局共享變量

// 2. 獲取/緩存 Template
Template template = cfg.getTemplate("user/profile.ftl");

// 3. 準備數據模型
Map model = new HashMap<>();
model.put("user", userService.getById(1L));
model.put("roles", roleService.listByUserId(1L));

// 4. 渲染輸出
try (StringWriter out = new StringWriter()) {
    template.process(model, out);
    String html = out.toString();  // 直接獲取生成內容
    // 寫入文件、返回響應、發送郵件...
}

模板語法精華

1. 變量與表達式

<#-- 基礎輸出 -->
${user.name?html}           <#-- HTML 轉義，防 XSS -->
${user.age!0}               <#-- 缺失值默認 0 -->
${user.tags?join(", ")}     <#-- 序列轉字符串 -->
${(user.balance/100)?string("0.00")}  <#-- 數字格式化 -->
${user.createTime?datetime?string("yyyy-MM-dd HH:mm")}  <#-- 日期格式化 -->

2. 流程控制

<#list users as u>
    <#if u_index == 0>
    <#if u_has_next><#else>
    
        ${u.name}
        <#if u.vip>VIP<#else>普通
    



<#switch status>
    <#case 1>待審核<#break>
    <#case 2>通過<#break>
    <#default>未知

3. 宏與函數：構建可復用 UI 組件庫

<#-- 定義宏 -->
<#macro btn type="primary" size="md" label="按鈕" onclick="">



<#-- 調用宏 -->
<@btn type="success" label="提交" onclick="submitForm()"/>
<@btn label="取消" onclick="closeModal()"/>  <#-- 使用默認值 -->

4. 包含與布局

<#include "common/header.ftl">  <#-- 靜態包含，編譯期合併 -->
<@layout title="用戶詳情">
    <#-- 動態填充區塊 -->
    <#nested>

進階配置與優化

模板加載器選型

加載器	適用場景	特點
FileTemplateLoader	開發/外部化模板	熱加載友好，需文件系統權限
ClassTemplateLoader	打包進 JAR 的內部模板	加載快、不可熱更、適合生產
WebappTemplateLoader	傳統 WAR 部署	基於 ServletContext 獲取資源
MultiTemplateLoader	多源混合	鏈式委託，優先級可控

緩存策略

強緩存：cfg.setTemplateUpdateDelayMilliseconds(-1) — 生產環境推薦，重啟應用生效。
間隔檢查：cfg.setTemplateUpdateDelayMilliseconds(5000) — 開發環境，5秒檢查一次文件變更。
自定義緩存：實現 TemplateCache 接口，接入 Redis/分布式緩存。

對象包裝器

默認 DefaultObjectWrapper 將 POJO/Map/List 自動包裝為 TemplateHashModel/TemplateSequenceModel。可通過 cfg.setObjectWrapper(new DefaultObjectWrapperBuilder(Configuration.VERSION_2_3_32).build()) 微調：

禁止暴露危險方法：wrapper.setExposeFields(false)
自定義枚舉/日期/集合渲染邏輯

非 Web 場景實戰：代碼生成器架構

public class CodeGenerator {
    private final Configuration cfg;

    public CodeGenerator(String templateRoot) throws IOException {
        cfg = new Configuration(Configuration.VERSION_2_3_32);
        cfg.setDirectoryForTemplateLoading(new File(templateRoot));
        cfg.setDefaultEncoding("UTF-8");
    }

    public void generateEntity(TableMeta meta, File outputDir) throws Exception {
        Template tpl = cfg.getTemplate("entity.ftl");
        Map model = Map.of(
            "table", meta,
            "columns", meta.getColumns(),
            "pkg", "com.demo.entity",
            "author", System.getProperty("user.name"),
            "date", LocalDate.now()
        );
        File outFile = new File(outputDir, meta.getClassName() + ".java");
        try (Writer w = new OutputStreamWriter(new FileOutputStream(outFile), "UTF-8")) {
            tpl.process(model, w);
        }
    }
}

配合 entity.ftl 宏定義 getter/setter、Builder、toString 等樣板代碼，可在秒級生成數百個實體類，並保證風格統一。