Go url.URL ResolveReference 组合相对地址的安全实现

url.URL.ResolveReference 是 Go 里组合相对地址的正确入口：它按 RFC 3986 第 5.2 节处理路径合并、点段消解、查询参数和片段。安全使用时不能只停在“能组合出 URL”，还要把 ref 当作不可信输入，拒绝它替换协议、主机或用户信息，并在组合后重新检查同源和允许路径。

最关键的事实是：ResolveReference 接受的并不只有相对路径。若 ref 是绝对 URL，base 会被忽略；若 ref 以 // 开头，它会保留 base 的 scheme，却替换 host。因此，字符串看起来“不是以 http 开头”并不等于安全。

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

RFC 3986 相对引用解析：https://www.rfc-editor.org/rfc/rfc3986.html#section-5.2

先理解 ResolveReference 的组合模型

假设文档站点的 base 是 https://docs.example.com/guide/start/，不同 ref 会影响不同的 URL 组件：

这也是不应该用 base + ref 或 strings.TrimRight(base, "/") + "/" + ref 的原因。URL 不是普通文件路径字符串，scheme、authority、path、query 和 fragment 各有独立语义，手工拼接很容易把问号、井号、转义和斜杠处理错。

base, err := url.Parse("https://docs.example.com/guide/start/")
if err != nil {
    return err // base 来自配置，也要处理格式错误
}

ref, err := url.Parse("../api/?lang=zh#request")
if err != nil {
    return err // ref 可能来自外部输入，解析失败必须停止
}

result := base.ResolveReference(ref)
fmt.Println(result.String()) // https://docs.example.com/guide/api/?lang=zh#request

base 末尾斜杠决定目录语义

ResolveReference 会把不以斜杠结尾的 base path 当作“最后一段是文件名”。这不是 Go 的特殊规则，而是 URI 相对引用的标准语义。

dirBase, _ := url.Parse("https://example.com/docs/guide/")
fileBase, _ := url.Parse("https://example.com/docs/guide")
ref, _ := url.Parse("intro.html")

fmt.Println(dirBase.ResolveReference(ref))  // https://example.com/docs/guide/intro.html
fmt.Println(fileBase.ResolveReference(ref)) // https://example.com/docs/intro.html

如果配置表示目录，保存时就明确保留末尾斜杠。不要在每次组合前凭感觉补斜杠，因为有些 base 本来就代表具体文档。更稳妥的做法是给配置字段命名为 BaseDirectoryURL 或 DocumentURL，让调用方知道它采用哪种语义。

组合前检查引用字段

只调用 ref.IsAbs() 不够。//evil.example/path 没有 scheme，IsAbs 会返回 false，但它带有 Host，组合后仍会换站。安全策略至少要检查 Scheme、Host、User 和 Opaque。

func parseRelativeReference(raw string) (*url.URL, error) {
    ref, err := url.Parse(raw)
    if err != nil {
        return nil, fmt.Errorf("解析相对引用: %w", err)
    }

    // 同时拒绝绝对 URL、网络路径引用、用户信息和 opaque URL
    if ref.Scheme != "" || ref.Host != "" || ref.User != nil || ref.Opaque != "" {
        return nil, fmt.Errorf("只允许不包含 scheme、host、userinfo 的相对引用")
    }
    return ref, nil
}

这段检查允许 /assets/a.css 这样的绝对路径引用，因为它仍在同一个 origin 内。若业务只允许相对当前目录的路径，还可以额外拒绝 strings.HasPrefix(ref.Path, "/")。是否允许绝对路径是业务规则，不应靠偶然的字符串拼接行为决定。

组合后再次验证同源

输入检查负责尽早拒绝明显越权，结果检查负责把最终 URL 绑定在可信 origin 上。比较 origin 时应拆开 scheme、hostname 和有效端口；不要使用 strings.HasPrefix(result.String(), base.String())，因为 https://example.com.evil.test/ 也可能通过粗糙前缀检查。

func effectivePort(u *url.URL) string {
    if port := u.Port(); port != "" {
        return port // 显式端口优先
    }
    switch strings.ToLower(u.Scheme) {
    case "http":
        return "80"
    case "https":
        return "443"
    default:
        return ""
    }
}

func sameOrigin(a, b *url.URL) bool {
    // 主机名不区分大小写；端口按协议补成有效端口后比较
    return strings.EqualFold(a.Scheme, b.Scheme) &&
        strings.EqualFold(a.Hostname(), b.Hostname()) &&
        effectivePort(a) == effectivePort(b)
}

例如 https://example.com/path 与 https://example.com:443/other 在这个策略下属于同源；http://example.com/、https://example.com:8443/ 则不属于同源。若你的系统对默认端口有不同约定，应把它写进自己的 origin 规则。

把结果限制在允许路径内

同源并不等于同目录。ref 可以用 ../ 离开当前目录，也可以用以斜杠开头的路径直接替换 base path。若应用只允许访问 /guide/ 下的资源，就应在 ResolveReference 完成点段消解后检查最终 Path。

func pathWithinRoot(targetPath, allowedRoot string) bool {
    // 统一成绝对、清理后的 URL 路径，再按完整路径段比较
    root := path.Clean("/" + strings.TrimPrefix(allowedRoot, "/"))
    target := path.Clean("/" + strings.TrimPrefix(targetPath, "/"))
    return target == root || strings.HasPrefix(target, root+"/")
}

func ResolveRelative(baseRaw, refRaw, allowedRoot string) (*url.URL, error) {
    base, err := url.Parse(baseRaw)
    if err != nil {
        return nil, fmt.Errorf("解析 base URL: %w", err)
    }
    // 本辅助函数只接受有主机的 HTTP(S) base，并拒绝内嵌用户信息
    if (base.Scheme != "http" && base.Scheme != "https") || base.Host == "" || base.User != nil {
        return nil, fmt.Errorf("base 必须是无 userinfo 的 HTTP(S) 绝对 URL")
    }

    ref, err := parseRelativeReference(refRaw)
    if err != nil {
        return nil, err
    }

    resolved := base.ResolveReference(ref)
    // 组合后再次锁定 origin，避免策略依赖单一输入检查
    if !sameOrigin(base, resolved) || resolved.User != nil {
        return nil, fmt.Errorf("组合结果离开可信 origin")
    }
    if !pathWithinRoot(resolved.Path, allowedRoot) {
        return nil, fmt.Errorf("组合结果离开允许目录 %s", allowedRoot)
    }
    return resolved, nil
}

这里使用的是 URL 的 Path，不是操作系统文件路径。不要改用 filepath.Clean：URL 路径始终使用斜杠，而 filepath 遵循当前操作系统规则。若下游代理或服务会对编码斜杠 %2F、反斜杠或重复解码采用不同规则，还要在入口层拒绝这些含糊形式，确保每一层对路径的解释一致。

查询参数、片段和 HTTP 跳转怎么处理

相对引用不只有 Path。?page=2 会保留 base 的路径并替换查询参数；#install 会保留路径与查询参数，只替换片段；普通路径 ref 如果没有自己的 RawQuery，则不会保留 base 原有查询参数。是否允许 ref 提供查询参数或片段，也应成为显式策略。

ref, err := parseRelativeReference(rawRef)
if err != nil {
    return nil, err
}
// 资源抓取场景不需要片段，可在组合前明确删除
ref.Fragment = ""
ref.RawFragment = ""

// 若业务不允许外部输入控制查询参数，就直接拒绝而不是悄悄清空
if ref.RawQuery != "" {
    return nil, fmt.Errorf("相对引用不能包含查询参数")
}

还要区分“组合 URL”和“真正发出 HTTP 请求”。即使最终 URL 通过了同源检查，服务器仍可能返回 30x 跳转到其他主机；ResolveReference 不负责限制重定向。用于下载器、爬虫或服务端请求时，还要在 http.Client.CheckRedirect 中对每次跳转后的 URL 重新执行 origin 和目标网络策略。

用表驱动用例固定安全边界

这类辅助函数最容易在“正常路径能用”后被认为已经完成。更重要的是把拒绝条件固定下来，避免以后为了兼容某个输入而无意放开换主机或目录越界。

func TestResolveRelative(t *testing.T) {
    tests := []struct {
        name    string
        ref     string
        want    string
        wantErr bool
    }{
        // 正常相对路径留在允许目录中
        {"child", "images/a.png", "https://docs.example.com/guide/images/a.png", false},
        // 网络路径引用会替换主机，必须拒绝
        {"network path", "//evil.example/a", "", true},
        // 绝对 URL 会忽略 base，必须拒绝
        {"absolute", "https://evil.example/a", "", true},
        // 点段消解后离开 /guide，必须拒绝
        {"escape root", "../../admin", "", true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := ResolveRelative(
                "https://docs.example.com/guide/",
                tt.ref,
                "/guide",
            )
            if (err != nil) != tt.wantErr {
                t.Fatalf("错误状态不符: err=%v", err)
            }
            if err == nil && got.String() != tt.want {
                t.Fatalf("结果不符: got=%s want=%s", got, tt.want)
            }
        })
    }
}

测试里至少应覆盖：base 是否有末尾斜杠、相对路径、绝对路径、../、网络路径引用、绝对 URL、查询参数、片段、显式默认端口和非默认端口。若业务允许的输入规则更窄，就继续把规则写成失败用例。

常见问题

ResolveReference 会修改 base 或 ref 吗？

不会。官方文档说明它总会返回一个新的 URL 实例，即使结果与 base 或 ref 相同。调用方仍应把返回值视为独立对象使用。

只检查 ref.IsAbs() 为什么不够？

因为 //host/path 是没有 scheme 的网络路径引用，IsAbs() 为 false，但组合时会替换 host。安全检查必须同时查看 Host。

为什么不直接用 url.JoinPath？

url.JoinPath 适合把路径元素加入一个 base URL；ResolveReference 处理的是完整 URI 引用语义，包括绝对路径、查询参数和片段。选择哪个 API 取决于输入究竟是“路径元素”还是“URI 引用”，不能混为一谈。

比较 Host 字符串能判断同源吗？

不够稳妥。Host 可能包含端口，主机名大小写也不应影响判断。拆成 scheme、Hostname() 和有效端口比较更清楚。

把解析能力和授权策略分开

ResolveReference 负责按照标准得到正确的目标 URL，但“这个目标是否允许访问”属于应用自己的授权策略。先解析 ref 字段、再组合、最后检查同源与路径范围，才能同时获得标准 URL 语义和明确的安全边界。对于会发起网络请求的程序，还要把同样的策略延伸到重定向和目标网络检查，不能把一次 URL 组合当成完整的请求安全验证。