Go html/template 怎样为 URL 属性限制协议

模板里有一个看似普通的 href 属性，真正上线后却经常暴露两个边界：输入可能带有不应该出现的协议，或者开发者为了“让链接原样输出”而关闭了模板的保护。Go 的 html/template 会识别 URL 上下文并进行上下文转义，但它不是业务协议白名单。要限制得更明确，应该在数据进入模板前做允许列表，再让模板继续负责 HTML 属性编码。

官方地址：https://pkg.go.dev/html/template

先记结论：URL 属性不要字符串拼 HTML。用 html/template 渲染普通字符串，让标准库在 URL 上下文中兜底；业务层再只放行 http、https 和明确的根路径相对地址。不要为了绕过过滤把未经检查的值转换成 template.URL。

触发信号：href 里的值为什么不能只看字符串

假设页面需要展示一个由接口返回的跳转地址。把它放进普通文本节点时，重点是 HTML 字符转义；放进 href 时，模板还要理解它是 URL。官方文档把这种处理称为上下文自动转义：同一个数据值进入 HTML、JavaScript、CSS 和 URI 位置时，安全处理方式不同。

因此，href="{{.Href}}" 与

{{.Href}}

快速判断：先让 html/template 保持默认保护

最小模板应该保持普通字符串输入，让 html/template 接管上下文处理。下面的代码只展示渲染边界，故意不把输入转换为 template.URL。代码是发布时的示例，重点是数据类型和模板上下文，不应把示例值当成真实业务地址。

package main

import (
	"html/template"
	"os"
)

// PageData 保持链接为普通字符串，让模板负责上下文转义。
type PageData struct {
	Href string
}

func main() {
	// href 位置会触发 URL 上下文处理，不要改成字符串拼接。
	tpl := template.Must(template.New("link").Parse(`打开链接`))
	data := PageData{Href: "https://example.com/docs"}

	// Execute 的错误应交给调用方处理；示例直接退出并保留错误信息。
	if err := tpl.Execute(os.Stdout, data); err != nil {
		panic(err)
	}
}

这一层解决的是“如何安全地把字符串放进 HTML URL 属性”，不是“业务到底允许哪些协议”。如果协议限制是产品规则，就继续在数据层加一层明确判断；不要依赖某一次输出恰好没有出现危险协议。

处理步骤：在数据进入模板前做协议允许列表

下面的辅助函数只接受三类输入：绝对的 http、https，以及以单个斜杠开头的站内根路径。相对路径的规则是本文的业务边界；如果项目还允许 mailto、锚点或自定义协议，应单独设计并记录，不要悄悄扩大允许范围。

package linkpolicy

import (
	"fmt"
	"net/url"
	"strings"
)

// AllowHref 只返回可以交给 html/template 的普通字符串。
func AllowHref(raw string) (string, error) {
	if raw == "" {
		return "", fmt.Errorf("链接不能为空")
	}
	// 双斜杠会把路径解释成外部主机，不能当作站内根路径。
	if strings.HasPrefix(raw, "//") {
		return "", fmt.Errorf("不允许协议相对地址")
	}

	u, err := url.Parse(raw)
	if err != nil {
		return "", fmt.Errorf("链接格式错误: %w", err)
	}
	if u.IsAbs() {
		// 只允许明确的网页协议，其他协议直接失败。
		switch strings.ToLower(u.Scheme) {
		case "http", "https":
			return u.String(), nil
		default:
			return "", fmt.Errorf("不允许协议 %q", u.Scheme)
		}
	}
	if strings.HasPrefix(raw, "/") {
		// 根路径相对地址交给模板继续做属性编码。
		return raw, nil
	}
	return "", fmt.Errorf("只允许根路径相对地址")
}

调用方应在组装页面数据时处理错误；失败时可以不渲染链接、返回业务错误或使用一个明确的站内兜底地址。重要的是保持返回值为普通 string，让模板仍然负责引号、尖括号和 URL 字符的编码。

回滚路径：哪些“修复”反而会放宽边界

如果旧代码把链接写成字符串拼接，回滚到模板表达式时应同时保留数据层允许列表；只改模板、不改输入策略，往往会把职责重新混在一起。尤其不要对任意外部输入直接使用 template.URL。这个类型表达的是调用方已经确认内容可安全作为 URL，使用它会绕开普通字符串的部分转义保护，不能拿来当协议过滤器。

同样，不能因为某个输入被输出成 #ZgotmplZ 就把所有 URL 标记为可信类型。正确回退是记录原始输入的拒绝原因、保留安全的默认链接，或者让当前字段不出现；不要用类型转换掩盖规则缺失。

告警确认：用边界表复查输入和输出

复查时同时看三处：业务层是否只返回允许范围，模板是否仍是 html/template，以及页面是否把错误路径当作正常链接继续渲染。协议白名单保护的是入口约束，模板上下文转义保护的是输出边界，两者互相补位。

复盘项与常见问题

html/template 能自定义允许协议吗？

它会对 URL 上下文执行内置的安全处理，但业务允许范围最好由应用层显式定义。这样可以把“允许哪些协议”作为可审查的产品规则，而不是依赖模板内部行为。

根路径相对地址安全吗？

本文允许的是以单斜杠开头的站内根路径，并主动拒绝双斜杠协议相对形式。实际项目还要结合部署域名、重定向策略和路由规则决定是否需要更细的约束。

什么时候可以使用 template.URL？

只有当值来自可信的、已经完成完整 URL 规则检查的内部构造过程时才考虑。它不是把用户输入变安全的函数；对于接口、表单或数据库里的未信任字符串，继续使用普通 string。

把 URL 协议限制放在数据层、把上下文转义留给 html/template，边界就容易解释：协议不合规时失败或兜底，字符需要编码时由模板处理。这样既能收紧允许范围，也不会因为追求“原样输出”而拆掉标准库的安全模型。