Velocity 模板引擎核心語法速查與最佳實踐指南

Apache Velocity 是老牌 Java 模板引擎，語法簡潔、邏輯與視圖分離度高。本文整理核心指令、變量引用、流程控制、巨集定義與工程實踐原則，助您快速上手並避免常見誤區。

基礎符號對照表

五大核心指令（覆蓋 90% 場景）

1. 直接輸出： $!obj / $!HtmlUtil.escape($!msg)
2. 條件判斷：

   #if($msg)
   <script>alert('$!msg');</script>
   #end

3. 集合迭代：

   #foreach($item in $hotList)
   <a href="/detail?id=$!item.id">$!item.title</a><br>
   #end

4. 巨集（函數）：

   #macro(orderPic $field)
   #if($orderField == $field)
   <img src="/icons/${orderType}.gif">
   #end
   #end
   #orderPic("title")

5. 模板片段引入： #parse("/common/header.vm")（解析 VM 標籤） vs #include("/static/footer.html")（原樣輸出）。

進階語法速查

#set 變量賦值

#set($i = 0)
#set($list = ["A", "B", "C"])
#set($map = {"key": "value"})  // 實為 Map
#set($i = $i + 1)              // 算術運算支援 + - * / %

註解

## 單行註解
#* 多行
   註解 *#

引用類型

• 變量：$var
• 屬性：$user.name → user.get("name") 或 getName()
• 方法：$user.getName()

形式化引用

#set($user="csy")
${user}name  ## 輸出 csyname

條件與邏輯

#if($foo) ... #elseif($bar) ... #else ... #end
## 邏輯運算子：==  !=  &&  ||  !

迴圈內建計數器

#foreach($c in $list)
$velocityCount. $c.name  ## 從 1 起算
#end
# 預設計數器名稱可在 velocity.properties 覆寫：
directive.foreach.counter.name = velocityCount
directive.foreach.counter.initial.value = 1

範圍運算子

#foreach($i in [1..5]) $i #end  ## 輸出 1 2 3 4 5

工程最佳實踐原則

1. 視圖無業務邏輯： 模板僅做資料呈現，複雜運算、格式化移至 Controller/Helper/Tool 類（如 $DateUtil.format($order.date)）。
2. 禁用 #set 聲明變量： 僅在極少數情況（如迴圈計數）使用，避免模板變成腳本語言。
3. 統一空值處理： 全域配置 eventhandler.referenceinsertion.null = "" 或統一用 $!，杜絕頁面出現 $null 字樣。
4. 巨集集中管理： 將常用巨集放入 macros.vm，頁面以 #parse("macros.vm") 引入，便於複用與維護。
5. 編碼一致性： 模板檔、Java 原始碼、HTTP 回應皆設為 UTF-8，避免中文亂碼。

常見坑點快速排查

遵循「模板只負責渲染」原則，配合 Velocity 簡潔語法，能構建出易維護、高效能的視圖層。