Go html/template 怎么安全渲染用户提供的属性值

Go 中要把用户提供的值放进 HTML 属性，优先使用 html/template，并把值放在固定的属性位置里。它会根据文本、普通属性和 URL 属性所在的上下文自动转义；不要先用字符串拼接 HTML，也不要让用户输入决定标签名、属性名或事件代码。

html/template 能保护不可信数据跨越 HTML、属性和 URL 边界，但它不替你判断业务权限。固定模板结构、默认字符串类型、单独处理 URL，并对 template.HTML 保持严格信任边界，才是可审计的写法。

先把字符串和模板结构分开

html/template 的安全模型是：模板作者可信，Execute 接收的数据不可信。普通字符串会被当作文本处理，模板解析阶段再依据插值所在位置加入对应的转义逻辑。因此，值可以来自表单或数据库，但 HTML 标签和属性骨架应由代码固定。

package main

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

type PageData struct {
    Label string
    URL   string
}

func main() {
    // 属性位置由模板固定，Label 和 URL 只是待转义的数据。
    const page = `{{.Label}}`
    tmpl, err := template.New("page").Parse(page)
    if err != nil {
        log.Fatal(err)
    }

    // 模拟来自请求或数据库的不可信值；不要把它拼进模板字符串。
    data := PageData{Label: `新手 `, URL: `/profile?id=7&from=home`}
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        log.Fatal(err)
    }
}

这里同一个 Label 出现在文本节点和 title 属性中，模板会按位置分别编码。值里即使出现尖括号、引号或 ampersand，也不会改变标签结构。图1把输入、模板上下文和浏览器输出的关系放在一起，排查时先看值进入了哪个上下文。

固定 data-* 属性比动态属性名更容易审查

如果页面需要把一个筛选条件交给前端，建议固定写成 data-filter 或 data-id，只让值变化。不要写成“属性名和值都由用户提交”的拼接逻辑；动态结构会让代码审查者无法稳定判断输入最终落在哪个上下文。

const item = `{{.Name}}`

// ID 和 Name 仅作为属性值或文本，属性名与标签仍由服务端控制。
tmpl, err := template.New("item").Parse(item)
if err != nil {
    return err
}

data- 属性仍然会参与属性上下文的处理，不是“因为给 JavaScript 读就自动安全”。前端拿到值后也要按数据使用，不能把它再次当成 HTML 或脚本执行。

href、onclick 和 style 不是同一种属性

URL 属性除了要编码字符，还涉及协议是否允许。把用户输入放进 href 时，https:、mailto: 等可接受协议与 javascript: 这类危险协议的处理不同；模板可能把不安全值替换成 #ZgotmplZ。这能阻止一条明显的脚本 URL，但不能代替业务层的链接白名单和权限判断。

事件处理器和内联样式更难维护。不要把用户值放入 onclick 的 JavaScript 片段，也不要拼到 style 属性中。需要交互时输出固定的 data-* 值，由前端代码读取并按类型处理；需要样式时使用固定 class 和有限枚举，而不是接受任意 CSS。

template.HTML 只给真正可信的片段

template.HTML、template.URL 等 typed string 可以表达已经被信任的内容，并因此减少默认转义。它们不是“更强的清洗函数”，而是对模板说“这段内容已经符合对应上下文”。如果把用户提交的 HTML 直接转换成 template.HTML，就等于自己关闭了默认保护。

type ViewData struct {
    Title string
    // FooterHTML 只能来自代码内固定片段或独立审核后的渲染结果。
    FooterHTML template.HTML
}

// 普通 Title 继续按文本处理；可信片段才使用明确的 typed string。
data := ViewData{
    Title:      userTitle,
    FooterHTML: template.HTML(`服务条款`),
}

更稳妥的边界是：业务数据保持普通字符串，富文本经过专门的允许标签和属性策略后再进入一个很小的适配层，并记录来源。仅仅调用 template.HTML(userInput) 不构成安全处理。

发布前按五项清单复核

1. 搜索生成 HTML 的包，确认网页模板使用的是 html/template。
2. 沿着每个用户值追踪它是文本、固定属性值、URL，还是事件和样式片段。
3. 检查标签、属性名、事件名和 class 是否由服务端固定，拒绝结构拼接。
4. 对 href 先做业务协议、域名和权限规则，再依赖模板做上下文转义。
5. 逐处审查 template.HTML、template.URL 等特殊类型，确认来源不是原始用户输入。

这份清单的重点不是记住某个转义函数，而是让“数据”和“模板结构”始终分开。模板负责上下文编码，业务代码负责允许什么链接、谁能看到什么内容，前端负责把 data-* 当作数据而不是代码。

相关问题

为什么不能用 text/template 生成 HTML？

text/template 没有 html/template 的上下文自动转义。它适合纯文本，不适合把不可信数据直接嵌入网页。

用户输入放进 href 后变成 #ZgotmplZ 是 bug 吗？

通常这是模板对不安全 URL 协议的保护信号。先检查业务是否允许该协议和目标，再决定如何显示或拒绝，不要直接把它转换成 template.URL 绕过处理。

把用户内容先调用 html.EscapeString 再放进模板可以吗？

一般不要重复做上下文转义。普通字符串交给 html/template，让它根据实际位置处理；手工 HTML 转义还可能在 URL、JavaScript 等上下文中使用错误的规则。

data-* 属性是不是完全不需要安全处理？

不是。模板仍会处理属性值；同时前端不能把属性值重新交给 innerHTML 或脚本解释器。

参考：html/template 官方文档、Go 官方模板安全模型说明、Go 官方 typed string 定义。