URL 转义

Go 里的 URL 转义，关键不在于“哪个函数能把字符变成百分号编码”，而在于这个值最终要放在 URL 的哪个位置：要作为一个路径段，使用 url.PathEscape；要作为查询参数的键或值，优先使用 url.Values，必要时才单独使用 url.QueryEscape。两者不能互换，尤其要小心斜杠、加号和空格。

判断口诀：斜杠要不要继续表示路径层级？如果不应该，就把它当作路径段内容交给 PathEscape；如果值要进入 ?key=value，就交给查询参数编码。

先划清 URL 转义的两个位置

一个 URL 通常至少有路径和查询两块语义不同的区域。例如：

https://example.com/files/report%2F2026?keyword=a%2Bb&page=2

这里的 report%2F2026 是一个路径段，它原本包含字符 /，所以斜杠不能再被解释为新的层级；keyword=a%2Bb 是查询参数，值里的加号必须作为普通字符保存。

Go 的 net/url 文档将 PathEscape 定义为“安全放进 URL 路径段”的转义，将 QueryEscape 定义为“安全放进 URL 查询”的转义。这个差异就是选函数的第一条检查点。

路径段：用 PathEscape 保护值里的斜杠

当一个变量代表“一个资源标识”或“一个路径段”时，应先用 PathEscape。例如资源名是 reports/2026+Q4，其中的斜杠是资源名的一部分，而不是 URL 的层级分隔符：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 这个值代表一个完整路径段，内部的斜杠不能再拆成两层路径。
	segment := "reports/2026+Q4"
	escaped := url.PathEscape(segment)

	// PathEscape 会把斜杠编码为 %2F，但不会把加号当成空格。
	fmt.Println(escaped)

	// 对应的解码函数只负责还原路径段本身。
	decoded, err := url.PathUnescape(escaped)
	if err != nil {
		// 输入中有不完整的百分号编码时，必须保留错误并停止使用结果。
		panic(err)
	}
	fmt.Println(decoded)
}

输出的关键形态是：

reports%2F2026+Q4
reports/2026+Q4

注意这里的加号仍然是加号。PathUnescape 只做百分号序列的还原，不会把 + 改成空格。

查询参数：优先使用 url.Values

查询参数不是把字符串直接拼到 ? 后面。只要值中可能出现 +、&、空格或中文，就应该让 url.Values 负责键值编码和参数连接：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// Query 参数的值可能包含加号和连接符，不能手工拼接。
	values := url.Values{}
	values.Set("keyword", "a+b & c")
	values.Set("page", "2")

	// Encode 同时处理键和值，并用 & 连接多个参数。
	encoded := values.Encode()
	fmt.Println(encoded)

	// ParseQuery 使用与查询区域匹配的规则把它还原成键值集合。
	decoded, err := url.ParseQuery(encoded)
	if err != nil {
		// 查询串出现坏的百分号编码时，不要静默忽略解析错误。
		panic(err)
	}
	fmt.Println(decoded.Get("keyword"))
}

这里的关键输出类似：

keyword=a%2Bb+%26+c&page=2
a+b & c

查询编码中的 + 常用来表示空格，所以原值中的字面加号会编码成 %2B。这也是手工调用 QueryEscape 时最容易误判的地方。

把路径和查询放进同一个 URL

实际请求往往同时包含路径段和查询参数。正确的流程是分别处理两种语义，最后让 url.URL 组合它们：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 先解析固定的基地址，再分别处理动态路径段和查询参数。
	u, err := url.Parse("https://example.com/files/" + url.PathEscape("reports/2026+Q4"))
	if err != nil {
		panic(err)
	}

	// Query 返回可编辑的 Values，避免自己处理 ?、& 和百分号编码。
	query := u.Query()
	query.Set("keyword", "a+b")
	query.Set("page", "2")
	u.RawQuery = query.Encode()

	// String 会把路径与 RawQuery 重新组合成可传输的 URL 文本。
	fmt.Println(u.String())
}

这个例子表达的是“先编码路径段，再编码查询参数”。不要把整条 URL 作为一个普通字符串再调用某一个 Escape 函数，否则 ?、& 和 / 的结构也会被一起当成数据。

用往返结果判断是否选对函数

如果不确定某个函数是否适用，可以先问一个更具体的问题：编码后的文本被放到哪里，之后由哪一种解析规则读取？路径用 PathEscape 对应 PathUnescape；查询值用 QueryEscape 对应 QueryUnescape，或者直接使用 url.Values 与 url.ParseQuery。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 同一个原始值放入两种 URL 位置，会得到不同的编码结果。
	raw := "a/b+c"
	pathText := url.PathEscape(raw)
	queryText := url.QueryEscape(raw)

	pathBack, pathErr := url.PathUnescape(pathText)
	queryBack, queryErr := url.QueryUnescape(queryText)
	if pathErr != nil || queryErr != nil {
		// 任一方向不能解码，都说明输入或配对函数需要重新检查。
		panic("URL 转义往返失败")
	}

	fmt.Println(pathText, "=>", pathBack)
	fmt.Println(queryText, "=>", queryBack)
}

这里要记住两个差异：

• PathEscape("a/b+c") 会把斜杠编码为 %2F，加号仍保持字面加号。
• QueryEscape("a/b+c") 会把斜杠和加号都编码；查询解码时，百分号编码的加号会还原成字面加号。

而对一个手写的查询文本 a+b 调用 QueryUnescape 时，+ 会被解释为空格。这不是矛盾，而是查询编码规则本身的约定：字面加号必须先写成 %2B。

一套不容易出错的工作流

1. 确认位置：把值标记为路径段、查询键、查询值，或只是普通文本；不要对整条 URL 做统一转义。
2. 选择工具：路径段使用 PathEscape；查询参数使用 url.Values；只有处理单个查询片段时才直接考虑 QueryEscape。
3. 组合结构：让 url.URL、Values.Encode 和 URL.String 处理分隔符，不手工拼接多个未经编码的值。
4. 配对解码：路径编码配 PathUnescape，查询编码配 QueryUnescape 或 ParseQuery。
5. 检查特殊字符：至少拿包含 /、+、空格和 & 的样例走一遍，确认它们没有改变原本的业务含义。

常见误区与速查表

最终可以把判断压缩成一句话：路径段的分隔符属于 URL 结构，参数值里的字符属于数据。先确定这两个角色，再选择对应的转义函数，URL 中的斜杠、加号和空格就不会因为“看起来都要编码”而被混用。

相关问题

PathEscape 能不能替代 QueryEscape？

不能。它们面对的语法位置不同；在查询参数中误用 PathEscape，可能让加号、连接符或空格的含义与接收方预期不一致。

为什么查询参数里的加号经常变成空格？

因为查询解码规则把裸 + 当作空格。业务数据确实包含加号时，应让 url.Values 编码成 %2B。

什么时候应该直接用 url.Values？

只要有一个以上查询参数，或者键和值来自变量，就直接使用 url.Values。它能同时处理编码和参数之间的 & 连接，代码更不容易漏掉边界。