Go url.URL EscapedFragment 保留片段编码的输出方式

需要在 Go 中保留 URL 片段原有的转义形式时，应该使用 u.EscapedFragment() 或直接使用 u.String()，而不是读取 u.RawFragment。Fragment 保存解码后的语义，RawFragment 只是可选的原始编码提示；EscapedFragment 会验证两者是否一致，再决定保留提示还是重新编码。

规模背景：批量改写链接时为什么会丢表示

我第一次注意到这个细节，是在批量改写文档锚点时：输入是 https://example.com/docs#x/y%2Fz，解析后业务只修改了主机名，输出却需要继续保留片段里的 %2F。从语义上看，x/y%2Fz 与解码后的 x/y/z 可以指向同一串字符；但对需要稳定快照、差异比较或原样转发的系统来说，表示形式也可能是合同的一部分。

小工具里重新规范化通常无所谓。到了链接迁移、站点地图生成、签名输入或海量文档重写场景，混用“解码语义”和“编码表示”会导致大量无意义差异，甚至出现百分号被再次转义的问题。

三字段模型：语义、提示和安全输出

url.URL 对片段采用两层表示：

• Fragment：不含 #，保存解码后的片段值，是业务代码应修改的语义字段。
• RawFragment：可选的编码提示，只在原始表示与 Go 的默认转义形式不同且值得保留时出现。
• EscapedFragment()：输出入口。它检查 RawFragment 是否是 Fragment 的合法编码；不匹配就忽略提示并从 Fragment 重新转义。

这个设计的关键是 RawFragment 不拥有独立语义。它不能与 Fragment 各说各话；只有编码合法，而且解码后正好等于 Fragment，才会被采用。URL.String() 在组装最终地址时会调用 EscapedFragment，因此通常不需要手工拼接井号和片段。

原架构瓶颈：直接读字段或手工拼接

下面是两个容易在批量处理中放大的错误。

func badOutput(u *url.URL) string {
	// RawFragment 可能为空，也可能已经与 Fragment 不匹配
	return u.Scheme + "://" + u.Host + u.Path + "#" + u.RawFragment
}

第二种错误是把已经编码的文本塞进 Fragment：

func badAssign(u *url.URL) string {
	// Fragment 需要解码语义；直接放入 %2F 会把百分号当普通字符
	u.Fragment = "x/y%2Fz"
	return u.String()
}

因为 Fragment 中的百分号属于实际字符，输出时它可能被编码为 %25，于是原本期望的 %2F 变成 %252F。这不是 Go 重复编码了 URL，而是输入字段的层次错了。

新架构：解析保留、语义修改、统一输出

一个稳定的链接处理管道可以分三层：入口用 url.Parse 建立解码语义和原始提示；中间层只修改语义字段；出口统一调用 URL.String。只有确实要求固定某种片段编码表示时，才手工维护 RawFragment。

func rewriteHost(raw, newHost string) (string, error) {
	u, err := url.Parse(raw)
	if err != nil {
		return "", fmt.Errorf("parse URL: %w", err)
	}

	// 只修改主机，不触碰片段语义和解析得到的编码提示
	u.Host = newHost

	// String 内部使用 EscapedFragment，能保留有效的原始片段编码
	return u.String(), nil
}

对于输入 https://old.example/docs#x/y%2Fz，解析结果中的 Fragment 是 x/y/z，RawFragment 是 x/y%2Fz，EscapedFragment 返回 x/y%2Fz。只改 Host 后调用 String，输出仍能保留该片段表示。

关键取舍一：修改片段后让 Go 重新规范化

当业务真的修改了片段语义，最安全的做法是更新 Fragment，并清空 RawFragment。即使遗留的 RawFragment 与新 Fragment 不一致时 EscapedFragment 会自动忽略它，主动清空仍能让对象状态更容易理解。

func replaceFragment(u *url.URL, fragment string) string {
	// Fragment 保存解码后的业务值，不包含井号
	u.Fragment = fragment

	// 旧编码提示属于旧语义，清空后由 Go 重新计算转义形式
	u.RawFragment = ""

	return u.String()
}

这种方案会得到 Go 选择的规范输出，不保证保留输入中的十六进制大小写或“某个可转义字符究竟是否转义”等表面差异。对一般链接生成器来说，这通常正是更低维护成本的选择。

关键取舍二：确需固定表示时同时设置两字段

如果下游合同明确要求斜杠以 %2F 出现在片段中，可以同时设置解码语义与编码提示。两者必须对应，否则 EscapedFragment 会丢弃提示。

func buildPreservedFragment() string {
	u := &url.URL{
		Scheme:      "https",
		Host:        "example.com",
		Path:        "/docs",
		Fragment:    "x/y/z",    // 解码后的真实语义
		RawFragment: "x/y%2Fz",  // 同一语义的指定编码表示
	}

	// EscapedFragment 验证提示后，String 才会采用它
	return u.String()
}

不要为了“强制输出任意文本”只改 RawFragment。它是提示，不是绕过编码规则的开关。无效百分号、不能按片段规则解码的字符串，或者解码后与 Fragment 不相等的提示都会被忽略。

上线结果：统一出口减少无意义差异

把所有输出收口到 URL.String 后，处理规则会变得可预测：

在大批量链接任务里，还应先决定去重键比较的是“片段语义”还是“原始字符串”。如果比较语义，应使用 Fragment；如果业务合同要求保留输入字节表现，则应保留完整原始 URL 或经过验证的 EscapedFragment，不能混用两种口径。

用表格测试固定边界

测试重点不是只看一个示例，而是覆盖“有效提示被采用、失配提示被回退、编码文本误放 Fragment”三类差异。

func TestEscapedFragment(t *testing.T) {
	tests := []struct {
		name string
		u    url.URL
		want string
	}{
		{
			name: "采用一致的原始编码提示",
			u: url.URL{Fragment: "x/y/z", RawFragment: "x/y%2Fz"},
			want: "x/y%2Fz",
		},
		{
			name: "失配提示回退到 Fragment",
			u: url.URL{Fragment: "new section", RawFragment: "x/y%2Fz"},
			want: "new%20section",
		},
		{
			name: "编码文本放入 Fragment 会转义百分号",
			u: url.URL{Fragment: "x%2Fy"},
			want: "x%252Fy",
		},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// 直接测试安全输出入口，避免手工读取 RawFragment
			if got := tt.u.EscapedFragment(); got != tt.want {
				t.Fatalf("EscapedFragment()=%q, want %q", got, tt.want)
			}
		})
	}
}

后续改进与边界提醒

• 片段不会随 HTTP 请求发送到服务器；浏览器通常在发请求前就移除 #fragment。服务端路由不要依赖它。
• ParseRequestURI 假设请求 URI 不包含片段，服务端解析请求目标时不要把它当普通完整 URL 解析器使用。
• URL.String 只有在 Fragment 非空时才输出 #fragment；只设置 RawFragment 不能创造独立片段语义。
• 一般业务代码调用 EscapedFragment，不应直接信任 RawFragment。
• 批处理管道应明确“保留原始表示”还是“输出规范形式”，不要在不同模块里临时决定。

最终可以记成一句话：Fragment 是事实，RawFragment 是提示，EscapedFragment 是裁判，URL.String 是统一出口。只要按这个分工处理，既能在需要时保留 %2F 等原始编码，也能在字段失配时安全回退。

参考资料：Go 官方 net/url.URL、EscapedFragment 文档与标准库实现。