Go net/url 中 Opaque URL 怎么读取真实请求目标

Go 的 net/url 遇到 scheme:opaque 形式时，真实主体不在 Path，而在 URL.Opaque。要读取完整地址，用 u.String()；要读取用于 HTTP 请求的目标，用 u.RequestURI()；如果你在服务端要保留客户端原样发来的 request-target，则看 r.RequestURI。

判断口诀：看字段先看 URL 是否带有 //；Opaque URL 读 Opaque，层级 URL 读 Host 和 Path，请求目标与完整 URL 不要混为一谈。

Opaque URL 先看字段边界

URL 常见写法是 scheme://host/path，这是层级 URL；如果 scheme 后面没有斜杠，Go 会按 scheme:opaque 解释。官方文档把 Opaque 定义为编码后的不透明数据，因此不能用读取普通路径的习惯去访问它。

下面的最小示例故意选择一个没有 // 的地址：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    u, err := url.Parse("https:api.example.com/v1/items?from=cache")
    if err != nil {
        // 解析失败时不要继续读取 URL 字段。
        panic(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)
}

这个结果的关键不是某个具体字符串，而是字段归属：Scheme 为 https，主体落在 Opaque，Host 和 Path 不再承担 api.example.com/v1 这一段。普通的 https://api.example.com/v1/items 则应从 Host、Path 读取。

String 和 RequestURI 分别返回什么

URL.String() 的职责是把结构重新组装成 URL。只要 Opaque 非空，它采用 scheme:opaque?query#fragment 这种形式。URL.RequestURI() 的职责更窄：返回可用于 HTTP 请求的编码后路径或 opaque，再附加查询串，不负责返回 fragment。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    u := &url.URL{
        Scheme:   "https",
        Opaque:   "api.example.com/v1/items",
        RawQuery: "from=cache",
        Fragment: "debug",
    }

    // String 用于观察完整 URL 形态，包含 scheme 和 fragment。
    fmt.Println(u.String())
    // RequestURI 用于观察请求目标，只保留 opaque 与 query。
    fmt.Println(u.RequestURI())
}

输出分别类似 https:api.example.com/v1/items?from=cache#debug 和 api.example.com/v1/items?from=cache。因此日志需要展示完整地址时选 String()；准备 request-target 或检查 HTTP 客户端写出的目标时选 RequestURI()。不要为了得到“真实目标”手动给 Opaque 拼一个斜杠，这会改变非层级 URL 的语义。

HTTP 服务端和客户端要分清两个 RequestURI

在服务端，r.RequestURI 是请求行中的未修改 request-target，适合记录客户端实际发来的目标；r.URL 是 Go 根据它解析出的结构，适合按字段处理。两者分别回答“线上收到的原文是什么”和“这段地址解析成了什么”。

在客户端代码里不要给 http.Request.RequestURI 赋值，Go 文档明确说明这是错误用法。应当构造 url.URL，把非层级主体放到 Opaque，再交给 HTTP 客户端处理：

u := &url.URL{
    Scheme: "https",
    Host:   "api.example.com",
    Opaque: "v1/items",
}

req, err := http.NewRequest(http.MethodGet, u.String(), nil)
if err != nil {
    // 请求创建失败时把错误交给上层，不要发送半成品请求。
    return err
}
_ = req

实际项目里先决定协议边界：如果目标就是标准层级 HTTP 地址，直接使用 https://host/path 并读取 Host、Path；只有上游协议明确要求保留 scheme:opaque 形态时，才显式使用 Opaque。这能避免代理、日志和路由代码对同一地址产生两套解释。

常见问题

为什么 Opaque URL 的 Path 是空的？

因为它不是层级路径。没有 // 的 scheme 地址按 scheme:opaque 解析，主体数据进入 Opaque；只有普通层级 URL 才把路径放到 Path。

读取真实请求目标时应该用 String 还是 RequestURI？

要完整 URL 用 String()，要 HTTP request-target 用 URL.RequestURI()；服务端想保留客户端原样发送的 request-target，则用 r.RequestURI。

Opaque 能不能和 Host、Path 一起当作普通 URL 拼接？

不要这样做。Opaque 非空会改变 String() 的组装形式，混用字段容易让地址从非层级结构变成难以预期的结果。先确定一种 URL 形态，再只使用对应字段。

把 Opaque 当作协议边界而不是“另一个 Path”来处理，解析、日志和 HTTP 请求代码就能保持一致：需要结构化路由时选层级 URL，需要保留非层级主体时选 Opaque URL。