4. 渲染超时根因分析（一）：模板语法错误与死循环、递归渲染导致栈溢出

模板引擎渲染超时并非总是由数据量过大或外部 I/O 阻塞引起。在异步导出链路中，模板语法错误、死循环以及递归渲染导致栈溢出是三类极易被忽视但破坏力极强的根因。它们通常不会触发业务异常日志，而是表现为渲染线程“卡死”或 JVM 进程直接崩溃。

4.1 模板语法错误：静默的渲染中断

模板引擎在解析阶段遇到非法语法时，行为因引擎实现而异。部分引擎（如 FreeMarker）会抛出异常并中断渲染；而另一些引擎（如 Thymeleaf 或某些旧版 Velocity）可能进入“容错模式”，尝试跳过错误节点，导致渲染循环无法正常结束。

4.2 死循环：数据层与模板层的耦合陷阱

死循环是渲染超时最常见的根因之一。它通常不是模板引擎本身的缺陷，而是模板中嵌入了对循环变量进行修改的逻辑，导致循环终止条件永远无法满足。

<!-- 危险示例：在循环体内修改集合 -->
<#list items as item>
  <#if item.status == "PENDING">
    <#-- 某些模板引擎允许在循环中操作集合 -->
    <#assign items = items + [item] />
  </#if>
  ${item.name}
</#list>

上述代码中，每次遇到 PENDING 状态的元素，都会向 items 集合追加一个新元素，导致列表无限增长，渲染线程永远无法退出 <#list> 指令。

死循环的三种常见模式

1. 集合自增模式：在循环体内通过 assign 或 put 向正在迭代的集合添加元素。
2. 嵌套循环变量覆盖：外层循环变量与内层循环变量同名，导致内层循环修改了外层循环的计数器。
3. 条件永不满足的跳出：<#break> 被包裹在永远为 false 的条件判断中。

4.3 递归渲染导致栈溢出

递归渲染通常出现在树形结构（如组织架构、分类目录、评论回复）的模板输出中。当递归深度超过 JVM 线程栈的默认大小（通常为 1024 KB），就会抛出 StackOverflowError，导致渲染线程直接终止。

<!-- 递归渲染树形菜单 -->
<#macro renderNode node>
  <li>${node.name}
    <#if node.children?? && node.children?size > 0>
      <ul>
        <#list node.children as child>
          <@renderNode node=child />
        </#list>
      </ul>
    </#if>
  </li>
</#macro>

上述代码在数据中存在循环引用（如 A 的子节点包含 A 自身）或深度超过 2000 层时，会迅速耗尽线程栈空间。

4.4 根因对比与快速定位表

4.5 架构层面的防御措施

• 模板沙箱执行：将模板渲染放入独立的线程池，设置超时时间（如 30 秒），超时后强制中断并回收线程。
• 递归深度硬限制：在模板上下文注入 maxDepth 变量，递归宏每进入一层检查深度，超过阈值直接返回空字符串。
• 预编译与语法校验：在模板上传或部署阶段，使用引擎提供的 Template.compile() 进行预编译，提前发现语法错误。
• 循环引用检测：在数据准备层，对树形结构进行拓扑排序或使用 Set<String> 记录已访问节点 ID，发现重复立即抛出异常。