3. 模板引擎基础
模板引擎是报表导出系统的核心翻译层。它负责将静态模板与动态数据合并，生成最终的输出内容（HTML、PDF、CSV 等）。理解其工作原理、选型差异和渲染生命周期，是后续进行渲染性能优化与 Redis 热点治理的前提。
3.1 工作原理：数据 + 模板 = 输出
模板引擎的核心公式可以概括为：Template + Data = Output。引擎将模板文件解析为抽象语法树（AST），然后在数据上下文中执行 AST 中的指令（变量替换、循环、条件判断），最终生成字符串输出。
核心流程：
- 加载：从文件系统、缓存或字符串中读取模板内容。
- 解析：将模板文本解析为结构化的 AST（抽象语法树）。
- 编译：将 AST 编译为可执行的 Java 类或字节码（如 Freemarker/Thymeleaf），或直接生成渲染函数（如 Jinja2）。
- 渲染：传入数据模型（Map/POJO），执行编译后的代码，输出最终文本。
3.2 常见模板引擎对比
在 Java 报表生态中，Freemarker、Thymeleaf 和 Jinja2（Python 生态，但常作为对比基准）是三种代表性引擎。下表从报表导出场景的关键维度进行对比：
| 维度 | Freemarker | Thymeleaf | Jinja2 (Python) |
|---|---|---|---|
| 语法风格 | ${variable} / <#list> |
th:text="${variable}" (自然模板) |
{{ variable }} / {% for %} |
| 编译方式 | 编译为 Java 类，高性能 | 编译为 Java 类，支持表达式缓存 | 编译为 Python 字节码 |
| 报表适用性 | ★★★★★ 纯文本/HTML/XML 输出，无侵入 | ★★★☆☆ 强绑定 HTML，非 Web 场景冗余 | ★★★★☆ 灵活，但非 JVM 原生 |
| 宏/函数支持 | 强大（macro, function, assign） | 一般（fragment, dialect） | 强大（macro, filter, test） |
| 缓存机制 | 内置模板缓存（强） | 内置模板缓存（中） | 需手动实现（如 Flask-Caching） |
| 空值处理 | ! 操作符 / default() |
?: 表达式 |
default() filter |
选型建议： 对于纯后端报表导出（非 Web 页面渲染），Freemarker 通常是 Java 技术栈的最佳选择——编译性能高、模板语法对非 HTML 输出友好、缓存机制成熟。Thymeleaf 更适合需要前端原型设计的 Web 场景。
3.3 渲染生命周期
一次完整的模板渲染请求，从接收到输出，经历以下 5 个阶段。每个阶段都可能成为性能瓶颈，也是后续优化（如 Redis 缓存、预编译、懒加载）的切入点。
3.4 关键概念：模板缓存与热点
在报表导出场景中，模板缓存是避免重复解析/编译的核心手段。但缓存本身也可能成为 Redis 热点——当大量并发请求同时访问同一个模板缓存键时，单节点 Redis 可能因 QPS 过高而出现延迟抖动甚至雪崩。
注意： 模板引擎的“编译缓存”通常存储在本地内存（如 ConcurrentHashMap），而“模板内容缓存”可能存储在 Redis。两者需要区分对待：本地缓存速度快但无法跨进程共享，Redis 缓存可共享但存在热点风险。后续章节将详细讲解如何通过 本地+远程多级缓存 和 Key 分片 解决这一矛盾。
3.5 代码示例：Freemarker 渲染核心流程
以下代码展示了 Freemarker 从模板加载到渲染输出的最小化实现，注意 Template 对象的缓存复用：
// 1. 配置 Freemarker（应用启动时执行一次）
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
cfg.setDirectoryForTemplateLoading(new File("/templates"));
cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
cfg.setCacheStorage(new MruCacheStorage(20, 250)); // 本地缓存
// 2. 获取模板（优先从缓存返回）
Template template = cfg.getTemplate("report.ftl");
// 3. 准备数据模型
Map<String, Object> dataModel = new HashMap<>();
dataModel.put("title", "月度销售报表");
dataModel.put("rows", queryDataFromDB()); // 数据查询
// 4. 渲染输出
StringWriter out = new StringWriter();
template.process(dataModel, out);
String result = out.toString();
优化点：
cfg.getTemplate() 内部会先检查本地缓存，若未命中则加载并编译。在高并发报表导出中，建议将 Template 对象本身也放入 Redis 二级缓存（序列化后），以加速多节点间的模板共享。