Go url.URL RawFragment 怎样保留片段中的百分号编码

Go 的 url.URL 会把 URL 片段拆成“语义值”和“原始编码提示”两个层面：Fragment 方便业务读取，RawFragment 记录可选的原始编码形式。需要保留片段中的百分号编码时，不要直接把 Fragment 拼回字符串，而应让 EscapedFragment() 或 String() 根据有效的编码提示完成输出。

官方地址：https://pkg.go.dev/net/url#URL

最稳妥的原则是：业务判断读取 Fragment，需要还原 URL 表示时调用 EscapedFragment() 或 String()；RawFragment 是可选提示，不是应该被业务代码直接依赖的最终输出接口。

模式命名：两个域的边界

解析一个带片段的 URL 后，Fragment 和 RawFragment 并不是两个互相独立的业务字段。前者面向解码后的语义，后者只是为了在重新输出时尽量保留原始编码形式的提示。比如片段中的 %2F 可能在 Fragment 中表现为斜杠，但原始 URL 仍然希望保留这段编码写法。

可以把它看成两个边界：业务层只关心“片段代表什么”，表示层关心“片段当初怎样编码”。这也是为什么官方文档建议优先调用 EscapedFragment()，而不是直接读取 RawFragment。

适用压力：重新输出时要保留百分号编码

当程序只判断片段内容时，读取 Fragment 就够了；当程序需要把 URL 写回日志、缓存键、重定向位置或下游请求时，编码形式也可能成为可观察结果。此时应先解析，再使用 EscapedFragment() 查看适合输出的片段。

package main

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

func main() {
	// 片段中的 %2F 表示编码后的斜杠，解析后仍要保留原始表示的线索。
	u, err := url.Parse("https://example.com/docs#x/y%2Fz")
	if err != nil {
		// 输入 URL 不可解析时直接结束，避免继续使用半成品结构。
		log.Fatal(err)
	}

	// Fragment 适合业务判断，EscapedFragment 适合重新构造 URL 表示。
	fmt.Println("Fragment:", u.Fragment)
	fmt.Println("RawFragment:", u.RawFragment)
	fmt.Println("EscapedFragment:", u.EscapedFragment())
	fmt.Println("URL:", u.String())
}

这个例子里，Fragment 更适合做“是否包含某个逻辑片段”的判断；EscapedFragment() 则会在 RawFragment 对应当前 Fragment 且编码有效时优先保留它，否则计算一个新的合法表示。最终 String() 也会使用这个方法来拼出 URL。

典型实现：只修改语义值，再让 URL 负责编码

如果业务确实要修改片段，建议修改 Fragment，不要把新的百分号串直接塞进 RawFragment。这样可以让 EscapedFragment() 判断原始提示是否仍然有效，并在提示失效时重新计算编码。

func updateFragment(rawURL, suffix string) (string, error) {
	// 先得到 URL 的语义字段，避免把百分号编码当普通业务文本拼接。
	u, err := url.Parse(rawURL)
	if err != nil {
		return "", err
	}

	// 修改 Fragment 后，旧 RawFragment 可能不再匹配；由 String 重新组织输出。
	u.Fragment = u.Fragment + suffix
	return u.String(), nil
}

这里的重点不是“手工把 suffix 做百分号编码”，而是保持字段职责清晰：Fragment 表示语义，String() 负责把当前结构重新编码。若后缀来自用户输入，还应在业务层先确认它的语义边界，不能把一段完整 URL 当成片段追加。

反例定位：直接拼接和直接写 RawFragment 为什么危险

最常见的误区有三个。第一，把 Fragment 直接拼到 # 后面，可能把空格、斜杠或非 ASCII 字符以不适合 URL 的形式输出。第二，把已经编码的文本写进 Fragment，会造成二次编码或语义混淆。第三，修改 Fragment 后仍然保留一个不匹配的 RawFragment，再把这个字段当成可信最终值。

func fragmentForDisplay(u *url.URL) string {
	// 展示或判断业务含义时使用解码后的 Fragment，不把它当成 URL 字面量。
	return u.Fragment
}

func urlForOutput(u *url.URL) string {
	// 重新输出交给 URL.String，避免手工遗漏片段和路径的转义规则。
	return u.String()
}

显示文本和 URL 文本是两种不同的结果。前者适合界面、日志中的语义阅读；后者必须经过 URL 的编码规则。把两个结果混用，通常会在缓存键不一致、路由锚点失效或下游解析差异时暴露。

后果与取舍：语义读取还是原样输出

只需要比较片段内容时，优先使用 Fragment，不要让百分号大小写或等价编码影响业务判断；需要尽量保持输入 URL 的文本形态时，调用 EscapedFragment() 或 String()。两者不是互相替代，而是分别服务于语义域和表示域。

判断清单：解析、读取、修改、输出四个检查点

1. 解析后先确认当前代码需要的是片段语义，还是 URL 的原始表示。
2. 业务判断读取 Fragment，不要用 RawFragment 做等价性比较。
3. 修改片段只改 Fragment，让 String() 重新计算需要的编码。
4. 重新构造 URL 时调用 EscapedFragment() 或 String()，不要手工拼接 # 后的文本。
5. 如果代码必须依赖原始编码形式，就把这个约束写进接口说明，并同时保留对无效 RawFragment 的处理。

相关问题

Fragment 和 RawFragment 是同一个值吗？

不是。Fragment 是解码后的语义值，RawFragment 是可选的编码提示；只有提示能有效表达当前片段时，输出方法才会采用它。

为什么不建议直接读 RawFragment？

因为它可能为空，也可能已经与当前 Fragment 不匹配。直接使用会让调用方绕过 URL 包提供的有效性判断。

修改 Fragment 后需要手工清空 RawFragment 吗？

一般不需要把清理逻辑扩散到调用方；由 EscapedFragment() 判断旧提示是否有效。若代码明确维护了自定义结构，也可以在修改语义值时同步清除旧提示，但最终仍应通过 URL 方法输出。

参考：Go net/url.URL 官方文档。