Go url.URL Opaque 适合表示哪类非层级地址

处理 URI 时，最容易误判的是把 url.URL 的 Opaque 当成普通路径的另一种写法。它真正表示的是 scheme:opaque 形式：scheme 后没有以斜杠开始的层级路径，后面的内容整体作为不透明数据保存。mailto:dev@example.com、urn:isbn:9787300000000、data:text/plain,hello 都属于这类场景；https://example.com/docs 则应使用 Host 和 Path。

scheme:opaque 和层级 URL 不是同一条路径

Go 官方 net/url 文档把 URL 概括为两种输出形态：scheme:opaque?query#fragment 和 scheme://userinfo@host/path?query#fragment。解析时，scheme 后的内容如果不是以 / 开头，就会进入 Opaque；如果是 // 或路径斜杠，则进入 Host、Path 等字段。

用 Parse 读取 Opaque、查询串和片段

读取时不要只检查 Host 是否为空。对于 mailto: 这类地址，应该同时查看 Scheme 和 Opaque；查询串仍由 RawQuery 保存，片段则进入 Fragment。

package main

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

func main() {
    // 非层级 URI 不提供 Host/Path，核心数据位于 Opaque。
    u, err := url.Parse("mailto:dev@example.com?subject=Go#contact")
    if err != nil {
        log.Fatal(err) // 解析失败时停止，避免继续使用空指针。
    }

    fmt.Println("scheme:", u.Scheme)
    fmt.Println("opaque:", u.Opaque)
    fmt.Println("host:", u.Host)
    fmt.Println("path:", u.Path)
    fmt.Println("query:", u.RawQuery)
    fmt.Println("fragment:", u.Fragment)
    fmt.Println("round trip:", u.String())
}

这里的 Opaque 是 dev@example.com，而 subject=Go 仍是查询串。若业务只允许一个明确的 scheme，可以在解析后检查 u.Scheme，再决定是否接受这类地址；不要把“Host 为空”直接当作非法。

直接构造 Opaque URI 时保持数据整体性

已知 scheme 和不透明数据时，可以直接初始化 url.URL。这种写法适合生成协议标识符或邮件地址，不适合把路径片段塞进 Opaque 后再期待 ResolveReference、JoinPath 等层级操作正常工作。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    values := []url.URL{
        {Scheme: "mailto", Opaque: "ops@example.com"},
        {Scheme: "urn", Opaque: "isbn:9787300000000"},
        {Scheme: "data", Opaque: "text/plain,hello"},
    }

    for _, u := range values {
        // String 会选择 scheme:opaque 形式，而不是拼出 //host/path。
        fmt.Println(u.String())
    }
}

如果 Opaque 中包含需要编码的内容，先明确该协议的编码规则，再把已经符合规则的 opaque 数据交给 URL。Opaque 不是通用的路径转义入口，也不会自动替你拆分层级字段。

什么时候不该使用 Opaque

只要业务需要按域名路由、拼接目录、替换路径、设置认证信息或使用 HTTP 客户端发起请求，就应该使用层级 URL。例如 API 地址应写成 https://api.example.com/v1/items，而不是把 api.example.com/v1/items 填进 Opaque。后者虽然可能被解析为合法的 URI 结构，但它表达的不是带主机的 HTTP 地址。

可以用下面的清单快速判断：

• 是邮件、URN、data 等协议，scheme 后数据不需要拆成 host/path：考虑 Opaque。
• 要按域名和目录处理，或要交给 HTTP 请求：使用 Host、Path 和 RawQuery。
• 解析结果 Host/Path 为空：先看 Scheme、Opaque 和协议语义，再决定是否报错。

常见问题

Opaque 非空时还能设置 RawQuery 吗？

可以。输出会采用 scheme:opaque?query 形式；但查询参数是否被该具体协议定义，仍由协议本身决定。

为什么 http:example.com/path 看起来不像普通 HTTP 地址？

因为 scheme 后没有斜杠，Go 会把它按 rootless opaque 数据解析。普通 HTTP 地址应使用带 // 的层级形式。

能用 Opaque 代替 PathEscape 吗？

不能。PathEscape 服务于层级 URL 的路径段，Opaque 则表达另一种 URI 结构，两者解决的问题不同。