Go net/url URL Opaque 非空时 Path 为什么不参与请求

url.URL.Opaque 非空时，URL 使用不透明表示；它不是 Path 的前缀，也不会与 Path 自动合并。此时修改 Path，通常不会改变 String() 或 RequestURI() 采用的主体。普通 HTTP 接口地址应优先使用 Scheme、Host、Path 等层级字段，不要同时维护另一份 Opaque。

官方文档入口：https://pkg.go.dev/net/url@go1.27.3。下面示例只解释 URL 对象和请求目标的构造，没有发送网络请求，也没有在本地执行代码。

为什么改了 Path 却看不到变化

可以把 URL 的主体表示分为两类：层级表示使用 Host 与路径字段；不透明表示使用 Opaque。它们不是两段等待拼接的字符串。排查时先看 Opaque 是否为空，再看 Path，而不是反复修改 Path 的斜杠。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    u := url.URL{
        Scheme: "https",
        Host: "api.example",
        Opaque: "/legacy",
        Path: "/v2/items",
        RawQuery: "limit=3",
    }
    // 同时保留两种表示是本例的反例；先观察实际选用的主体。
    fmt.Println(u.String())
    fmt.Println(u.RequestURI())

    // 仅在确定目标是普通层级 URL 后，移除不透明表示。
    u.Opaque = ""
    fmt.Println(u.String())
    fmt.Println(u.RequestURI())
}

按字段规则推导，清空前 String 的主体来自 https:/legacy，请求目标来自 /legacy；查询部分仍追加 ?limit=3。清空后，Host 与 /v2/items 参与层级表示。这是规则推导，不是本文取得的运行输出。

关键不在于 Path 有没有值，而在于当前序列化选择了哪种表示。Opaque 非空也不会让原来的 Path 字段从内存消失，查看结构体时仍能看到它，这正是容易误判的地方。

普通 HTTP 地址用层级字段构造

对于“解析一个普通地址，再替换路径”的函数，最简单的策略是明确拒绝 Opaque 输入。这样调用方不会以为自己完成了普通路径替换，实际上却保留了另一份请求目标。

package endpoint

import (
    "fmt"
    "net/url"
)

func ReplacePath(raw, nextPath string) (string, error) {
    u, err := url.Parse(raw)
    if err != nil {
        return "", fmt.Errorf("parse endpoint: %w", err)
    }
    // 本函数只接受普通绝对 HTTP 地址，不猜测不透明内容如何转换。
    if u.Opaque != "" || u.Host == "" ||
        (u.Scheme != "http" && u.Scheme != "https") {
        return "", fmt.Errorf("endpoint must be a hierarchical HTTP URL")
    }
    if nextPath != "" && nextPath[0] != '/' {
        return "", fmt.Errorf("path must start with slash")
    }
    // nextPath 是未转义路径；丢弃旧路径的转义提示。
    u.Path = nextPath
    u.RawPath = ""
    return u.String(), nil
}

这个函数保留原查询参数和片段，只替换路径；如果业务需要同时清除它们，应另外设置 RawQuery、ForceQuery、Fragment 和 RawFragment。它不是任意外部 URL 的安全访问策略，不负责决定目标主机是否允许访问。

若已有对象确实需要从不透明表示转成层级表示，应显式给出 Scheme、Host 和目标 Path，再清空 Opaque；不能假定清空后会从旧 Opaque 自动提取主机与路径。对不透明地址做语义转换属于调用方自己的业务决定。

Path、RawPath 和查询参数分别放什么

修改 Path 后将 RawPath 清空，是普通路径替换中减少残留状态的写法。若必须保留特殊编码形式，需要让 RawPath 成为 Path 的有效转义表示，不能把二者当成互不相关的路径。

// 查询参数单独编码，不把问号和参数值塞进 Path。
u := url.URL{Scheme: "https", Host: "api.example", Path: "/v2/items"}
q := url.Values{}
q.Set("label", "blue sky")
u.RawQuery = q.Encode()
// String 负责组合层级 URL，这里没有发起请求。
address := u.String()
_ = address

此处示例片段需要在已导入 net/url 的函数内使用。不要先对整个路径反复转义再放进 Path，否则百分号本身可能被再次转义。遇到空格、中文、百分号或编码后的斜杠时，分别检查解码路径与转义路径，比观察完整 URL 字符串更容易发现字段混用。

请求目标不等于完整 URL

String() 用于完整 URL 表示；URL.RequestURI() 主要给出请求目标形式，不是另一个 String。普通情况下它来自转义路径与查询，而不包含 Fragment。Opaque 非空时则使用不透明主体；若它以双斜杠开头，RequestURI 还有补入 Scheme 的特殊处理，不能笼统理解为“永远原样返回 Opaque”。

net/http 的 HTTP/1 请求写出逻辑会使用 URL.RequestURI，并对代理与 CONNECT 等情况作额外处理。因此不能只凭 URL.String 推断所有传输场景的线级请求形式。请求目标、URL.Host 和 HTTP Host 是相关但不同的概念：改了请求目标也不能据此推断连接地址已经改变。

另一个容易混淆的名称是 http.Request.RequestURI 字段。它与 url.URL.RequestURI() 方法不是同一个东西，不应为了修正普通客户端路径而手动给前者填完整 URL。常规客户端构造仍应围绕 Request.URL 与正常的请求构造 API 进行。

相关问题

清空 Opaque 就一定能请求成功吗？不能。它只改变主体表示的选择；Scheme、Host、路径、查询和传输配置仍必须符合实际业务。若旧对象只有 Opaque 内容而没有 Host，清空后不会凭空恢复地址。

只改 RawPath 可以绕过 Opaque 吗？不能。RawPath 服务于层级路径的转义表示，不能代替选择主体表示。先确定 Opaque 是否应存在，再处理编码细节。

复制一个 URL 再改字段可以吗？对本文的字符串字段，可以先复制对象再改副本，避免直接改动共享对象；但不要把浅拷贝当作任意可变引用的深拷贝，也不要并发修改同一个 URL 对象。

代理代码有意设置了 Opaque 怎么办？先确认它是否承担特定请求目标的构造契约。不要把所有 Opaque 一律清空。本文的普通 HTTP 路径替换函数选择拒绝这类输入，正是为了不悄悄改变特殊调用方的语义。

参考：net/url 官方文档；URL 表示与请求目标实现；HTTP 请求写出实现。