Go url.URL 怎样用 Opaque 字段表达不透明请求目标

在 Go 的 net/url 里，URL.Opaque 用来表达 scheme:opaque 形式的非层级数据。只要它非空，URL.String() 就不会按 Host + Path 组装，而是输出 scheme:opaque?query#fragment。因此，Opaque 适合协议本身定义了“不透明请求目标”的场景；普通网站地址仍应使用 Host 和 Path。

官方文档：https://pkg.go.dev/net/url#URL

记住一个判断：需要保留“冒号后面整体是什么”时用 Opaque；需要按主机、路径和查询分别处理时，用 Host、Path、RawQuery。不要把两种表达混在同一个 URL 里。

Opaque 与 Path、Host 的分工

Go 文档把 URL 分成两种常见形态。层级形式是 scheme://host/path?query#fragment，其中 Host 和 Path 都有独立语义；不透明形式是 scheme:opaque?query#fragment，冒号后的 Opaque 由具体协议解释，net/url 不会替你拆分它。

这也是 Opaque 和 RawPath 的关键区别：RawPath 只是 Path 的编码提示，Opaque 则会改变整个 String 的组装分支。构造时应只选择一条表达路线：

用 URL 结构体构造不透明目标

Opaque 字段保存的是已经适合放在 URL 中的编码数据。下面的例子把协议名、冒号后的目标、查询和片段分开设置，便于观察每个字段的责任：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    u := &url.URL{
        Scheme:   "proto",
        Opaque:   "tenant%2F42/resource",
        RawQuery: "mode=compact",
        Fragment: "details",
    }

    // Opaque 已经是编码后的不透明数据，不要再当 Path 重复拼接。
    fmt.Println(u.String())
    // HTTP 请求目标只保留请求行需要的 opaque 和 query。
    fmt.Println(u.RequestURI())
}

输出形态应分别理解为完整 URI 和请求目标：proto:tenant%2F42/resource?mode=compact#details 与 tenant%2F42/resource?mode=compact。片段只供客户端定位文档位置，不会成为 HTTP 请求目标的一部分。

String 与 RequestURI 的输出边界

String() 负责把结构重新组装成 URI，所以会保留 Scheme、Opaque、RawQuery 和 Fragment。RequestURI() 的语义更窄：它返回可用于 HTTP 请求的 opaque?query 或 path?query，不包含 #fragment。

调试时不要只打印 String() 就认为请求行一定正确。可以同时打印字段和 RequestURI，检查是否误把查询写进 Opaque，或者把只在客户端使用的 Fragment 当成服务端参数。

func inspect(u *url.URL) {
    // 先看字段，确认当前对象确实采用 Opaque 路线。
    fmt.Printf("scheme=%q opaque=%q host=%q path=%q query=%q fragment=%q\n",
        u.Scheme, u.Opaque, u.Host, u.Path, u.RawQuery, u.Fragment)
    // RequestURI 用于检查请求目标，不代表完整的 URI 字符串。
    fmt.Println("request-target:", u.RequestURI())
}

与 Path 混用时的处理边界

当 Opaque 非空时，String() 优先使用不透明形式；这不是“Path 再加一个特殊前缀”，而是两套互斥的结构表达。为了避免维护时产生歧义，可以在构造函数中明确拒绝同时设置 Opaque 与 Host、Path：

func opaqueURL(scheme, opaque, query string) (*url.URL, error) {
    if scheme == "" || opaque == "" {
        return nil, fmt.Errorf("scheme 和 opaque 不能为空")
    }
    // 这里固定只生成不透明 URL，避免调用方混入 Host 或 Path。
    return &url.URL{Scheme: scheme, Opaque: opaque, RawQuery: query}, nil
}

还要注意编码责任：Opaque 字段的注释就是“encoded opaque data”。如果协议规定某些字符必须百分号编码，应在进入结构体前按协议完成编码；不要把一个本应按路径分段编码的值直接塞进 Opaque。

常见边界与速查

• 适合：协议将冒号后的内容视为整体标识，调用方不需要让 net/url 理解其中的层级。
• 不适合：需要按域名、端口、路径段路由，或要用 ResolveReference 做层级合并的普通 HTTP 地址。
• 检查：修改 RawQuery 后重新查看 String() 和 RequestURI()，确认查询没有被错误地编码两次。

相关问题

Opaque 和 RawPath 能互相替代吗？不能。RawPath 服务于 Path 的原始转义提示，Opaque 决定 URL 使用非层级的整体表达。

RequestURI 为什么没有 Fragment？因为 Fragment 是客户端拿到资源后使用的片段标识，不属于发送给服务器的请求目标。