Go net/url区分 PathEscape 与 QueryEscape的参数对比

Go 的 net/url 里，PathEscape 和 QueryEscape 都能把特殊字符转成百分号编码，但它们服务的不是同一块数据：前者用于一个 URL 路径段，后者用于查询串中的键或值。最容易踩坑的场景是把带斜杠的业务编号放进 path，或把带空格、加号的搜索词直接拼到 ?q= 后面。

判断方法很简单：这个字符串是“一个路径段”，还是“查询参数的值”？前者用 PathEscape，后者用 QueryEscape 或 Values；不要因为函数名里都有 Escape 就互换。

先把 URL 分成路径域和查询域

URL 的 path 用斜杠表达层级，query 则由 ?、& 和 = 组织键值。PathEscape 的文档定义是把字符串安全地放进 path segment，特殊字符包括斜杠会按需要替换为 %XX；QueryEscape 则面向 query。两者的差异不是“编码多少”，而是要保护的分隔符不同。

同一组字符为什么会得到不同结果

用同一个输入对比最直观。下面的示例没有把输出写成运行截图，只展示 API 语义对应的结果关系：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	value := "team/a+b c&d"

	// PathEscape 把 value 当成一个路径段，斜杠不能继续充当层级分隔符。
	fmt.Println("path:", url.PathEscape(value))
	// QueryEscape 把 value 当成查询值，& 不能继续拆出新的键值对。
	fmt.Println("query:", url.QueryEscape(value))
}

按 net/url 的定义，路径版本会编码其中的斜杠，但会保留一部分 path 允许的字符；查询版本会把斜杠、加号和与号都视为需要保护的内容，空格按 query 规则表示。不要只看结果字符串“像不像”，要先确认它将被放入哪个 URL 位置。

在 URL 结构中分别写入 path 和 query

实际项目里不要手工把编码后的字符串拼在问号后面。路径参数先编码成单个段，查询条件交给 url.Values，这样更容易看出每个值的归属：

package main

import (
	"fmt"
	"net/url"
)

func buildURL(resourceID, keyword string) (*url.URL, error) {
	u, err := url.Parse("https://api.example.com/v1")
	if err != nil {
		return nil, err // 基础 URL 不合法时，不能继续写入动态参数
	}

	// resourceID 是一个整体标识；编码后再作为 Path 的一个 segment。
	u.Path = "/v1/items/" + url.PathEscape(resourceID)

	query := u.Query()
	// Query 的键值由 Values 负责转义，避免 keyword 中的 & 变成新参数。
	query.Set("q", keyword)
	query.Set("page", "1")
	u.RawQuery = query.Encode()
	return u, nil
}

func main() {
	u, err := buildURL("team/a", "c++ 入门")
	if err != nil {
		panic(err) // 示例只处理构造错误；服务代码应返回给调用方
	}
	fmt.Println(u.String())
}

这里的 team/a 是一个资源 ID，所以它在最终路径中应表现为一个编码段；如果业务真正需要两级路径，就应该把两个段分别传入拼接逻辑，而不是先合并再 Escape。查询部分则由 Values.Encode 统一处理，避免漏转义。

解码和双重编码要成对检查

服务端解析已有 URL 时，路径和查询也应按所在位置还原。PathUnescape 与 QueryUnescape 都会检查非法的百分号序列，但二者对加号的处理不同：路径解码保留 +，查询解码按查询语义将其还原为空格。

另一个常见错误是双重编码：第一次得到 team%2Fa 后，又把这个结果当作原始 ID 传给 PathEscape，最终会出现 %252F。建议在函数边界约定“输入是未编码业务值”，只在最后写入 URL 结构时编码一次。

func decodePathSegment(encoded string) (string, error) {
	// 只解码一个路径段；非法 %XX 让调用方明确感知，不要静默吞掉。
	return url.PathUnescape(encoded)
}

func decodeQueryValue(encoded string) (string, error) {
	// 查询值使用 QueryUnescape，和 QueryEscape 的语义保持配对。
	return url.QueryUnescape(encoded)
}

把参数选择固化为回归清单

• 资源 ID 含 / 时，确认它是一个段还是多个段；一个段必须使用 PathEscape。
• 查询值含 &、=、空格或加号时，使用 Values.Set 和 Encode。
• 检查输出 URL 中的 ?、&、= 仍只承担查询结构职责，path 中没有意外的业务层级。
• 检查编码只发生一次，解码函数与数据所在位置配对。

最终可以把规则压缩成一句话：PathEscape 保护路径段，QueryEscape 保护查询值，url.Values 负责多参数结构。只要先判断数据落点，再选择 API，URL 编码就不会靠猜。

常见问题

PathEscape 能不能用于整个 URL？

不能。它会把 scheme、host、路径和查询都当成普通字符处理；应先解析 URL，只对动态 path segment 调用。

QueryEscape 能不能替代 Values.Encode？

单个键或值可以使用，但多组参数仍建议使用 Values，因为它同时负责键值分隔和排序后的统一编码。

为什么路径里的加号没有变成空格？

加号是 query 解码中的空格约定，PathUnescape 不会把 path 中的 + 自动转换为空格。