net/url OmitHost URL 的序列化边界

Go 的 net/url 里，URL.OmitHost 解决的是一个很具体的构造问题：URL 有 scheme 和 path，但不想在 scheme 后面输出空的 authority。把它设为 true 后，URL.String() 会在 host 为空且 user 为空时省略 // 以及空 host；它不是“把 URL 变成相对路径”，也不是 Opaque 的别名。

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

需要表达“有 scheme、没有 authority、仍按层级 path 组织”的 URL 时使用 OmitHost。如果数据本来就是 scheme:opaque 形式，应使用 Opaque；如果调用方要把结果交给只接受 HTTP 请求目标的接口，还要另外考虑 RequestURI() 的语义。

接口目标：省略空 authority，不改变路径模型

url.URL 同时承载 scheme、authority、path、query 和 fragment。常见的层级 URL 形态是 scheme://host/path，而 OmitHost 允许调用方明确告诉 String()：本次层级 URL 没有 host，不要为了 scheme 自动补出 //。

例如，字段组合为 Scheme="https"、Path="/docs"、OmitHost=true 时，序列化结果是 https:/docs。这里仍然有 scheme 和层级 path，只是 authority 被省略了。RawQuery 和 fragment 仍按普通规则拼接，例如会继续出现在 ? 和 # 之后。

这与把 Scheme 清空不是一回事。清空 scheme 后得到的是相对引用；保留 scheme 并设置 OmitHost，表达的是另一种字段契约。

调用方需求：三个相似写法其实对应三种 URL

判断时先问数据模型属于哪一类，而不是先试几个字符串拼接方式。Opaque 非空时，String() 走 scheme:opaque 形式，path、host 等字段不会按普通层级路径一起输出。OmitHost 则只影响空 host 的 authority 部分，path 仍由 EscapedPath() 参与构造。

参数设计：OmitHost、Host 和 User 需要一起看

最容易被忽略的是，OmitHost 的省略条件不只看 Host。Go 的序列化逻辑会在 OmitHost=true、Host 为空且 User 为 nil 时省略空 authority。如果仍然设置了 userinfo，调用方就不能把它当成“完全没有 authority”的 URL。

同理，OmitHost 不会把非空的 Host 隐藏掉。下面这组决策可以作为接口设计时的速查：

• 需要 https://example.com/：保持 Host 非空，不设置 OmitHost。
• 需要 https:/docs：保持 Host 为空、User 为 nil，设置 OmitHost=true。
• 需要 custom:payload：使用 Opaque，不要把 payload 塞进 Path 后期待同样结果。
• 需要保留 path 中非默认的百分号编码：让 RawPath 与 Path 保持一致，并通过 EscapedPath() 读取编码结果。

错误处理：双斜杠路径必须防止重新解析成 Host

无 authority 的层级 URL 有一个重要边界：如果 path 本身以 // 开头，直接输出会让下游解析器有机会把第二部分误认为 host。Go 的 String() 对这种组合做了保护：在 OmitHost=true、host 和 user 为空时，会把 path 的第一个斜杠编码成 %2F，从而保持“这是一条 path”的意图。

因此，不要为了“看起来更短”自行拼接 scheme: 与 path，也不要对 String() 的结果做第二轮通用替换。字段组合和标准库的序列化规则共同构成了契约；改写结果可能破坏下一次 url.Parse 的字段边界。

最小示例：把字段语义交给 URL.String

下面的示例只展示构造与序列化，不把输出冒充成本机运行截图。代码用三个 URL 变量把层级、OmitHost 和 opaque 三种意图放在同一处，便于接口评审时比较。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 带 Host 的层级 URL：authority 会按 //host 的形式输出。
	withHost := url.URL{Scheme: "https", Host: "example.com", Path: "/docs"}

	// 空 Host 的层级 URL：OmitHost 让 String 省略空 authority。
	withoutHost := url.URL{Scheme: "https", OmitHost: true, Path: "/docs"}

	// Opaque URL：scheme 后直接拼接 Opaque，不走层级 Path 规则。
	opaque := url.URL{Scheme: "mailto", Opaque: "user@example.com"}

	// 统一通过 String 获取序列化结果，避免手写 scheme、斜杠和查询拼接。
	fmt.Println(withHost.String())
	fmt.Println(withoutHost.String())
	fmt.Println(opaque.String())
}

这段代码对应的形态分别是 https://example.com/docs、https:/docs 和 mailto:user@example.com。真正接入业务时，若 URL 来自用户输入或配置文件，先按业务协议决定允许哪些字段，再把 String() 结果交给下游；不要仅凭字符串里有没有 // 判断是否存在 host。

兼容策略：构造 API 要把 URL 形态写进契约

如果一个函数返回 *url.URL，建议在函数注释或类型约定中明确三件事：是否允许空 host、返回的是层级 URL 还是 opaque URL、调用方是否会再次解析字符串。这样调用方不会把 OmitHost 当成格式化开关，也不会在序列化后再用字符串替换补斜杠。

如果下游只接受常见的 HTTP 请求目标，先确认它需要的是完整 URL、RequestURI() 还是 path-query；URL.String() 的表达能力更宽，不等于每个下游协议都接受所有形式。对于需要跨语言传输的字段，最好在协议文档里写出示例字符串和重新解析后的字段期望。

相关问题

OmitHost=true 会让 URL 变成相对 URL 吗？

不会。只要 Scheme 非空，URL.IsAbs() 仍按非空 scheme 判断为绝对 URL；OmitHost 只描述空 authority 的序列化方式。

OmitHost 能隐藏已经设置的 Host 吗？

不能。它针对的是空 host 的省略条件；如果 Host 非空，调用方应按带 authority 的 URL 处理。

为什么不用 Opaque 代替 OmitHost？

Opaque 表示 scheme:opaque，不会把内容当成层级 path。需要保留 path、query 和 fragment 的层级语义时，应使用普通字段组合和 OmitHost。

读取 RawPath 还是调用 EscapedPath？

通常调用 EscapedPath()。官方文档把 RawPath 定义为可选的编码提示，并建议通过方法获取最终可用的转义路径。