模板引擎原理与选型

引言

模板引擎解决的是一个古老的问题：把静态骨架和动态数据拼成最终文本。听起来简单，但它处在「表现层」与「逻辑层」的交界，设计取舍极其微妙——给太多逻辑，模板里会写出意大利面；给太少，业务代码里会塞满字符串拼接。

本文从编译原理视角拆解模板引擎：占位符如何被解析成代码、编译型与解释型有何本质差异、四大语法家族各自的哲学、自动转义为何是 XSS 防御的关键、以及渲染性能与沙箱安全的工程考量。最后给一张按场景的选型表。

相关：DSL 设计实战 、Markdown 与文档工程 。语法描述可参考 巴科斯范式 。

1. 模板引擎的核心问题

一个模板引擎要回答四个问题：

这四个维度的取值，几乎决定了一种引擎的全部性格。

2. 编译型 vs 解释型

2.1 解释型：边解析边输出

最简单的实现是「扫描模板 → 遇到文本就输出 → 遇到占位符就求值」。

# 极简解释型模板引擎（仅示意）
import re
def render(tpl, ctx):
    def repl(m):
        return str(ctx.get(m.group(1).strip(), ""))
    return re.sub(r"\{\{\s*(\w+)\s*\}\}", repl, tpl)

print(render("Hello, {{ name }}!", {"name": "World"}))

缺点：每次渲染都要重新解析；复杂的控制流难以表达。

2.2 编译型：模板 → 函数/字节码

Jinja2、Go template、ERB 走的是编译路线：把模板编译成一个 Python/Go/Ruby 函数，之后每次渲染就是调用这个函数。

# Jinja2 会把模板编译成 Python 模块
from jinja2 import Environment
env = Environment()
tpl = env.from_string("Hello, {{ name }}!")
print(tpl.render(name="World"))

# 查看编译产物（生成的 Python 源码）
print(env.compile("{% for x in items %}{{ x }}{% endfor %}", raw=True))

编译型的优势：解析只做一次，渲染快；可以做常量折叠、局部变量提升等优化；错误可在编译期发现（语法、未闭合标签）。

2.3 两阶段流水线

无论哪种，内部通常分三步：

模板文本
  → 词法分析（tokenize）：切出 TEXT / VAR / BLOCK 三类 token
  → 语法分析（parse）：构建 AST（模板节点树）
  → 代码生成（codegen）：输出可执行代码或直接求值

这与编译器的前端流程完全一致，可对照 DSL 设计实战 里的递归下降解析器。

2.4 何时不该用模板引擎

模板引擎不是万能的。以下场景直接拼字符串或用手写生成器更合适：

• 输出结构固定、只有一两个变量：f"Hello {name}" 比引模板更清晰。
• 需要严格的结构正确性（如 SQL、JSON、XML）：应使用构建器 API（json.dumps、SQL 参数化）而非模板，否则易产生注入。
• 高频调用的热路径：预编译的模板函数有时仍不如手写的 strings.Builder 直接。
• 需要复杂类型检查：模板是弱类型的，生成代码时用宿主语言的类型系统更安全。

判断标准很简单：模板的价值在于「静态骨架 + 动态填充」的反复复用。如果骨架只用一次，模板就是多余的抽象层。

3. 四大语法家族

3.1 Mustache / Handlebars：无逻辑（Logic-less）

Mustache 的哲学是「模板里不该有逻辑」，只有变量、区段（section）和反向区段：

Hello {{name}}!
{{#items}}
  - {{.}}
{{/items}}
{{^items}}
  （空列表）
{{/items}}

{{#items}} 既可以是循环（数组）也可以是条件（布尔），由数据类型决定。Handlebars 在其上加了辅助函数（helper）和块辅助。

优点：模板干净，跨语言实现多（40+ 语言）。缺点：复杂逻辑无处安放，容易在 helper 里堆代码。

3.2 Jinja2 / Django / Twig：Python 风格表达力

Jinja2 允许 if、for、过滤器（filter）、宏（macro），表达力接近一门小语言：

{% macro input(name, value='') %}
  <input name="{{ name }}" value="{{ value | escape }}">
{% endmacro %}

<ul>
{% for user in users if user.active %}
  <li>{{ user.name | title }} — {{ user.email }}</li>
{% else %}
  <li>无活跃用户</li>
{% endfor %}
</ul>

PHP 的 Twig、Java 的 Thymeleaf/FreeMarker、Python 的 Jinja2 都属于这一族，语法高度相似（{{ }} 取值、{% %} 语句、| 过滤器）。

3.3 ERB / EJS：嵌入式代码

ERB（Ruby）和 EJS（JS）直接把宿主语言代码嵌进模板：

<ul>
<% @users.each do |user| %>
  <li><%= user.name %></li>
<% end %>
</ul>

<% %> 求值不输出，<%= %> 求值并输出。表达力最强，也最危险——模板里可以写任意代码，逻辑与表现彻底混合。

3.4 Go template：保守而安全

Go 的 text/template 与 html/template 刻意限制表达力，只有 if、range、with 和管道：

{{ range .Items }}
  {{ if .Active }}{{ .Name }}{{ end }}
{{ end }}

{{ .Name | printf "%s (%d)" .Age }}

html/template 会在编译期做上下文感知的自动转义（见第 4 节），是服务端渲染安全的标杆实现。

3.5 语法家族对照

4. 转义与 XSS 防御

4.1 自动转义（autoescape）

模板最常见的漏洞是忘记转义用户输入，导致 XSS：

{# 危险：默认关闭自动转义时 #}
<div>{{ user_bio }}</div>
{# user_bio = "<script>steal()</script>" → 直接执行 #}

现代引擎默认开启自动转义，把 <、>、&、"、' 编码为实体：

<script> → &lt;script&gt;

但自动转义不是万能药。Jinja2 的转义是 HTML 上下文的，若你把数据插进 JavaScript 或 CSS 上下文，转义规则不同：

<script>var name = "{{ user_name }}";</script>
{# user_name = `";alert(1);//` → 逃逸出字符串 #}

正确做法是用 tojson 过滤器做 JS 上下文转义：

<script>var name = {{ user_name | tojson }};</script>

4.2 上下文感知转义

Go 的 html/template 会分析每个插值点所处的上下文（HTML 文本、属性、URL、JS、CSS），应用对应转义。这是它比「统一 HTML 转义」更安全的原因：

// 同一个变量，在 href 里和文本里转义方式不同
<a href="{{ .URL }}">{{ .URL }}</a>

Jinja2 也有 autoescape 的上下文感知扩展，但不如 Go 细粒度。

4.3 何时必须关闭自动转义

当你已经把内容转义好，或内容本身就是可信 HTML（如 Markdown 渲染结果）时，用 | safe / {{{ }}} / template.HTML：

{{ article_html | safe }}   {# 前提：article_html 已由可信渲染器净化 #}

关闭转义是安全决策，必须确认数据来源可信且已净化。永远不要对用户原始输入用 safe。

5. 复用机制

5.1 包含（include）

最简单的复用：把公共片段抽成独立模板。

{% include "header.html" %}

5.2 继承（inheritance）

Jinja2 的块继承是复用设计的典范：父模板定义骨架与可覆盖的块，子模板只填块。

{# base.html #}
<html>
<body>
  {% block content %}{% endblock %}
</body>
</html>

{# page.html #}
{% extends "base.html" %}
{% block content %}
  <h1>{{ title }}</h1>
{% endblock %}

对比 Mustache 的「部分模板 + 反向引用」和 Go template 的 {{ template "name" . }}，Jinja2 的继承模型表达力最强。

5.3 宏与组件

宏（macro）是可参数化的模板片段，接近函数：

{% macro card(title, body) %}
  <div class="card">
    <h3>{{ title }}</h3>
    <p>{{ body }}</p>
  </div>
{% endmacro %}

{{ card("标题", "内容") }}

现代前端框架的「组件」概念，本质就是带作用域与状态的宏。

5.4 复用的取舍

6. 性能与缓存

6.1 编译缓存

编译型引擎的模板应只编译一次并缓存。Jinja2 的 FileSystemLoader 会按文件名缓存编译结果：

from jinja2 import Environment, FileSystemLoader
env = Environment(
    loader=FileSystemLoader("templates"),
    auto_reload=False,        # 生产环境关闭热重载
    cache_size=400,           # 缓存最近 400 个模板
)

生产环境务必 auto_reload=False——否则每次渲染都检查文件修改时间，白白消耗 IO。

6.2 渲染开销

预编译是常见手段：把模板在构建期编译成宿主语言模块，运行时零解析开销。这与 Markdown 与文档工程 里静态站点生成器的「构建期渲染」思路一致。

6.3 沙箱

当模板来自不可信来源（用户自定义主题、CMS 模板），必须用沙箱限制可访问的对象与函数。Jinja2 的 SandboxedEnvironment 会拦截危险的属性访问：

from jinja2.sandbox import SandboxedEnvironment
env = SandboxedEnvironment()

注意：Jinja2 的沙箱并非绝对安全，历史上有过多次沙箱逃逸漏洞（SSTI）。若模板完全来自用户，更好的方案是用 Mustache 这类「无逻辑」引擎，从设计上杜绝代码执行。服务端模板注入（SSTI）是可导致 RCE 的高危漏洞，与 安全 CTF 专题 里的注入类题目同源。

7. 选型决策

7.1 按场景选

7.2 一条设计原则

模板里只放表现逻辑，不放业务逻辑。判断标准：如果一段模板代码需要写测试，它大概率该搬到业务层，模板只接收算好的数据。这条原则能避免模板演变成「无人敢改的第四语言」。

7.3 与前端框架的边界

当页面由前端框架（React/Vue）渲染时，服务端模板通常退化为「只输出初始 HTML 壳和 JSON 数据」。此时选型重点从「表达力」转向「首屏渲染性能」，SSR 场景要关注模板渲染是否阻塞关键路径。相关工程实践可见 PHP 专题 与 Java 专题 。

8. 小结

模板引擎的本质是「受限的代码生成器」：它用占位符与块把数据映射成文本，用自动转义守住安全底线，用继承与宏实现复用。选型的核心变量是表达力需求与数据可信度——数据可信且需要复杂逻辑，选 Jinja2/Twig 一族；数据不可信或逻辑极简，选 Mustache；服务端渲染且追求安全，选 Go 的 html/template。无论选哪种，自动转义默认开启、用户输入永不用 safe、模板不写业务逻辑，这三条都是底线。需要理解模板语法背后的形式语言基础，可回到 巴科斯范式 与 DSL 设计实战 。