Go html/template上下文转义保护用户可见片段的实践

Go 页面里只要把用户昵称、搜索词、跳转地址或配置值插入 HTML，就不能把模板当成普通字符串拼接。这个标题对应的实践重点是：使用 html/template，让模板根据动态值所在的 HTML、属性、URI、JavaScript 或 CSS 上下文自动选择转义方式；只有明确可信且经过审查的片段，才考虑使用安全类型。

用 html/template 建立第一道保护

html/template 与 text/template 共享大部分模板接口，但它额外理解 HTML 结构。动态值默认被当作普通文本处理，所以尖括号、引号等字符会被编码，不能改变模板作者已经写好的标签边界。

package main

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

func main() {
	// 模板作者控制结构，页面数据只作为不可信的文本进入结构。
	const source = `
{{.}}
`
	tmpl, err := template.New("notice").Parse(source)
	if err != nil {
		log.Fatal(err) // 解析失败时停止，避免使用不完整模板。
	}
	// 这段字符串会被转成 HTML 实体，而不会成为新的标签。
	if err := tmpl.Execute(os.Stdout, `未审核内容`); err != nil {
		log.Fatal(err) // 输出端失败也要让调用方知道渲染没有完成。
	}
}

上例的关键不是手工调用某个转义函数，而是让模板引擎知道值最终会落在 HTML 文本节点。实践中，模板解析和执行错误都应保留；不要为了“页面能显示”而忽略 Execute 返回的错误。

不同上下文要按不同结果判断

模板中的 {{.}} 不是一个固定的“统一编码器”。放在正文时主要进行 HTML 转义，放在属性中要处理引号和属性边界，放在 URL 查询参数里还会进行 URL 编码。解析阶段会根据周围模板结构加入对应的内部处理。

const source = `
{{.Text}}
查询
`

// Text、Query、State 处于不同上下文，不能用一个手工函数覆盖全部场景。
tmpl, err := template.New("page").Parse(source)
if err != nil {
	log.Fatal(err) // 模板结构不合法时不要继续执行。
}
err = tmpl.Execute(os.Stdout, struct {
	Text  string
	Query string
	State struct{ Ready bool }
}{
	Text:  `普通文本`,
	Query: `a&b`,
	State: struct{ Ready bool }{Ready: true},
})
if err != nil {
	log.Fatal(err) // 数据编码或输出错误必须向上返回。
}

链接值还要关注协议边界。一个看起来像字符串的值，如果被放进不安全的 URL 位置，模板可能输出 #ZgotmplZ，这表示该值没有通过允许协议的判断。它不是“转义失败”，而是提醒你重新确认链接来源和用途。

属性和安全类型是最容易误判的地方

data-href 仍然是属性语境，不能因为名字以 data- 开头就把它当作普通文本容器。事件属性、内联脚本、样式表达式更应谨慎：能改成普通数据属性或由服务端生成固定枚举，就不要把任意字符串拼进执行语境。

template.HTML、template.URL 等类型表达的是“调用者已经保证这段内容符合目标语境”。它们不是清洗器，也不会替你验证数据库字段是否可信。比如文章编辑器产生的 HTML 片段，必须先经过明确的白名单清洗和来源控制，才能考虑转换成安全类型；用户直接提交的字符串继续保持 string。

上线前按清单复查模板边界

我通常在代码评审里按五项检查：第一，生成 HTML 的包是否始终是 html/template；第二，数据是否通过结构化字段传入而不是拼接模板源码；第三，链接协议和跳转范围是否有限定；第四，所有安全类型是否能追溯到白名单清洗或固定常量；第五，Parse、Execute 的错误是否会被记录并交给调用方。

这套检查不能替代业务授权，也不能把不可信 HTML 变成可信 HTML。它的价值是把“动态值会落在哪里”变成可读的工程约束，后续新增一个属性或脚本数据字段时，评审者可以沿着上下文重新判断，而不是只看变量名。

相关问题

html/template 和 text/template 可以互换吗

接口大体相似，但输出 HTML 时不应互换。text/template 不负责 HTML 上下文转义，页面渲染应优先使用 html/template。

为什么链接结果会出现 #ZgotmplZ

通常是 URL 值处在不安全协议或不允许的上下文中。先检查值的来源、协议白名单和模板位置，不要直接把它替换成手工拼接。

什么时候可以使用 template.HTML

只有内容来源可信、结构已经经过严格白名单处理，并且调用者愿意承担该语境的安全责任时才考虑；用户输入不能因为“看起来像 HTML”就转换。