Velocity 模版加載機制詳解：Classpath 與 Webapp 兩種資源載入模式

Velocity 核心配置：velocity.properties

Velocity 通過 ResourceLoader 載入模版，兩種主流模式：

模式一：Classpath 資源載入（適合獨立應用、單元測試、Jar 包內模版）

配置

file.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader
input.encoding = UTF-8
output.encoding = UTF-8

目錄結構

src/main/resources/
  velocity.properties
  templates/
    list.vm

Java 代碼手動初始化引擎

VelocityEngine ve = new VelocityEngine();
InputStream is = this.getClass().getResourceAsStream("/velocity.properties");
Properties props = new Properties();
props.load(is);
ve.init(props);
Template template = ve.getTemplate("templates/list.vm");  // classpath 相對路徑
context.put("orders", orders);
StringWriter writer = new StringWriter();
template.merge(context, writer);
return writer.toString();

Servlet 整合（繼承 VelocityViewServlet）

public class ListServlet extends VelocityViewServlet {
    @Override
    protected Template handleRequest(HttpServletRequest req, HttpServletResponse resp, Context ctx) {
        // ... 準備數據 ...
        ctx.put("orders", orders);
        // 手動初始化引擎（或依賴父類已初始化）
        VelocityEngine ve = new VelocityEngine();
        InputStream is = getClass().getResourceAsStream("/velocity.properties");
        Properties props = new Properties();
        props.load(is);
        ve.init(props);
        return ve.getTemplate("templates/list.vm");
    }
}

模式二：Webapp 資源載入（適合 Web 應用、模版放 WEB-INF 熱部署修改）

配置

resource.loader = webapp
webapp.resource.loader.class = org.apache.velocity.tools.view.servlet.WebappLoader
webapp.resource.loader.path = /WEB-INF/vm/
input.encoding = UTF-8
output.encoding = UTF-8

目錄結構

src/main/webapp/
  WEB-INF/
    vm/
      list.vm
    velocity.properties
    web.xml

Servlet 代碼簡化

public class ListServlet extends VelocityViewServlet {
    @Override
    protected Template handleRequest(HttpServletRequest req, HttpServletResponse resp, Context ctx) {
        // ... 準備數據 ...
        ctx.put("orders", orders);
        return getTemplate("list.vm");  // 父類自動使用 WebappLoader 解析路徑
    }
}

web.xml 關鍵配置

<servlet>
  <servlet-name>velocity</servlet-name>
  <servlet-class>org.apache.velocity.tools.view.servlet.VelocityViewServlet</servlet-class>
  <init-param>
    <param-name>properties-file</param-name>
    <param-value>/WEB-INF/velocity.properties</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>velocity</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

兩種模式對比

模版文件示例 list.vm

<html>
<body>
#foreach($order in $orders)
  $order.item  $order.type  $order.price<br/>
#end
</body>
</html>

總結

• Classpath 模式**適合**打包部署、模版不變、追求性能與隔離的場景。
• Webapp 模式**適合**開發期頻繁修改模版、傳統 Servlet 容器部署。
• 現代 Spring Boot 整合 Velocity 通常採用 spring-boot-starter-velocity 自動配置，屬於 Classpath 模式增強版。
• 理解 ResourceLoader 機制，能快速排查「模版找不到」「編碼亂碼」「修改不生效」等常見問題。