Apache Velocity 2.4.1 介绍与选型指南

一、信息基准

本章列明本文事实性信息的核查时间与来源，全部信息取自 Apache Velocity 官方渠道，不含本地实测推算。

1.1 版本基准

1.2 官方来源清单

二、软件概述

本文介绍的是 Apache Velocity Engine 2.4.1（配套 Velocity Tools 3.1）。官网对 Velocity 的定位是：基于 Java 的模板引擎，"100% pure Java"，可轻松嵌入应用程序，用模板语言（Velocity Template Language，VTL）引用 Java 对象定义的数据，从而把 Java 代码与页面/文本模板解耦。

Velocity 是 Apache 顶级项目（projects.apache.org PMC 列表收录 velocity），历史悠久、生态成熟。当前子项目结构：Engine（模板引擎核心，最新稳定版 2.4.1）与 Tools（通用工具与 Web 视图工具集，最新稳定版 3.1）；历史上著名的 Anakia、Texen、DVSL、DocBook Fx 等子项目已归档（官网 Archive 栏目分别标注 1.0 版本）。

典型用途包括：Web 页面渲染、代码生成、邮件内容生成、配置/文档文本生成等一切"数据 + 文本模板"的场景。2.5 已进入 RC 阶段（2026-09 发布 2.5-RC2），本文以官方最新稳定版 2.4.1 为基准。

三、核心架构

3.1 运行时结构

依据官方开发者指南，Velocity Engine 的对外接口被刻意收窄：

• 单例模式：通过 org.apache.velocity.app.Velocity 类直接使用全局运行时，适合简单应用。
• 实例模式：通过 org.apache.velocity.app.VelocityEngine 创建独立引擎实例，可各自配置模板目录、日志等，官方推荐在需要多套配置的应用中使用。
• 官方明确要求应用不要直接使用 org.apache.velocity.runtime 包内部的 Runtime、RuntimeConstants、RuntimeSingleton、RuntimeInstance 等内部类。

3.2 模板处理流程

一个模板的典型处理链路（官方开发者指南的示例结构）：

1. 初始化引擎（ve.init()，可先 setProperty 定制配置）。
2. 通过 ve.getTemplate("foo.vm") 加载模板文件。
3. 组织 VelocityContext 数据（键值对映射到模板中的引用 $reference）。
4. 调用模板的 merge(context, writer)，把数据代入模板渲染到输出流。

3.3 VTL 模板语言

官方 VTL Reference 归纳的语言要素：

• 引用（References）：以 $ 开头的变量/属性/方法引用，用于输出数据。
• 指令（Directives）：以 # 开头的控制语句，官方参考手册列出的指令包括 #set、#if/#elseif/#else、#foreach、#include、#parse、#break、#define、#evaluate、#macro 等。
• 注释与未解析内容：## 行注释、#* *# 块注释，以及 #[[ ]]. 非解析文本块（官方手册均有独立章节）。

四、功能特性

4.1 引擎能力

• 纯 Java 实现、易嵌入：官网强调可嵌入任意 Java 应用，无需外部依赖服务。
• 单例与多实例两种运行模式，支持同应用多套模板/日志配置（官方开发者指南）。
• 模板加载策略可配置（模板目录等由引擎属性控制），渲染输出为任意 Writer。
• 稳定的 Java 8 兼容基线（2.4.1 字节码 52），对遗留系统友好。

4.2 Velocity Tools 3.1

配套工具子项目提供两类工具集：通用工具（如数学、日期、集合等常用工具）与面向 Web/视图环境的工具（官方 Tools 子项目文档），配合 Engine 使用可减少模板中的重复胶水代码。

4.3 生态位

• 代码生成：很多构建期代码生成器用 VTL 作为代码模板。
• 文本产物生成：邮件模板、报告文本、脚本生成等。
• Web 渲染：历史上大量 Web 框架集成 Velocity 视图（配合 Tools 的视图工具），2.5 线仍在维护（2026-09 发布 2.5-RC2，说明项目持续活跃而非停止维护）。

五、快速上手

以下示例引自官方开发者指南（velocity.apache.org/engine/2.4/developer-guide.html）中的引擎用法，本文不做本地实测。

5.1 实例模式（官方推荐结构）

官方开发者指南给出的 VelocityEngine 用法（节选自官方示例）：

import org.apache.velocity.app.VelocityEngine;
import org.apache.velocity.Template;

// create a new instance of the engine
VelocityEngine ve = new VelocityEngine();
// configure the engine（如按需设置属性）
ve.setProperty(VelocityEngine.RUNTIME_LOG_NAME, "mylog");
// initialize the engine
ve.init();

Template t = ve.getTemplate("foo.vm");

数据侧使用 VelocityContext 组织键值，渲染侧调用 t.merge(context, writer) 输出结果，官方指南对该链路有完整示例。

5.2 Maven 引入

引擎核心构件（Maven Central 坐标）：

<dependency>
    <groupId>org.apache.velocity</groupId>
    <artifactId>velocity-engine-core</artifactId>
    <version>2.4.1</version>
</dependency>

工具集构件为 org.apache.velocity.tools:velocity-tools-generic / velocity-tools-view（Tools 3.1），按需引入。

5.3 模板示例

一段最小 VTL 模板（语言要素均出自官方 VTL Reference）：

## 行注释：#set 赋值
#set($name = "Velocity")
Hello $name!
#if($items)
#foreach($item in $items)
- $item
#end
#end

六、适用场景与限制

6.1 适用场景

• 服务端文本渲染：页面、邮件、报表、公告等以模板驱动的内容。
• 构建期代码生成：以 VTL 为代码模板生成脚手架、接口定义、配置文件。
• 需要长期稳定性的遗留系统：2.x 线 Java 8 基线 + 持续维护（2.5 在推进），升级风险低。
• 已有大量 .vm 模板资产的团队继续沿用与增强。

6.2 已知限制

• VTL 对 HTML 无原生感知，做现代 Web 前端模板时不如 Thymeleaf 等对浏览器友好（对比详见第七章）。
• 引擎只负责"数据 + 模板 → 文本"，Web 场景的绑定、校验等需框架层配合。
• 2.5 尚未发布稳定版，追求绝对保守的团队可继续使用 2.4.1。
• Velocity Tools 的 Web 工具集面向传统 Servlet 视图模型，与现代响应式 Web 框架的整合需要额外胶水层。

七、同类选型对比

7.1 对比对象与数据基准

选取三个同类 Java 模板引擎：Apache FreeMarker、Thymeleaf、Mustache（以其规范仓库为准）。数据于 2026-10-18 取自各项目官方渠道（GitHub 仓库页 stars 数、releases.atom、Maven Central 版本元数据）。

7.2 量化对比

补充说明：FreeMarker 与 Velocity 同属"指令式"模板语言，能力相近、可互换性强；Thymeleaf 主打"自然模板"（模板即合法 HTML，浏览器可直接打开），与 Spring 官方推荐绑定；Mustache 是逻辑无关（logic-less）模板规范，表达力最弱但模板最可移植。

7.3 选型建议

存量 Velocity 资产或代码生成类需求继续用 Velocity 2.4.1 没有问题；新建 Spring MVC/Web 项目优先考虑 Thymeleaf；需要在多个语言栈间共享同一套模板时选 Mustache 系实现；FreeMarker 与 Velocity 二选一时按团队既有经验与 FreeMarker 更活跃的发版节奏权衡。

八、参考链接

• 项目官网：https://velocity.apache.org/
• Engine 开发者指南：https://velocity.apache.org/engine/2.4/developer-guide.html
• VTL 参考手册：https://velocity.apache.org/engine/devel/vtl-reference.html
• GitHub 仓库：https://github.com/apache/velocity-engine
• Maven Central 构件目录：https://repo1.maven.org/maven2/org/apache/velocity/velocity-engine-core/