html/template 安全输出动态链接属性的设计要点

我在给 Go 页面加“外部文档”链接时，最容易误判的一点是：把 URL 当成普通字符串拼进 HTML，并不等于完成了安全处理。更稳的分工是让 html/template 负责根据输出位置做上下文转义，让业务代码负责决定哪些协议和目标地址有业务意义。

结论先说：模板里直接写 ，不要手工拼接 HTML，也不要为了“跳过转义”随意把字符串转换成 template.URL。先在业务层筛选允许的 URL，再把普通字符串交给 html/template 执行。

官方资料：https://pkg.go.dev/html/template

先把动态值放进正确的属性上下文

html/template 的关键能力不是简单替换字符，而是观察动作出现在哪里。相同的值放在文本节点、title 属性和 href 属性里，所需的处理不同：文本要防止改变 HTML，普通属性要防止冲出引号，URL 属性还要考虑 URL 上下文和协议。

模板只描述结构，不负责拼接 HTML

实际项目里可以把动态链接收敛成一个数据结构，模板只保留明确的属性边界。下面的例子先把用户输入解析成 URL，再只允许业务需要的 http 和 https 协议，最后把普通字符串交给模板。这样 URL 策略和 HTML 输出各自有清晰的责任。

package main

import (
	"fmt"
	"html/template"
	"io"
	"net/url"
	"strings"
)

type Link struct {
	Label string
	URL   string
}

func allowLink(raw string) (string, error) {
	// 先解析 URL，再按业务白名单限制协议；不要仅靠字符串前缀判断。
	u, err := url.Parse(raw)
	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
		return "", fmt.Errorf("不允许的链接: %q", raw)
	}
	return u.String(), nil
}

func render(w io.Writer, raw string) error {
	link, err := allowLink(raw)
	if err != nil {
		return err
	}

	// href 的引号和 URL 上下文由 html/template 自动处理。
	const page = `{{.Label}}`
	tmpl, err := template.New("link").Parse(page)
	if err != nil {
		return fmt.Errorf("解析模板: %w", err)
	}
	return tmpl.Execute(w, Link{Label: "Go 文档", URL: link})
}

func main() {
	// 用 strings.Builder 演示输出目标；HTTP 响应中可替换成 http.ResponseWriter。
	var out strings.Builder
	if err := render(&out, "https://pkg.go.dev/html/template?q=href"); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(out.String())
}

这里有两个重点。第一，模板数据仍然是普通 string，没有把未经确认的内容升级成安全类型。第二，Parse 和 Execute 都保留错误返回，模板结构写错或执行阶段遇到问题时，调用方可以决定返回错误页面，而不是继续输出半成品。

协议筛选和 template.URL 要分开

当动态值进入 href 时，html/template 会做上下文相关处理。对不适合放进 URL 属性的协议，它可能输出 #ZgotmplZ 一类的安全占位结果。这个行为保护了 HTML 结构，但它不是业务授权系统：你仍然要在业务层决定是否允许外链、是否限制域名，以及相对路径能否出现。

template.URL、template.HTMLAttr 等类型表达的是“调用方已经确认这段内容安全”。它们会越过一部分普通字符串的保护，因此不能把类型转换当成修复手段。只有当值来自明确的内部构造、经过严格约束并且团队愿意承担信任责任时，才考虑使用。

把完整流程拆成四个检查点

1. 输入点：明确 URL 来自数据库、配置还是用户输入，并保留原始值用于错误记录，不把它直接当 HTML。
2. 策略点：用 net/url 解析，按业务决定允许的协议、主机和相对路径；不要只检查字符串是否以 https:// 开头。
3. 模板点：保持属性有引号，直接使用 {{.URL}}，不要在模板中调用 printf 拼接标签或手写转义。
4. 输出点：检查 Parse、Execute 的错误；如果策略拒绝链接，显示安全的替代文案或站内链接。

如果链接是站内路由，可以把路由名和参数分开传入，让服务端生成相对路径；如果必须输出外链，则把“允许哪些目标”写成可审查的策略，而不是散落在多个模板函数里。

常见误区和最终决策表

• 用 text/template 生成 HTML：它没有 HTML 上下文自动转义，不适合作为 HTML 模板引擎。
• 用 template.HTML 包住完整的 ：这会把结构安全责任重新交回业务代码，除非内容来自可信且已审计的构造器，否则不要这么做。
• 只看到页面能点击就认为安全：点击结果不能证明属性边界、协议和错误路径都符合预期。

相关问题

为什么 href 里的危险值没有原样输出？因为 html/template 会结合 URL 上下文做转义和协议安全处理；业务仍要负责更细的允许列表。

可以在模板里手工调用 html 或 urlquery 吗？新模板通常应让上下文自动转义工作，手工套预定义转义函数容易改变语义，复杂拼接还会让上下文变得不清楚。

什么时候才使用 template.URL？只有当值由可信代码构造、来源和协议已经被严格约束，并且调用方明确承担“原样信任”的责任时；普通用户输入不属于这个范围。