net/url RawPath 保留转义斜杠的序列化边界

在 Go 的 net/url 中，Path 和 RawPath 不是两个可以随意互换的路径字段。Path 保存解码后的路径，RawPath 只是一个可选的编码提示；只有这个提示本身有效，并且解码后确实等于 Path，EscapedPath() 才会保留它。也就是说，想让路径中的转义斜杠 %2F 在序列化时继续存在，关键不是只给 RawPath 赋值，而是让两个字段表达同一个路径。

处理带转义斜杠的 URL 时，业务判断通常读取 Path，需要保留原始转义形式时读取 EscapedPath()；String() 和 RequestURI() 也会沿用这套规则。

路径字段为什么不能只保留一个值

URL 中的 /a/b 和 /a%2Fb 在传输文本上不同，但解码后都可能包含相同的字符。Go 如果只把解码结果放进 Path，后续就无法判断某个斜杠原本是路径分隔符，还是由 %2F 解码而来。因此 URL 还提供了 RawPath 作为编码提示。

这个设计把两个需求分开：路由、分段和业务判断可以使用更易处理的解码值；签名、代理转发或需要保持原始编码的场景，则可以使用转义后的路径。RawPath 不是第二个独立的事实来源，它必须与 Path 保持一致。

url.Parse 会怎样处理 %2F

下面的示例使用一个路径片段 a%2Fb。代码只展示字段关系，不把 Path 当作原始请求文本：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// %2F 解码后是斜杠，但这里仍希望观察原始编码提示。
	u, err := url.Parse("https://api.example.test/team/a%2Fb")
	if err != nil {
		// 解析失败时不要继续使用不完整的 URL 对象。
		panic(err)
	}

	fmt.Println("Path:", u.Path)
	fmt.Println("RawPath:", u.RawPath)
	fmt.Println("EscapedPath:", u.EscapedPath())
	fmt.Println("String:", u.String())
	fmt.Println("RequestURI:", u.RequestURI())
}

这里的关键区别是：

• Path 是 /team/a/b，因为它是解码后的值。
• RawPath 可以保留 /team/a%2Fb 这一编码提示。
• EscapedPath() 在提示有效时返回带 %2F 的形式。
• String() 和 RequestURI() 通过 EscapedPath() 组织输出，而不是直接读取 RawPath。

RawPath 被保留需要满足两个条件

EscapedPath() 的判断可以概括为“编码合法”和“解码后相等”。如果 RawPath 含有非法百分号编码，或者它解码出的内容与 Path 不同，Go 就会忽略这个提示，重新根据 Path 计算一个可用的转义路径。

因此，下面的手动构造是可靠的：Path 放解码值，RawPath 放与之对应的编码值。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	u := &url.URL{
		Scheme: "https",
		Host:   "api.example.test",
		// Path 保存解码后的语义路径。
		Path: "/team/a/b",
		// RawPath 必须解码回同一个 Path，%2F 才能被保留。
		RawPath: "/team/a%2Fb",
	}

	fmt.Println(u.EscapedPath())
	fmt.Println(u.String())
}

如果把 RawPath 改成 /team/a%2Fc，它解码后就不再等于 Path。此时继续调用 EscapedPath()，结果不会盲目相信错误提示，而是从 Path 重新转义。

PathEscape 不能替代 RawPath 配对

一个常见误区是把已经编码的路径再次交给 PathEscape，然后直接塞进 Path。Path 的语义是解码后的路径，直接放入 %2F 可能导致百分号再次被编码，最终得到的文本与预期不一致。

如果输入是一个完整的路径片段，先明确它是“原始编码文本”还是“普通语义字符串”。普通字符串要放进单个路径段时，可以使用 PathEscape；需要保留一个已经确认的完整编码路径时，则应让 Path 和 RawPath 成对表达同一内容。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	segment := "a/b"
	// PathEscape 把斜杠当作段内字符处理，适合单个路径段。
	escapedSegment := url.PathEscape(segment)
	fmt.Println(escapedSegment) // a%2Fb

	u := &url.URL{
		Scheme: "https",
		Host:   "api.example.test",
		// URL 的 Path 是解码语义，RawPath 是对应的编码提示。
		Path:    "/team/" + segment,
		RawPath: "/team/" + escapedSegment,
	}
	fmt.Println(u.EscapedPath())
}

是否应该保留 %2F，取决于下游协议把它看作“段内字符”还是“路径分隔符”。Go 只能保证字段和序列化规则一致，不会替业务决定路由语义。

String、RequestURI 和业务读取该怎么选

如果代码要做路由匹配、资源查找或路径分段，优先使用 Path，因为这些操作通常关心解码后的字符。需要生成请求目标时使用 RequestURI()；需要重新组装完整 URL 时使用 String()。二者都会走 EscapedPath()，所以有效的 RawPath 会参与输出。

对于签名、缓存键或代理转发，不能只凭字段名猜测下游规则。应先确定签名方约定的是规范化路径、原始转义路径，还是再次编码后的路径，然后统一在同一字段上计算和发送。直接读取 RawPath 会绕过它的有效性语义，官方接口更推荐 EscapedPath()。

兼容这类路径时记住四条规则

1. 不要把 Path 当作原始请求字符串；它保存的是解码形式。
2. 不要把 RawPath 当成无条件生效的覆盖字段；它只是可选编码提示。
3. 手动构造时让 RawPath 解码后等于 Path，否则提示会被忽略。
4. 序列化优先调用 EscapedPath、String 或 RequestURI，不要自己拼接百分号编码。

这条边界的价值在于：业务层可以稳定使用解码后的路径，协议层又能在确有需要时保留原始的转义斜杠。只要先定义下游对斜杠的语义，再按成对字段构造 URL，重复转义和路径分段误判就会少很多。

相关问题

RawPath 为空是不是丢失了路径信息？

不一定。若默认转义形式已经足以表达 Path，RawPath 可以为空；这时 EscapedPath() 会根据 Path 计算输出。

为什么修改 Path 后原来的 RawPath 不再可信？

因为 RawPath 只对它解码后等于当前 Path 的情况有效。修改 Path 后如果没有同步调整 RawPath，序列化时就会回退到根据新 Path 重新转义。

读取 RawPath 能不能判断请求原文？

只能把它当作 URL 对象保留的编码提示，不能把它当作脱离解析过程的原文证明。需要稳定的转义输出时，应使用 EscapedPath()。