Go net/url.ResolveReference 怎么拼接带路径的 API 地址

在 Go 里把 API 的基础地址和接口返回的相对链接拼起来，优先使用 net/url 的 ResolveReference，不要直接用字符串相加。它会按照 URI 引用规则处理目录、根路径、查询参数和完整地址；真正需要先确认的是基础 URL 最后有没有斜杠。

最小写法是分别 url.Parse 基础地址和相对地址，再调用 base.ResolveReference(ref)。基础地址以 / 结尾时，相对路径进入这个目录；没有斜杠时，最后一段会被当作文件名替换。

先把基础 URL 和相对路径的关系看清

假设服务把用户详情链接写成相对地址。基础地址是目录时，detail?id=42 会接在目录后面；基础地址像文件时，detail 会替换最后一段：

package main

import (
    "fmt"
    "log"
    "net/url"
)

func main() {
    // 末尾斜杠表示当前路径是目录。
    base, err := url.Parse("https://api.example.com/v1/users/")
    if err != nil {
        log.Fatal(err)
    }
    ref, err := url.Parse("detail?id=42")
    if err != nil {
        log.Fatal(err)
    }

    // 返回新的 URL，便于保留 base 作为后续请求的上下文。
    resolved := base.ResolveReference(ref)
    fmt.Println(resolved.String())
    // https://api.example.com/v1/users/detail?id=42
}

如果把基础地址改成 https://api.example.com/v1/users，同一个引用的结果会是 https://api.example.com/v1/detail?id=42。这不是 Go 的字符串拼接，而是把基础路径的最后一段视为可替换部分。

四种引用写法分别会改什么

把引用按形态分组，比记住某个例子的输出更可靠。下面以 https://api.example.com/v1/users/?token=old 为基础地址：

空引用还有一个容易忽略的行为：当引用没有路径、查询和片段时，基础 URL 的查询和片段会被保留。完整 URL 则会独立于基础地址返回副本，所以不要把外部跳转链接当成“继续拼接”。

把解析错误和调用边界放进 API 客户端

ResolveReference 本身不返回 error，错误发生在前面的 url.Parse。基础地址和外部引用都可能来自配置或服务响应，因此两处都要检查；不要为了省一行代码忽略第二次解析。

func resolveAPIURL(rawBase, rawRef string) (*url.URL, error) {
    // 先解析配置中的基础地址，失败时直接返回上下文错误。
    base, err := url.Parse(rawBase)
    if err != nil {
        return nil, fmt.Errorf("解析基础 API 地址失败: %w", err)
    }

    // 再解析服务返回的引用，避免把不合法字符带入请求地址。
    ref, err := url.Parse(rawRef)
    if err != nil {
        return nil, fmt.Errorf("解析 API 相对地址失败: %w", err)
    }
    return base.ResolveReference(ref), nil
}

生产代码还应明确是否允许引用携带新的 scheme 或 host。若只允许站内 API，可以在返回后比较 Scheme、Host，再交给 HTTP 客户端；这属于业务安全边界，不是 ResolveReference 自动替你做的校验。

常见问题

ResolveReference 会修改 base 吗？

不会。官方文档说明它总是返回一个新的 URL 实例，适合把同一个基础地址复用于多次请求。

为什么结果少了一层 users？

通常是基础 URL 没有以斜杠结尾。没有斜杠时，最后一段按文件处理；需要把它当目录，就写成 /users/。

ResolveReference 和 URL.Parse 有什么关系？

base.Parse(refString) 会先解析字符串，再按同样的引用规则调用 ResolveReference。需要复用已解析引用或显式处理两次错误时，直接调用前者更清楚。