Go html/template.URLQueryEscaper 如何编码查询参数：空格、加号与多值参数边界

模板里拼下载链接时，最容易把一个查询值和整段查询串混在一起：用户输入的“Go 并发 + 入门”如果直接塞进 href，空格、加号和 & 都可能改变浏览器实际解析出的参数。Go 的 html/template.URLQueryEscaper 适合处理一个查询值；如果页面要生成多值参数或完整查询串，则应交给 url.Values。

记住一个边界：URLQueryEscaper 负责把参数值变成可嵌入查询部分的文本，不负责替你拼接键名、多个键或重复键。

URLQueryEscaper 解决的是“一个值”

html/template.URLQueryEscaper 的参数是可变数量的 any，它先把参数转成文本，再按 URL 查询值的规则处理。最小示例不需要手写百分号编码：

package main

import (
	"fmt"
	"html/template"
)

func main() {
	value := template.URLQueryEscaper("Go 并发 + 入门")
	fmt.Println(value)
}

这里的输入是一个值，不是 keyword=... 这整段表达式。图中把 URLQueryEscaper、空格、加号 和 查询参数 放在同一条路径上，便于把字符处理和键名拼接区分开。

空格、加号和 & 为什么要单独验收

查询字符串中的 + 常被服务端按空格解释，而输入内容本身也可能带有真正的加号。不要靠日志里的肉眼观察判断是否安全，直接打印转义结果，再用接收端的解析函数验证还原后的值。

package main

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

func main() {
	encoded := template.URLQueryEscaper("C++ 入门 & 实战")
	query := "keyword=" + encoded
	values, err := url.ParseQuery(query)
	if err != nil {
		panic(err)
	}
	fmt.Println(query)
	fmt.Println(values.Get("keyword"))
}

ParseQuery 是验收环节，不是编码环节。它把服务端收到的查询串重新解析成键和值；如果只看浏览器地址栏，往往看不出“原始加号”和“空格”是否被混淆。生产日志建议同时记录参数名和解析后的业务值，避免记录未经筛选的敏感内容。

多值参数交给 url.Values.Encode

搜索条件可能有多个标签，例如 tag=go&tag=web。这时继续手工调用 URLQueryEscaper，很快就会变成字符串拼接代码；url.Values 更能表达“一个键有多个值”的数据结构：

values := url.Values{}
values.Add("tag", "go")
values.Add("tag", "web")
values.Set("keyword", "C++ 入门")

query := values.Encode()
fmt.Println(query)
fmt.Println(values.Get("tag"))

url.Values 保存键到字符串切片的映射，Add 追加同名值，Set 覆盖同名值，Encode 负责生成查询串。它还会对键排序，所以同一组数据在日志、测试和缓存键里更容易保持稳定。

模板里怎么放进 href

如果参数来自模板数据，尽量把“值的准备”和“URL 的输出上下文”拆开。下面的模板只把 URLQueryEscaper 用在参数值位置，固定的键名和路径仍由模板本身提供：

const page = `搜索`

t := template.Must(template.New("page").Parse(page))
_ = t.Execute(os.Stdout, struct{ Keyword string }{
	Keyword: "Go 并发 + 入门",
})

实际程序别忘了导入 os，示例重点是模板上下文。html/template 会根据插值所在的属性和 URL 位置继续做上下文处理；不要把已经拼好的整段 URL 标记成信任内容来绕过它。

几个容易误用的边界

• 只给查询值编码，不要把完整 keyword=... 再当成一个值编码。
• 需要重复键时使用 Values.Add，不要手写多个字符串片段。
• 需要覆盖旧值时使用 Values.Set，避免同名参数残留。
• 编码和解析要成对测试，至少覆盖空格、加号、中文、& 和空字符串。

相关问题

URLQueryEscaper 能代替 url.Values 吗？

不能。前者适合单个查询值，后者表达键和值的集合，并负责多值参数和完整查询串。

为什么不直接使用字符串拼接？

手拼时容易漏掉一个值的编码、重复键的边界或字符顺序稳定性；url.Values 把这些规则集中在标准库里。

模板里的参数还需要 html/template 吗？

需要。查询值的编码和 HTML 属性上下文安全是两个问题，应让 html/template 继续处理输出上下文。

小结

把 URLQueryEscaper 当成单值转换器，把 url.Values.Encode 当成查询集合编码器，代码边界就清楚了。最值得保留的测试不是一条“看起来正常”的链接，而是空格、加号、中文、&、重复键和解析结果组成的一组输入输出。