Apache Anakia 1.0 介绍与选型指南

目标：讲清 Apache Anakia 1.0 是什么——它如何用 JDOM + Velocity 模板把 XML 文档转换成任意格式、作为 Ant 任务如何配置、适合哪些场景，并给出与 XSLT（Apache Xalan）、Pandoc、Asciidoctor 等相近文档转换方案的选型对比。本文为认知篇，全部内容基于官方文档与项目发布数据联网查证（查询日期 2026-10-18），不做本地安装实测。

一、信息基准

• 查询日期：2026-10-18（Asia/Shanghai）。文中版本号、能力描述均于该日期联网核实并随文标注来源。
• 版本依据：本文介绍的版本为 Anakia 1.0。Apache Velocity 官网的 Anakia 页面将其归入「Archive」栏目，明确列出「Archive: Anakia 1.0」与「Anakia 1.0 Documentation」（来源：https://velocity.apache.org/anakia/ 左侧导航，查询日期 2026-10-18）。Anakia 1.0 也是 Maven Central 上的正式发布坐标：org.apache.anakia:anakia:1.0 与历史坐标 velocity-anakia:anakia:1.0（来源：search.maven.org 检索 anakia 结果，查询日期 2026-10-18）。1.0 之后官方未再发布独立新版本。
• 官方来源清单：
  • Anakia 门户页（Archive 区）：https://velocity.apache.org/anakia/
  • Anakia 1.0 文档（What Is Anakia / How Does It Work / 任务属性表）：https://velocity.apache.org/anakia/1.0/
  • Apache Velocity 项目主页与发布数据：https://velocity.apache.org/ 、https://projects.apache.org/json/projects/velocity.json
  • Maven Central 检索：https://search.maven.org/
• 上下文版本：Anakia 所属的 Apache Velocity 项目当前引擎版本为 Velocity Engine 2.4.1（2024-10-14 发布，来源：https://projects.apache.org/json/projects/velocity.json 与 velocity.apache.org 首页 Releases 栏目，查询日期 2026-10-18）。

二、软件概述

2.1 版本与定位

Anakia 1.0 是 Apache Velocity 项目旗下「Archive」区的 XML 转换工具当前唯一发布版本（来源：https://velocity.apache.org/anakia/ ，查询日期 2026-10-18）。官方定义：「Anakia is an XML transformation tool which uses JDOM and Velocity to transform XML documents into the format of your choice」——即用 JDOM 解析 XML、用 Velocity 模板渲染输出格式的转换工具，是「Ant 的 <style> 任务 + XSL」之外处理 XML 文件的另一种选择（来源：https://velocity.apache.org/anakia/1.0/ 「What Is Anakia?」，查询日期 2026-10-18）。

它最初的目标是取代 Stylebook，用于生成所有页面共享统一观感的简单静态站点——官方明确说它「great for documentation/project web sites」，Apache 与 Jakarta 的历史站点文档就是用它生成的；本文档所属的 Velocity 官网本身也曾用 Anakia 生成（官网原文：「Anakia is being used to create the documentation for this website」，来源：https://velocity.apache.org/anakia/1.0/ ，查询日期 2026-10-18）。

一句话概括：Anakia 是一个 Ant 任务 <anakia>，批量读取目录下的 .xml 文件，把每个文件的 JDOM 文档对象灌进 Velocity 模板（.vsl），渲染出 HTML 等目标格式——「模板语言写样式，JDOM 导航数据」取代 XSLT 的标签式转换。

2.2 许可与维护方

• 许可证：Apache License 2.0（来源：https://velocity.apache.org/anakia/ 页脚「Licensed under the Apache License, Version 2.0」，查询日期 2026-10-18）。
• 维护方：Apache Software Foundation Velocity 项目。需要注意的是，Anakia 目前位于官网 Archive（存档）区，与 Texen、DVSL、DocBook Fx 并列，官方不再将其作为活跃子项目演进（来源：velocity.apache.org 首页导航，查询日期 2026-10-18）。
• 形态：不是独立进程或 CLI，而是随 Velocity 分发的 Ant 任务库（org.apache.anakia.AnakiaTask），在构建文件中通过 <taskdef> 声明后使用。

2.3 版本说明

• Anakia 1.0 为唯一发布版本：官方 Archive 栏目仅列出 Anakia 1.0；Maven Central 坐标 org.apache.anakia:anakia:1.0 无后续版本（来源：velocity.apache.org 与 search.maven.org，查询日期 2026-10-18）。
• 项目历史悠久：文档中的性能对比背景是「PIII 500MHz + JDK 1.3」时代，属 Jakarta Velocity 时期的产物（来源：https://velocity.apache.org/anakia/1.0/ 原文，查询日期 2026-10-18）。

三、核心概念与工作方式

本章内容均引自官方 Anakia 1.0 文档（来源：https://velocity.apache.org/anakia/1.0/ ，查询日期 2026-10-18）。

3.1 三步工作模型

官方把 AnakiaTask 的基本模型概括为三步：

1. 解析：用 JDOM 的 SAXBuilder 把 XML 解析成 JDOM Document（文档示例中指定 org.apache.xerces.parsers.SAXParser 作为解析器实现）；
2. 注入上下文：把 Document（或根 Element）放入 Velocity Context，键名为 root；
3. 渲染：用 Velocity 执行 .vsl 模板；模板内通过 JDOM 的方法遍历 XML 文档取数。

3.2 Context 中的对象

• root：当前被转换 XML 页面的 JDOM Document 对象；
• project（可选）：来自 projectFile 属性指定的「导航」XML 文件的 JDOM Document，用于渲染侧边导航等站点级结构（对应 Stylebook/Struts 站点生成的用法）；
• 官方文档还说明：除 project.xml 导航文档外，可通过 context 嵌套元素向 Context 追加更多自定义 XML 上下文（来源：https://velocity.apache.org/anakia/1.0/ ，查询日期 2026-10-18）。

3.3 与 XSLT 的关系

官方文档对两者的定位表述：Anakia 潜在上比 XSL 更容易学习——不必记忆晦涩的 <xsl:> 标签，只需掌握 Context 对象、JDOM 与 Velocity 的简单指令；同时功能上与 XSL「相似但更聚焦」，因定位更专一而放弃了 XSL 的部分「额外」能力。文档还记录了当时（Jakarta 时期）的生成性能对比：同机同 JDK 下 Anakia 生成 23 页耗时 7-8 秒，Ant <style> 任务走 Xalan 约 14-15 秒，约 2 倍差距（来源：https://velocity.apache.org/anakia/1.0/ ，查询日期 2026-10-18；该数据为历史基准，不代表现代硬件表现）。

四、功能特性

• 批量目录转换：<anakia> 任务按 includes/excludes 扫描 basedir 下的 XML 文件集，逐个渲染到 destdir（来源：官方任务属性表，查询日期 2026-10-18）。
• 模板即样式：输出格式完全由 .vsl Velocity 模板决定，模板作者用 VTL + JDOM API 编排页面结构。
• 站点导航支持：projectFile 提供站点级导航 XML，模板中可引用以渲染统一的菜单/目录结构。
• 增量构建：lastModifiedCheck 属性控制是否跳过未修改文件，避免全量重渲染。
• 可扩展上下文：context 嵌套元素可向模板追加自定义 XML 数据源（来源：官方文档，查询日期 2026-10-18）。
• 与 Ant 无缝集成：作为标准 Ant 任务，可与其他构建目标（拷贝图片资源、打包站点等）串联编排。
• Velocity 模板可复用：.vsl 模板语言与 Velocity 引擎生态一致，模板技能可迁移（Velocity Engine 当前版本 2.4.1，来源：projects.apache.org，查询日期 2026-10-18）。

五、快速上手

以下构建文件逐字引自官方 Anakia 1.0 文档「How Does It Work?」一节（来源：https://velocity.apache.org/anakia/1.0/ ，查询日期 2026-10-18）。它演示了「xdocs 目录的 XML 源 → site.vsl 模板 → docs 目录的 HTML」这一经典站点生成流：

<project name="build-site" default="docs" basedir=".">
  <property name="docs.src" value="../xdocs"/>
  <property name="docs.dest" value="../docs"/>
  <target name="prepare">
    <available classname="org.apache.anakia.AnakiaTask"
        property="AnakiaTask.present"/>
  </target>
  <target depends="prepare" name="prepare-error"
                          unless="AnakiaTask.present">
    <echo>
      AnakiaTask is not present! Please check to make sure that
      velocity.jar is in your classpath.
    </echo>
  </target>
  <target name="docs" depends="prepare-error"
                        if="AnakiaTask.present">
    <taskdef name="anakia"
             classname="org.apache.anakia.AnakiaTask"/>
    <anakia basedir="${docs.src}" destdir="${docs.dest}/"
         extension=".html" style="./site.vsl"
         projectFile="./stylesheets/project.xml"
         excludes="**/stylesheets/**"
         includes="**/*.xml"
         lastModifiedCheck="false"
         velocityPropertiesFile="velocity.properties">
    </anakia>
    <copy todir="${docs.dest}/images" filtering="no">
      <fileset dir="${docs.src}/images">
        <include name="**/*.gif"/>
        <include name="**/*.jpeg"/>
        <include name="**/*.jpg"/>
      </fileset>
    </copy>
  </target>
</project>

官方给出的 <anakia> 任务属性表（摘译，来源同上，查询日期 2026-10-18）：

官方的使用路径说明（来源同上）：构建好 Velocity 后，进入 Velocity 发行包的 examples/anakia/build 目录直接运行 ant，生成的 HTML 输出到 examples/anakia/docs/；XML 源码在 examples/anakia/xdocs/，模板在 xdocs/stylesheets/ 下的 .vsl 文件中——理解模板需要 Velocity 模板语言（VTL）与 JDOM 两方面知识。Maven 使用者可通过坐标 org.apache.anakia:anakia:1.0 引用（来源：search.maven.org 检索结果，查询日期 2026-10-18）。

六、适用场景与限制

6.1 适用场景

• 遗留站点/文档工程维护：历史上大量 Apache、Jakarta 项目站点由 Anakia 生成（来源：官网「great for documentation/project web sites」表述，查询日期 2026-10-18），存量 xdocs + .vsl 工程需要继续构建时仍是原配工具。
• 已有 Velocity 技术栈的团队：模板技能与引擎配置可直接复用，不想为文档转换引入 XSLT 或新工具链。
• 结构稳定、格式统一的文档站：页面结构统一、只需换肤式渲染的场景正是其设计目标。

6.2 限制与注意事项

• 处于存档状态：官方已将 Anakia 归入 Archive 区，1.0 之后无独立发版（来源：velocity.apache.org 首页 Archive 栏目，查询日期 2026-10-18），新项目选型需谨慎评估长期维护风险。
• 依赖链老：典型用法绑定期 Jakartax 时代的 Velocity 1.x 类路径与 JDOM 1.x；与现代 Velocity Engine 2.4.1（2024-10-14，来源：projects.apache.org，查询日期 2026-10-18）搭配时需自行验证兼容性。
• 不是通用 XML 工具链：无 XSLT 的完整能力（如复杂的模式匹配、多输出、XPath 2.0+ 特性），官方自述「does not provide some of XSL's extra functionality」（来源：anakia/1.0 文档，查询日期 2026-10-18）。
• 必须以 Ant 为宿主：没有独立 CLI，脱离 Ant 构建体系使用价值有限。
• 模板调试体验一般：VTL + JDOM 组合的出错信息与调试手段不如现代静态站点生成器。

七、同类选型对比

对比对象：Apache Xalan-J（XSLT 处理器，Anakia 的官方「对照组」）、Pandoc（通用文档格式转换器）、Asciidoctor（AsciiDoc 文本标记 → HTML/PDF 的现代文档工具链）。数据来源：projects.apache.org、GitHub 仓库页与 Releases（github.com，均于 2026-10-18 查询）；Xalan-J 的 GitHub 仓库为上游代码的同步副本（其活跃度不代表上游开发状态）。

选型建议一句话：维护存量 Anakia 站点工程时继续用它（并优先验证与现有 Velocity/JDOM 版本的兼容性）；新文档站或新转换需求选 Asciidoctor（结构化写作）或 Pandoc（格式搬运），需要真正 XSLT 语义时用 XSLT 处理器（Java 侧 Xalan-J 或 C 侧 libxslt），不建议在 Anakia 上启动新工程。

八、参考链接

1. Anakia 门户页（Archive 区与定位说明）：https://velocity.apache.org/anakia/
2. Anakia 1.0 官方文档（三步模型、示例构建文件、属性表来源）：https://velocity.apache.org/anakia/1.0/
3. Apache Velocity 项目主页：https://velocity.apache.org/
4. Apache Velocity 项目发布数据（Engine 2.4.1）：https://projects.apache.org/json/projects/velocity.json
5. Maven Central 检索（anakia 坐标）：https://search.maven.org/
6. Velocity Engine 文档（模板语言参考）：https://velocity.apache.org/engine/2.4.1/