3. 模板引擎渲染原理：Jinja2 / Thymeleaf 渲染流程、模板编译、上下文变量传递

在异步导出链路中，模板引擎渲染是 CPU 密集且极易超时的环节。理解 Jinja2（Python 生态）与 Thymeleaf（Java 生态）的底层渲染流程，是定位“渲染慢、超时、上下文丢失”等故障的前提。本节从模板编译、上下文变量传递、渲染流水线三个维度拆解其核心机制。

3.1 模板引擎渲染全流程

无论是 Jinja2 还是 Thymeleaf，其渲染过程均可抽象为三个阶段：加载与编译 → 上下文绑定 → 渲染输出。差异主要体现在编译策略和变量解析方式上。

3.2 模板编译：从文本到可执行结构

模板编译是渲染性能的基石。Jinja2 和 Thymeleaf 采用截然不同的编译策略，直接影响首次加载速度和运行时效率。

3.3 Jinja2 渲染流程详解

Jinja2 的渲染流程可拆解为以下步骤：

1. 词法分析： 将模板字符串拆分为 token 流（文本块、变量 {{ }}、语句 {% %}、注释 {# #}）。
2. 语法分析： 将 token 流构建为抽象语法树（AST），包含 Node 对象（如 Output、If、For）。
3. 字节码生成： 将 AST 编译为 Python 字节码，生成 Template 对象的 render() 方法。
4. 上下文注入： 将传入的字典变量绑定到模板作用域链中。
5. 执行渲染： 逐条执行字节码指令，拼接字符串输出。

# Jinja2 编译与渲染示例
from jinja2 import Environment, FileSystemLoader

env = Environment(loader=FileSystemLoader('templates/'))
template = env.get_template('report.html')  # 编译阶段（若缓存则跳过）
output = template.render(                    # 渲染阶段
    title="异步导出报告",
    rows=[{"id": 1, "name": "数据A"}, {"id": 2, "name": "数据B"}]
)

3.4 Thymeleaf 渲染流程详解

Thymeleaf 基于 XML DOM 操作，渲染流程与 Jinja2 有本质区别：

1. 模板解析： 使用 SAX 或 DOM 解析器将模板文件解析为 Document 对象（DOM 树）。
2. 标准方言处理： 遍历 DOM 树，识别 th:* 属性（如 th:text、th:each），构建表达式树。
3. 表达式缓存： 将解析后的表达式（OGNL / SpringEL）缓存到 CacheManager。
4. 上下文绑定： 将 IContext 对象（包含变量映射）绑定到 VariableMapper。
5. 渲染输出： 遍历 DOM 树，执行表达式求值，替换节点内容，最终序列化为 HTML 字符串。

<!-- Thymeleaf 模板示例 -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title th:text="${title}">默认标题</title>
</head>
<body>
    <table>
        <tr th:each="row : ${rows}">
            <td th:text="${row.id}">1</td>
            <td th:text="${row.name}">名称</td>
        </tr>
    </table>
</body>
</html>

3.5 上下文变量传递机制

上下文变量传递是渲染超时的“重灾区”。理解作用域链和变量查找路径，才能精准优化。

3.6 渲染超时排查清单

基于上述原理，当异步导出链路出现模板渲染超时时，按以下清单逐项排查：