net/url ResolveReference 怎样把相对 URL 补成绝对地址

在接口返回分页链接、静态资源地址或文档中的相对链接时，最稳妥的做法不是手写字符串拼接，而是先把 base URL 和引用 URL 解析成对象，再调用 net/url.URL.ResolveReference。它会依据一个绝对 base URI 解析相对引用；引用本身已经是绝对 URL 时，则忽略 base，并返回引用的副本。

这篇只讨论 URI 引用解析，不涉及 HTTP 请求发送。先记住一个边界：ResolveReference 解决的是“这个引用相对于哪个地址”，不是“把几个路径字符串拼起来”。

先把 base URL 和相对引用解析成两个对象

url.Parse 可以解析相对或绝对 URL，但 ResolveReference 的接收者应当是绝对 base URI。也就是说，解析没有报错并不代表 base 具备补全相对地址所需的上下文，写包装函数时还要额外检查 base.IsAbs()。

func resolve(baseRaw, refRaw string) (string, error) {
    // 先解析 base，语法错误要和“不是绝对地址”分开处理。
    base, err := url.Parse(baseRaw)
    if err != nil {
        return "", fmt.Errorf("解析 base URL 失败: %w", err)
    }
    // ResolveReference 需要绝对 base，只有路径的字符串不能提供主机和 scheme。
    if !base.IsAbs() {
        return "", fmt.Errorf("base URL 必须是绝对地址: %q", baseRaw)
    }

    // 引用可以是相对路径、根路径、查询/片段或另一个绝对 URL。
    ref, err := url.Parse(refRaw)
    if err != nil {
        return "", fmt.Errorf("解析引用 URL 失败: %w", err)
    }
    // 方法返回新的 URL；这里用 String 取出可传递的完整地址。
    return base.ResolveReference(ref).String(), nil
}

这个函数把三种问题分开了：Parse 负责输入语法，IsAbs 负责 base 的前置条件，ResolveReference 负责 URI 引用规则。这样遇到空字符串、缺少 scheme 或非法转义时，错误位置更容易定位。

ResolveReference 的适用压力：相对、根路径和绝对引用

同一个 base 下，不同形式的引用代表不同语义。假设 base 是 https://example.com/docs/index.html?lang=zh#top，可以把几种常见输入放在一个表里：

这也是它比 strings.TrimRight(base, "/") + "/" + ref 更可靠的原因：字符串拼接只能处理表面斜杠，不能正确表达根路径、查询、片段、scheme 和 host 的边界。

最容易错的不是函数，而是 base 的目录边界

相对路径是相对于 base 的“当前路径”解析的。base 以文件名结尾还是以斜杠结尾，会改变最后一段是否被当作目录：

func compareBase() {
    // 没有尾斜杠时，docs 被视为当前路径的最后一段。
    pathBase, _ := url.Parse("https://example.com/docs")
    // 有尾斜杠时，docs 被视为承载相对引用的目录。
    dirBase, _ := url.Parse("https://example.com/docs/")
    ref, _ := url.Parse("next")

    fmt.Println(pathBase.ResolveReference(ref).String())
    fmt.Println(dirBase.ResolveReference(ref).String())
}

这里的结果分别是 https://example.com/next 和 https://example.com/docs/next。如果 base 是带文件名的 https://example.com/docs/index.html，引用 next 同样会落到 /docs/next，因为最后一段被当作当前资源名替换。这个差异说明：写入 base 的字符串时，要明确它表示目录、文件，还是一个不带尾斜杠的路径节点。

工程上不要凭“有没有尾斜杠”猜结果，而应把真实的 base 和 ref 写成表格测试。尤其是 ../、空引用、只有查询的引用，以及带百分号编码的路径，都是应该单独覆盖的边界。

封装一个可复用的相对链接解析函数

如果业务层拿到的是网页或 API 返回的字符串，建议把解析集中到一个小函数中。调用方只接收已经补全的地址，不在各处重复处理斜杠和查询参数：

func absoluteURL(baseRaw, refRaw string) (*url.URL, error) {
    // base 必须带 scheme；否则相对引用没有可继承的绝对上下文。
    base, err := url.Parse(baseRaw)
    if err != nil {
        return nil, fmt.Errorf("base URL 无法解析: %w", err)
    }
    if !base.IsAbs() {
        return nil, fmt.Errorf("base URL 不是绝对地址: %q", baseRaw)
    }

    // 解析 ref 后交给标准库处理 path、query、fragment 和绝对引用。
    ref, err := url.Parse(refRaw)
    if err != nil {
        return nil, fmt.Errorf("引用 URL 无法解析: %w", err)
    }
    resolved := base.ResolveReference(ref)
    return resolved, nil
}

返回 *url.URL 而不是立即返回字符串，适合还要读取 Path、RawQuery 或 Fragment 的场景；只有要写日志、JSON 或发起后续请求时，再调用 String()。官方文档还明确说明该方法会返回新的 URL，因此不会因为解析结果改变而修改 base 或 ref 对象。

判断清单：什么时候不要拿它代替 JoinPath

ResolveReference 适合“一个地址加一个 URI 引用”的问题；如果需求只是把已经明确的路径段接到同一个 URL 上，可以考虑 URL.JoinPath。两者的判断可以压缩为下面四条：

• 输入有相对 URL、根路径、查询或片段语义：优先 ResolveReference。
• 输入已经是绝对 URL：ResolveReference 会忽略 base，直接返回 ref 的副本。
• 输入只是路径元素，需要清理 ./、../ 和重复斜杠：再看 JoinPath 是否更贴切。
• 输入来自外部数据：先处理 url.Parse 错误，并明确允许哪些 scheme 和 host；补全地址不等于建立安全信任。

最终可以把模式记成一句话：ResolveReference 负责解释引用相对于哪个绝对地址，JoinPath 负责在一个 URL 上组织路径元素。先确定需求是 URI 解析还是路径拼接，代码就不会被手写斜杠牵着走。

相关问题

• ResolveReference 会修改 base URL 吗？不会。它始终返回一个新的 URL 实例。
• base 只有 /docs/ 可以解析相对链接吗？可以被 url.Parse 解析，但它不是绝对 base，缺少 scheme 和 host，包装函数应拒绝它。
• 为什么绝对引用不会沿用 base 的 host？因为绝对引用已经带有自己的 scheme，上下文补全不再需要 base，标准库会返回它的副本。