3. 模板引擎核心概念：模板与数据分离、变量插值、控制结构（if/for）、过滤器与自定义函数

模板引擎的核心价值在于将展示逻辑与业务数据解耦。在报表导出模块与 gRPC 接口契约集成的场景中，理解这些核心概念是构建可维护、高性能模板系统的前提。本节将逐一剖析模板引擎的五大基石，并结合报表导出的实际案例进行说明。

3.1 模板与数据分离

这是模板引擎最根本的设计思想。模板文件只包含占位符和控制逻辑，而所有可变数据由后端程序（如 Go、Java、Python 服务）在渲染时注入。这种分离带来了以下好处：

• 职责清晰：前端/模板设计师专注于布局与样式，后端工程师专注于数据获取与业务逻辑。
• 可维护性：修改报表样式无需改动后端代码，反之亦然。
• 安全性：模板无法直接访问数据库或内部 API，只能操作传入的上下文数据。

在 gRPC 接口契约中，模板通常作为静态资源或配置项存储在服务端。当 gRPC 客户端请求报表时，服务端从 Protobuf 消息中提取数据，填充到指定模板中。

3.2 变量插值

变量插值是将数据注入模板的最基本操作。模板引擎通过特定的语法标记（如 {{ }}）识别占位符，并将其替换为实际数据。在 Go 的 text/template 和 html/template 中，点号 . 代表当前上下文。

// 模板文件：report.tmpl
<h1>销售报表：{{ .Title }}</h1>
<p>生成时间：{{ .GeneratedAt }}</p>
<p>总销售额：{{ .TotalAmount }} 元</p>

// 后端数据注入（Go 示例）
data := ReportData{
    Title:         "2024 年度销售汇总",
    GeneratedAt:   "2024-12-31 23:59:59",
    TotalAmount:   1250000.50,
}
err := tmpl.Execute(w, data)

在报表导出场景中，变量插值常用于填充标题、日期、汇总金额等单值字段。对于嵌套结构，可以使用点号链式访问，例如 {{ .User.Name }}。

3.3 控制结构（if/for）

控制结构使模板具备基本的逻辑判断和循环能力，从而处理动态列表和条件展示。这是报表模板中最常用的功能之一。

3.3.1 条件判断（if/else）

用于根据数据状态决定是否渲染某段内容。例如，当报表没有数据时显示提示信息：

{{ if .Items }}
<table>
  <tr><th>产品</th><th>销量</th></tr>
  {{ range .Items }}
  <tr><td>{{ .Name }}</td><td>{{ .Quantity }}</td></tr>
  {{ end }}
</table>
{{ else }}
<p class="warning">当前时间段内无销售数据。</p>
{{ end }}

3.3.2 循环遍历（range/for）

用于遍历数组、切片或 Map，生成重复的表格行或列表项。在 Go 模板中，range 会重置上下文 . 为当前迭代元素。

// 模板片段：遍历订单列表
<h2>订单明细</h2>
<ul>
{{ range .Orders }}
  <li>订单号：{{ .OrderID }} - 金额：{{ .Amount }} 元</li>
{{ end }}
</ul>

在报表导出模块中，for 循环常用于生成多行数据表格、图表数据点序列或分页内容。

3.4 过滤器

过滤器（Filter）用于在模板中对变量进行格式化或变换，而不需要在后端代码中预处理。不同模板引擎的过滤器语法略有差异，但核心思想一致。

在报表导出中，过滤器常用于：

• 数字格式化：保留两位小数、千分位分隔符。
• 日期格式化：将时间戳转为 YYYY-MM-DD 格式。
• 字符串处理：转义 HTML、截断长文本、大小写转换。
• 默认值：当变量为空时显示替代文本。

// Go 模板过滤器示例
// 后端注册自定义过滤器
func ToUpper(s string) string {
    return strings.ToUpper(s)
}
func AddSuffix(s, suffix string) string {
    return s + suffix
}
tmpl = tmpl.Funcs(template.FuncMap{
    "toUpper":   ToUpper,
    "addSuffix": AddSuffix,
})

// 模板中使用
{{ .ProductName | toUpper }}
{{ .OrderID | addSuffix "-CN" }}

3.5 自定义函数

当内置过滤器和控制结构无法满足复杂业务需求时，模板引擎允许开发者注册自定义函数。这些函数可以接受参数、执行复杂逻辑并返回值，极大地扩展了模板的表达能力。

在报表导出与 gRPC 集成的场景中，自定义函数的典型用途包括：

• 数据转换：将 Protobuf 枚举值转为中文描述。
• 计算聚合：在模板内计算小计、百分比、增长率。
• 条件格式化：根据数值大小返回不同的 CSS 类名或颜色。
• 国际化：根据语言代码返回对应的翻译文本。

// 自定义函数示例：将枚举值转为中文状态
func StatusText(status int32) string {
    switch status {
    case 0:
        return "待处理"
    case 1:
        return "进行中"
    case 2:
        return "已完成"
    default:
        return "未知"
    }
}

// 注册到模板
tmpl.Funcs(template.FuncMap{
    "statusText": StatusText,
})

// 模板中使用
<td>{{ .OrderStatus | statusText }}</td>

3.6 综合案例：报表模板实战

以下是一个综合运用上述概念的报表模板片段，展示了在 gRPC 报表导出场景中的典型用法：

<!DOCTYPE html>
<html>
<head><title>{{ .ReportTitle | html }}</title></head>
<body>
  <h1>{{ .ReportTitle }}</h1>
  <p>导出时间：{{ .ExportTime | dateFormat "2006-01-02 15:04:05" }}</p>

  <h2>销售汇总</h2>
  <table border="1">
    <tr>
      <th>区域</th>
      <th>销售额</th>
      <th>占比</th>
    </tr>
    {{ range .Regions }}
    <tr>
      <td>{{ .Name }}</td>
      <td>{{ .Amount | printf "%.2f" }} 元</td>
      <td>{{ .Amount | percentage $.TotalAmount }}%</td>
    </tr>
    {{ else }}
    <tr><td colspan="3">暂无数据</td></tr>
    {{ end }}
  </table>

  <h2>订单明细</h2>
  {{ if .Orders }}
  <ul>
    {{ range .Orders }}
    <li>
      <strong>{{ .OrderID }}</strong> -
      {{ .Status | statusText }} -
      {{ .Total | addTax .TaxRate | printf "%.2f" }} 元
    </li>
    {{ end }}
  </ul>
  {{ else }}
  <p class="empty">无订单记录。</p>
  {{ end }}
</body>
</html>

该模板中：

• 变量插值：{{ .ReportTitle }}、{{ .ExportTime }}
• 控制结构：{{ range .Regions }}、{{ if .Orders }}
• 过滤器：| html、| printf "%.2f"
• 自定义函数：| dateFormat、| percentage、| statusText、| addTax