Go url.URL.RawPath 为什么设置后没有按预期编码

我在排查一条带编码斜杠的请求路径时，最容易误判的地方就是：明明给 url.URL.RawPath 赋了值，最后 String() 输出的路径却没有照着它走。原因通常不是 Go “把编码改错了”，而是把 Path、RawPath 当成了同一种数据。

Go 的 net/url 会把 Path 保存为解码后的路径；RawPath 只是可选的编码提示。只有当它确实是 Path 的有效编码时，EscapedPath() 才会采用它，否则就会忽略并重新计算编码。

官方资料：https://pkg.go.dev/net/url#URL.RawPath

解决这类问题的关键不是强行改 RawPath，而是先确定路径中的斜杠是路由分隔符还是数据内容，再让 Path 保存解码值、让 RawPath 只承担需要保留的编码差异。

先分清 Path、RawPath 和 EscapedPath

下面这段关系很重要：解析后的 Path 负责表达路径语义，RawPath 负责在必要时保留原始编码，最终的 String() 和 RequestURI() 都通过 EscapedPath() 取得编码后的路径。

package main

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

func main() {
	// %2F 表示数据中的斜杠，不应在解析后和普通路径分隔符混为一谈。
	u, err := url.Parse("https://example.com/docs/a%2Fb")
	if err != nil {
		log.Fatal(err)
	}

	// Path 是解码后的语义值，RawPath 保存可选的原始编码提示。
	fmt.Println("Path:", u.Path)
	fmt.Println("RawPath:", u.RawPath)
	fmt.Println("EscapedPath:", u.EscapedPath())
	fmt.Println("RequestURI:", u.RequestURI())
}

这里的重点不是记住某一组输出，而是记住读取层次：需要判断用户看到的请求路径时看 EscapedPath() 或 RequestURI()；不要把直接读取 RawPath 当成最终答案。官方文档也建议一般调用 EscapedPath()，而不是直接读取 RawPath。

确认 RawPath 是否真的是 Path 的有效编码

RawPath 不是“想输出什么就写什么”的覆盖开关。它能被使用的前提是：对它做路径解码后，结果必须与 Path 对应。只要两者不一致，EscapedPath() 就会放弃这个提示并重新生成编码。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	valid := &url.URL{
		// Path 使用解码后的值，表示 a/b 的路径语义。
		Path: "/docs/a/b",
		// RawPath 保留第二个斜杠原本是 %2F 的编码差异。
		RawPath: "/docs/a%2Fb",
	}
	fmt.Println("有效提示:", valid.EscapedPath())

	invalid := &url.URL{
		// 这里的 Path 与 RawPath 解码结果不一致，提示会失效。
		Path: "/docs/a/c",
		RawPath: "/docs/a%2Fb",
	}
	fmt.Println("无效提示:", invalid.EscapedPath())
}

因此，“RawPath 设置了但没有按预期编码”首先应该检查这两个字段的语义是否一致，而不是继续叠加 url.PathEscape。如果你希望保留解析前的精确写法，优先让 url.Parse 负责建立字段关系；如果手动构造，就同时维护解码值和有效的编码提示。

按目标语义选择解析、结构体或分段转义

迁移旧代码时，我会先问一个问题：路径里的斜杠是目录分隔符，还是某个业务 ID 的内容？两种答案对应不同写法。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	segment := "a/b"
	// PathEscape 面向单个路径段，会把段内斜杠编码为 %2F。
	escapedSegment := url.PathEscape(segment)
	u := &url.URL{
		Scheme: "https",
		Host:   "example.com",
		// 这里的 Path 是路由骨架，段内数据已经单独转义。
		Path: "/docs/" + segment,
		RawPath: "/docs/" + escapedSegment,
	}
	fmt.Println(u.String())
}

如果只是普通目录层级，直接使用解码后的 Path: "/docs/a/b" 更清楚；只有当你需要区分“目录分隔符”和“数据中的斜杠”时，才需要保留匹配的 RawPath。不要把已经含有百分号编码的完整 URL 再当成 Path 重新处理，否则很容易得到 %25 这样的双重编码结果。

用 EscapedPath 和 RequestURI 做回归检查

排障时建议同时打印三个层次：Path 看语义值，RawPath 看是否有提示，EscapedPath 或 RequestURI 看最终要放到请求里的编码形式。这样能区分“字段没有保存”和“字段保存了但被判定无效”。

func describe(u *url.URL) string {
	// RequestURI 代表 HTTP 请求使用的编码路径和查询部分。
	return fmt.Sprintf(
		"path=%q raw=%q escaped=%q request=%q",
		u.Path,
		u.RawPath,
		u.EscapedPath(),
		u.RequestURI(),
	)
}

如果 RawPath 不为空但 EscapedPath() 没有采用它，回到上一节检查“RawPath 解码后是否等于 Path”。如果 Path 本身出现了 %2F 或 %20，优先修正字段来源，而不是在输出阶段再套一层转义。

迁移清单与常见边界

• 把 Path 当作解码后的路径语义，不把它当作完整的已编码 URL 片段。
• 把 RawPath 当作可选提示；它必须是 Path 的有效编码，否则会被忽略。
• 面向阅读和发送时优先使用 EscapedPath() 或 RequestURI()。
• 路径编码和查询编码分开处理；查询参数使用 url.Values，不要用 PathEscape 代替查询编码。
• 回归用例至少覆盖普通斜杠、数据斜杠、空格、百分号和无效 RawPath 五种边界。

相关问题

为什么直接设置 Path 后输出出现 %252F？ 通常是因为 Path 中已经放入了 %2F，百分号又被当成普通字符编码了一次。

RawPath 为空是不是错误？ 不是。普通路径不需要保留特殊编码差异时，RawPath 为空很正常，EscapedPath 会根据 Path 计算结果。

什么时候应该调用 PathEscape？ 当你要编码一个独立路径段，且该段内容可能包含斜杠等特殊字符时使用；不要把完整路径无差别地重复转义。