Velocity 模板引擎：從獨立應用到 Struts 整合的完整指南

在 HTML、XML 等標準格式中處理文本數據往往繁瑣單調。模板引擎通過靜態模板與動態數據合並，極大簡化此類工作。Velocity 作為成熟開源的模板引擎，憑藉簡潔語法、靈活集成，成為客戶端/服務端應用的理想選擇。本文系統介紹 Velocity 模板語言（VTL）、上下文機制、獨立解析器構建、Servlet 容器部署，以及與 Struts MVC 框架的無縫整合。

核心概念：模板合並

Velocity 模板保留靜態內容，用 $變量 佔位動態部分。合並過程將數據模型與模板結合生成最終輸出。

基礎示例

<!-- template.vm -->
<html>
<body>
<p>Generated by $engine.</p>
<p>Customer: $name</p>
</body>
</html>

// 數據設置
#set($engine = "Velocity")
#set($name = "John Doe")

<!-- 合並輸出 -->
<p>Generated by Velocity.</p>
<p>Customer: John Doe</p>

Velocity 模板語言（VTL）詳解

引用與變量

• 變量：#set($var = "value")，名稱必須以字母開頭。
• 屬性訪問：$customer.lastName 自動映射為 getLastName()。
• 方法調用：$customer.getPhone("mobile") 支持參數傳遞。
• 集合操作：#set($list = ["a","b","c"])，$list.get(1) 取第二項。

靜默引用

$!undefined 若未定義則輸出空字符串，避免模板顯示原始佔位符。

流程控制

#if($user.vip)
  尊貴會員專屬內容
#else
  普通用戶內容
#end

#foreach($item in $items)
  <li>$item</li>
#end

$velocityCounter 內置計數器（從 1 起）可在循環中使用。

宏定義

#macro(showList $list)
  #if($list)
    #foreach($e in $list)$e#end
  #end
#end

#showList($treeList)

支持參數化宏，促進模板腳本復用。

Velocity 上下文機制

上下文是 Java 對象進入模板的唯一通道，必須顯式放入：

VelocityContext ctx = new VelocityContext();
ctx.put("treeFarm", Arrays.asList("pine","oak","maple"));
ctx.put("title", "Tree Farm");
ctx.put("date", new Date());

模板中直接用 $treeFarm、$title 訪問。支持上下文鏈，外層同名屬性覆蓋內層，便於控制可見性。

獨立應用集成步驟

1. 初始化引擎：Velocity.init("velocity.properties")，多實例用 VelocityEngine。
2. 加載模板：Template t = Velocity.getTemplate("file.vm")。
3. 合並輸出：t.merge(ctx, writer)。

服務端部署：VelocityViewServlet

Velocity 封閉模型（默認無任何 Java API 訪問權限）天然實現表現層與業務邏輯分離，優於 JSP 的開放模型。

Tomcat 整合

1. 放入 velocity-tools-view.jar 及核心 jar 至 WEB-INF/lib。
2. web.xml 配置 VelocityViewServlet，映射 *.vm，指定 toolbox.xml。
3. toolbox.xml 註冊工具類（DateTool、MathTool、LinkTool 等）。

<servlet>
  <servlet-name>velocityView</servlet-name>
  <servlet-class>org.apache.velocity.tools.view.servlet.VelocityViewServlet</servlet-class>
  <init-param>
    <param-name>org.apache.velocity.toolbox</param-name>
    <param-value>/WEB-INF/toolbox.xml</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>velocityView</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

與 Struts MVC 整合

VelocityStruts 組件提供專用工具：

• StrutsLinkTool：生成 Action 映射鏈接
• FormTool：訪問表單 Bean
• ErrorsTool/MessageTool：國際化錯誤/消息
• TilesTool/ValidatorTool：支持 Struts 1.1+ 擴展

整合步驟

1. 複製 Velocity 相關 jar 至 Struts 應用 WEB-INF/lib。
2. struts-config.xml 將轉向目標改為 .vm 文件。
3. web.xml 同時配置 ActionServlet（*.do）與 VelocityViewServlet（*.vm），歡迎文件設為 index.vm。
4. 編寫 index.vm，使用 $msg、$link 等工具訪問 Struts 資源。

<title>$msg.get("index.title")</title>
<a href="$link.setURI('editRegistration.do').addQueryData('action','Create')">
  $msg.get("index.registration")
</a>

測試訪問 https://localhost:8080/struts-example/，效果與原 JSP 版完全一致，實現 JSP 与 Velocity 協同工作。

總結

• Velocity 以簡潔 VTL、強制上下文隔離、豐富工具箱，構建清晰分層的視圖層。
• 獨立應用可快速實現報表生成；服務端通過 VelocityViewServlet 成為強大視圖技術。
• 與 Struts 整合無縫，保留現有 Action/Model，僅替換 View，平滑遷移或混合使用。