模板引擎封装 - TemplateUtil

---

1. 介绍

在前后端分离的背景下，JSP技术和传统模板引擎的使用逐渐减少，但在邮件模板、页面静态化等场景下依然有着不可替代的作用。然而，不同模板引擎的语法和使用方式各不相同，学习成本较高。为此，Hutool 对常见模板引擎进行了统一封装，使开发者能够轻松切换引擎，无需改变业务代码。

Hutool 当前支持以下模板引擎：

• Beetl (opens new window)
• Enjoy (opens new window)
• Rythm (opens new window)
• FreeMarker (opens new window)
• Velocity (opens new window)
• Thymeleaf (opens new window)

2. 使用原理

Hutool 的模板引擎封装借鉴了 Java 日志门面的设计思想，将模板渲染抽象为以下两个核心接口：

• TemplateEngine：模板引擎，用于配置模板加载方式、编码等参数，并获取模板对象。
• Template：模板对象，用于渲染模板内容并生成最终结果。

通过这两个接口，开发者可以无缝切换不同模板引擎，而无需修改代码逻辑。Hutool 会通过 TemplateFactory 自动检测项目中引入的模板引擎，并选择相应的实现进行渲染。

---

3. 使用示例

3.1. 从字符串模板渲染内容

在以下示例中，无论使用何种模板引擎，代码逻辑均保持不变，只需调整模板内容：

import cn.hutool.core.lang.Dict;
import cn.hutool.extra.template.TemplateConfig;
import cn.hutool.extra.template.TemplateEngine;
import cn.hutool.extra.template.TemplateUtil;
import cn.hutool.extra.template.Template;

public class TemplateExample {
    public static void main(String[] args) {
        // 自动根据用户引入的模板引擎库的 jar 自动选择使用的引擎
        TemplateConfig config = new TemplateConfig();
        TemplateEngine engine = TemplateUtil.createEngine(config);

        // 使用字符串模板（假设引入的是 Beetl 引擎）
        Template template = engine.getTemplate("Hello ${name}");
        
        // 构建参数，Dict 本质上为 Map
        Dict params = Dict.create().set("name", "Hutool");
        
        // 渲染模板并输出结果
        String result = template.render(params);
        System.out.println(result); // 输出：Hello Hutool
    }
}

API解析：

• TemplateEngine.createEngine(TemplateConfig config)：创建模板引擎，配置模板加载方式、编码等参数。
• Template.getTemplate(String templateContent)：获取模板对象。
• Template.render(Map<String, Object> params)：渲染模板，返回渲染后的结果字符串。

实际开发场景：

• 用于生成动态内容，如邮件模板、报告生成等。

---

3.2. 从 ClassPath 查找模板渲染

通过设置 TemplateConfig，可以轻松实现从 ClassPath 加载模板文件并渲染内容。以下示例以 Velocity 为例：

import cn.hutool.core.lang.Dict;
import cn.hutool.extra.template.TemplateConfig;
import cn.hutool.extra.template.TemplateEngine;
import cn.hutool.extra.template.TemplateUtil;
import cn.hutool.extra.template.Template;
import cn.hutool.extra.template.ResourceMode;

public class ClassPathTemplateExample {
    public static void main(String[] args) {
        // 配置从 ClassPath 加载模板文件
        TemplateConfig config = new TemplateConfig("templates", ResourceMode.CLASSPATH);
        TemplateEngine engine = TemplateUtil.createEngine(config);

        // 加载 ClassPath 下的模板文件 velocity_test.vtl
        Template template = engine.getTemplate("velocity_test.vtl");
        
        // 构建参数
        Dict params = Dict.create().set("name", "Hutool");
        
        // 渲染模板并输出结果
        String result = template.render(params);
        System.out.println(result); // 输出渲染结果
    }
}

API解析：

• TemplateConfig(String path, ResourceMode mode)：配置模板加载路径和方式。
• ResourceMode.CLASSPATH：表示从 ClassPath 中加载模板。

实际开发场景：

• 适用于将模板文件保存在项目资源路径下，并在运行时加载和渲染。

---

3.3. 其它方式查找模板

模板加载方式由 ResourceMode 枚举定义，支持以下几种模式：

• CLASSPATH：从 ClassPath 加载模板。
• FILE：从本地文件系统加载模板。
• WEB_ROOT：从 Web 根目录加载模板。
• STRING：直接从字符串模板加载。
• COMPOSITE：复合加载模式，依次尝试从 File、ClassPath、WebRoot 和字符串方式加载模板。

例如，从本地文件系统加载模板：

import cn.hutool.core.lang.Dict;
import cn.hutool.extra.template.TemplateConfig;
import cn.hutool.extra.template.TemplateEngine;
import cn.hutool.extra.template.TemplateUtil;
import cn.hutool.extra.template.Template;
import cn.hutool.extra.template.ResourceMode;

public class FileTemplateExample {
    public static void main(String[] args) {
        // 配置从本地文件系统加载模板
        TemplateConfig config = new TemplateConfig("/path/to/templates", ResourceMode.FILE);
        TemplateEngine engine = TemplateUtil.createEngine(config);

        // 加载文件系统中的模板文件 template.vtl
        Template template = engine.getTemplate("template.vtl");
        
        // 构建参数
        Dict params = Dict.create().set("name", "Hutool");
        
        // 渲染模板并输出结果
        String result = template.render(params);
        System.out.println(result); // 输出渲染结果
    }
}

实际开发场景：

• 适用于模板文件保存在指定路径或用户自定义目录下的场景。

---

4. 总结

TemplateUtil 通过封装多种模板引擎，为开发者提供了统一的接口，简化了不同模板引擎之间的切换。在实际项目中，无论是渲染字符串模板，还是加载外部模板文件，都可以通过 TemplateUtil 提供的 API 轻松实现。根据项目需求，开发者可以自由选择和切换模板引擎，而无需修改业务逻辑。