第 46 课 - 模板引擎

学习目标

通过本课的学习，你将能够：

理解什么是模板引擎及其在 Web 开发中的作用。
掌握使用 Go 标准库 html/template 和 text/template 创建并渲染模板。
学会在模板中安全地插入数据，并使用条件判断、循环等控制结构。
了解模板继承、函数映射等高级用法，以构建可维护的网页结构。

核心概念

想象一下，你想为每位用户生成一个个性化的欢迎页面。如果你手动拼接 HTML 字符串，不仅代码会变得混乱不堪，而且极易出错，尤其是在涉及动态数据（如用户名、文章内容）时。模板引擎就像一个“数据填充器”，它解决了这个问题。

模板 (Template) 是一个包含静态文本和“占位符”的文件。这些占位符定义了动态数据应该出现的位置和显示方式。 数据 (Data) 是你希望填入模板的变量、对象或结构体。 渲染 (Rendering) 是模板引擎将数据填入模板的占位符中，生成最终可呈现文本（通常是 HTML）的过程。

Go 标准库提供了两个核心的模板包：

html/template：专门用于生成 HTML。它最重要的特性是上下文感知的自动转义。例如，当在 HTML 标签内插入包含 <script> 的字符串时，它会自动将其转义为安全的 <script>，从而有效防止跨站脚本攻击 (XSS)。这是 Web 开发中必须使用的包。
text/template：用于生成纯文本、邮件内容、配置文件等任何非 HTML 的文本。它不进行任何转义。

模板语法核心：

{{.}}：表示根数据对象。点 . 代表“当前作用域中的数据”。
{{.FieldName}}：访问数据对象的字段。
{{range .Items}} ... {{end}}：遍历切片或数组。
{{if .Condition}} ... {{else}} ... {{end}}：条件判断。
{{template “name” .}}：嵌入另一个命名的子模板。
{{/* 注释 */}}：模板中的注释，不会出现在输出中。

代码示例

示例 1：基础模板渲染

以下程序展示了一个最简单的模板定义、解析、渲染流程。

package main

import (
	"html/template"
	"os"
)

// 定义一个用于传递给模板的数据结构
type Person struct {
	Name string
	Age  int
}

func main() {
	// 1. 定义模板字符串（在实际项目中，通常会将模板保存在单独的 .html 文件中）
	tmplStr := `
<!DOCTYPE html>
<html>
<head>
    <title>个人资料</title>
</head>
<body>
    <h1>欢迎，{{.Name}}！</h1>
    <p>您今年 {{.Age}} 岁。</p>
</body>
</html>`

	// 2. 解析模板字符串为模板对象
	// template.New 创建一个新模板，Parse 负责解析模板内容
	tmpl, err := template.New("profile").Parse(tmplStr)
	if err != nil {
		panic(err) // 生产环境中应妥善处理错误
	}

	// 3. 准备要渲染的数据
	user := Person{
		Name: "Alice",
		Age:  28,
	}

	// 4. 执行（渲染）模板，并将结果输出到标准输出 (os.Stdout)
	// Execute 的第一个参数是输出目标，第二个参数是要传入的数据
	err = tmpl.Execute(os.Stdout, user)
	if err != nil {
		panic(err)
	}
}

运行结果： 将输出填充了 Alice 和 28 的完整 HTML 页面。

示例 2：使用循环、条件和函数

这个例子展示了更复杂的模板操作。

package main

import (
	"html/template"
	"os"
	"strings"
)

type Article struct {
	Title   string
	Summary string
	Publish bool
}

func main() {
	// 自定义一个函数，用于在模板中使用
	funcMap := template.FuncMap{
		"toUpperCase": strings.ToUpper, // 让模板中可以用 toUpperCase 函数
	}

	// 模板内容，使用了循环、条件和自定义函数
	tmplStr := `{{/* 博客文章列表 */}}
{{range .Articles}}
{{if .Publish}}
<h2>{{toUpperCase .Title}}</h2>
<p>{{.Summary}}</p>
<hr>
{{end}}
{{end}}
{{/* 如果没有可显示的文章，则显示提示 */}}
{{if not .HasArticles}}
<p>暂无已发布文章。</p>
{{end}}`

	// 解析模板时，传入自定义函数映射
	tmpl, err := template.New("articles").Funcs(funcMap).Parse(tmplStr)
	if err != nil {
		panic(err)
	}

	// 准备数据
	data := struct {
		Articles    []Article
		HasArticles bool
	}{
		Articles: []Article{
			{"Go并发入门", "学习 goroutine 和 channel。", true},
			{"模板引擎详解", "深入理解 html/template。", true},
			{"草稿文章", "这只是个草稿。", false},
		},
		HasArticles: true, // 这里可以动态计算 len(Articles) > 0
	}

	// 渲染到标准输出
	err = tmpl.Execute(os.Stdout, data)
	if err != nil {
		panic(err)
	}
}

运行结果： 只会输出前两篇已发布文章的标题和摘要，且标题被转为大写。

实践练习

练习 1：基础个人信息页 创建一个 Go 程序，定义一个 User 结构体（包含 Name, Email, Bio 字段）。编写一个模板，生成一个简单的 HTML 页面来展示这些信息。将渲染后的 HTML 写入到一个文件 user.html 中，而不是直接输出到终端。

预期输出文件 (user.html) 内容示例：

<!DOCTYPE html>
<html>
<body>
    <h1>关于张三</h1>
    <p><strong>邮箱:</strong> [email protected]</p>
    <p><strong>简介:</strong> 这是一个爱好编程的开发者。</p>
</body>
</html>

练习 2：商品列表页 定义一个 Product 结构体（Name, Price, InStock）。编写一个模板，接收一个商品切片，生成一个带表格的商品列表页。要求：

只显示库存中（InStock 为 true）的商品。
价格大于 100 的商品用红色文字显示（使用内联样式）。
在列表末尾显示当前显示的商品总数。

预期输出结构示例（简化）：

<table>
  <tr><th>商品</th><th>价格</th></tr>
  <tr><td>键盘</td><td style="color: red;">¥199.00</td></tr>
  <tr><td>鼠标</td><td>¥89.00</td></tr>
</table>
<p>共显示 2 件商品。</p>

练习 3：模板继承与布局 创建三个模板文件：base.html（基础布局，定义 {{define “content”}}...{{end}} 区域）、home.html（首页内容，通过 {{template “content” .}} 继承布局）、about.html（关于我们页面）。编写一个程序，根据不同的 URL 路径（例如 / 和 /about）选择渲染对应的页面，并共享 base.html 的头部和导航栏。

常见错误

忘记解析模板：直接对字符串调用 Execute 会 panic。必须先通过 Parse 或 ParseFiles 等方法将模板字符串或文件解析为 *template.Template 对象。
模板字段或函数名大小写错误：Go 模板只能访问导出的（首字母大写的）结构体字段。如果在模板中写 {{.name}}，而结构体字段是 Name，将会渲染为空字符串（不会报错，但可能不符合预期）。
混淆 html/template 和 text/template：对于任何用户可见的 HTML 输出，必须使用 html/template 以获得自动转义保护。使用 text/template 渲染 HTML 是危险的。
在循环中错误使用点 .：在 {{range .Items}} 内部，点 . 的作用域变为当前遍历的元素。要访问外层作用域的数据（如 .Title），可以使用 $ 变量，它始终指向根数据。示例：{{$.SiteName}}。
试图在模板中执行复杂的逻辑：模板应专注于展示。复杂的业务逻辑、数据查询或转换应在 Go 代码中完成，然后将简洁的数据结构传递给模板。这有助于保持模板的可读性和可维护性。

小结

模板引擎将数据与表现层分离，是构建动态 Web 页面的基础工具。
在 Go Web 开发中，始终使用 html/template 包来渲染 HTML，它能自动转义输出，防止 XSS 攻击。
模板的核心语法包括访问字段 ({{.Field}})、循环 ({{range}})、条件 ({{if}}) 和调用函数 ({{func}})。
通过 FuncMap 可以将自定义的 Go 函数注册到模板中，扩展模板的能力。
保持模板的简洁性，将复杂逻辑放在 Go 代码端处理。

掌握模板引擎后，你将能够灵活地为你的 Web 应用生成丰富多样的 HTML 页面。下一课，我们将学习如何接收和处理用户通过表单提交的数据，这通常是与模板渲染协同工作的关键环节。

模板引擎