Go URL路径中的加号与空格编码差异排查指南

接口日志里出现 /files/a+b 和 q=a+b 时，不要先把加号统一替换成空格。Go 的 net/url 把路径段和查询参数当作两种不同组件：路径中的字面量 + 通常应保留为加号，查询串里的 + 则可能代表空格。排查的关键是先确认值属于哪一段，再选择编码和解码函数。

官方文档：https://pkg.go.dev/net/url

为什么加号在路径和查询中会得到不同结果

PathEscape 的职责是安全地放入路径段，QueryEscape 的职责是安全地放入查询参数。它们都处理百分号编码，但保留字符集合不同，因此不能只看函数名里的 Escape 就认为结果可以互换。

实际排查时，把四个值并排记录最有效：原始空格、原始加号、编码后的 %20 或 +，以及字面加号对应的 %2B。查询编码中的 + 是空格的常见表示，而路径编码不能依赖这个约定来表达空格。

生产代码如何按组件选择编码函数

查询串由 url.Values 管理，路径变量则应先按 segment 编码后再拼到固定路径模板。下面的示例故意同时放入空格、加号和斜杠，便于看出“数据字符”和“路径分隔符”的边界。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	name := "a+b note"
	// 路径变量只编码一个 segment，斜杠会被当作数据而不是层级分隔符。
	pathSegment := url.PathEscape(name)

	query := url.Values{}
	// 查询参数交给 Values.Encode，空格和字面加号会使用查询规则。
	query.Set("q", name)

	fmt.Println("/files/" + pathSegment)
	fmt.Println("/search?" + query.Encode())
}

如果资源 ID 本身允许包含斜杠，使用 PathEscape 是必要的；如果斜杠本来就代表层级，就应该拆成多个 segment 分别编码。查询部分不要先用字符串拼接再补转义，否则很容易把已经编码的百分号再次变成 %25。

用 URL 字段和解码函数定位二次编码

解析后的 URL.Path 是解码形式，保留原始编码提示时要看 EscapedPath，查询原文则在 RawQuery 中。排查日志时，先判断你打印的是语义值还是传输表示，再决定是否解码。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	raw := "https://example.com/files/a+b?q=a+b&tag=a%2Bb"
	u, err := url.Parse(raw)
	if err != nil {
		// 解析失败时保留原始输入，避免把错误误判成加号规则。
		panic(err)
	}

	pathValue, pathErr := url.PathUnescape("a+b")
	queryValue, queryErr := url.QueryUnescape("a+b")
	if pathErr != nil || queryErr != nil {
		// 百分号后缺少两位十六进制字符时，必须停止继续处理。
		panic("invalid escape sequence")
	}

	fmt.Println(u.Path, u.EscapedPath(), u.RawQuery)
	fmt.Println(pathValue, queryValue)
}

这个检查能区分两类常见故障：把路径里的 + 错解为空格，以及把查询里的字面加号当成普通空格。服务端如果使用框架自动解析 query，就不要再对已经得到的值调用一次 QueryUnescape；否则会出现二次解码。

上线前的编码边界检查清单

回归测试至少覆盖 "a b"、"a+b"、"a/b" 和 "a%2Bb"。测试断言应分别写在 path 和 query 两组场景里，不能只断言最终整条 URL 字符串。

常见问题

路径里的加号什么时候会变成空格

Go 的 PathUnescape 不会把加号变空格；如果发生了变化，通常是后续框架、代理或业务代码按表单查询规则做了解码。

QueryEscape 能不能用来编码路径

不建议。它针对 query 设计，字面加号、斜杠和空格的处理语义不同；路径变量应使用 PathEscape 并按 segment 组装。

为什么看到 %252B

这通常表示原本的 %2B 又被编码了一次，百分号变成了 %25。沿链路记录每一层输入和输出，找到第一次重复 Escape 的位置即可。