Go url.JoinPath 怎样拼接 URL 路径并保留查询参数

在 Go 里，如果只是把基础地址和几个路径段直接用字符串相加，很容易留下重复斜杠、../，或者把路径段中的斜杠误当成目录分隔符。url.JoinPath 更适合这个场景：它解析基础 URL，把路径段加入已有路径并清理点段，同时保留基础 URL 的查询参数和片段。

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

最小写法如下：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // 基础 URL 中的查询参数和片段不属于路径，JoinPath 会保留它们。
    base := "https://api.example.com/v1/?tenant=golang#users"
    result, err := url.JoinPath(base, "users", "42")
    if err != nil {
        // 基础 URL 解析失败时不要继续使用空结果。
        panic(err)
    }
    fmt.Println(result)
}

返回结果是 https://api.example.com/v1/users/42?tenant=golang#users。可以看到，路径被拼接和规范化了，?tenant=golang 与 #users 仍然存在。

JoinPath 只改路径，查询参数仍属于原 URL

url.JoinPath(base, elem...) 的基础 URL 会先被解析，路径段加入已有路径后，./、../ 和连续斜杠会按 URL 路径规则清理。查询参数和片段不是路径的一部分，因此不会被当成路径段重新拼接。

可以把它记成下面这张速查表：

基础路径和查询参数一起使用

如果参数值会变化，先用 url.URL 管理查询参数，再调用方法版 URL.JoinPath。这样路径和查询参数各自负责自己的语义，代码也比手写 ?、& 更稳妥。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // 先解析基础地址，便于分别修改 Path 和 RawQuery。
    u, err := url.Parse("https://api.example.com/v1?tenant=golang")
    if err != nil {
        // Parse 失败时返回错误，避免后续对 nil URL 继续操作。
        panic(err)
    }

    // QueryValues 只负责查询参数，JoinPath 只负责路径。
    values := u.Query()
    values.Set("page", "2")
    u.RawQuery = values.Encode()

    // 方法版返回新的 URL，不直接改变原对象的路径。
    child := u.JoinPath("users", "42")
    fmt.Println(child.String())
    fmt.Println(u.String())
}

这个例子输出的子地址会包含 /v1/users/42、tenant=golang 和 page=2。原来的 u 仍保留基础路径，适合在同一基础地址下派生多个资源 URL。

路径段里有斜杠，先判断它是分隔符还是数据

JoinPath 的参数是路径元素。如果传入的字符串中的斜杠表示层级，就直接把它作为多个路径段传入；如果斜杠属于一个资源名，例如对象键 team/a，就要先用 url.PathEscape 把它编码成一个路径段。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // 斜杠表示目录层级时，拆成多个路径元素。
    hierarchical, err := url.JoinPath("https://example.com", "team", "members")
    if err != nil {
        panic(err)
    }

    // 斜杠属于一个资源名时，先转义，避免它被拆成两级路径。
    objectName := url.PathEscape("team/members")
    encoded, err := url.JoinPath("https://example.com/object", objectName)
    if err != nil {
        panic(err)
    }

    fmt.Println(hierarchical)
    fmt.Println(encoded)
}

这里的区别是语义区别：第一种写法表达 /team/members 两级路径；第二种写法表达一个名为 team/members 的路径段，其斜杠应以转义形式保留。

url.JoinPath 和 URL.JoinPath 怎么选

两者的清理规则相近，主要差别在输入形态：

• url.JoinPath 接收字符串基础地址，适合一次性从配置值生成结果，并返回 (string, error)。
• (*url.URL).JoinPath 接收已解析的 URL，适合先修改查询参数、检查 host，再派生多个子路径，并返回新的 *url.URL。

如果基础地址来自配置、用户输入或网络数据，优先检查 Parse 或 JoinPath 返回的错误；如果基础地址是代码里写死的常量，测试代码中才适合使用 url.MustParse。

四个容易让结果不对的细节

1. 把查询串写进路径段。不要把 "users?active=1" 当作路径元素；查询参数应通过 RawQuery 或 url.Values 设置。
2. 把资源名里的斜杠直接传入。先判断斜杠是否代表层级，若是数据的一部分就使用 PathEscape。
3. 重复转义。路径元素必须按文档要求以已转义形式传入，已经是 %2F 的内容不要再无条件调用一次 PathEscape。
4. 忽略基础地址错误。JoinPath 仍要解析 base，非法 scheme、控制字符等问题会通过错误返回，不能只检查结果字符串是否为空。

结论

需要拼接 URL 路径时，先让 url.JoinPath 处理路径层级和点段清理，再用 url.Values 管理查询参数；路径段中的斜杠如果属于数据，就先做 PathEscape。如果同一个基础地址会派生多个结果，使用 URL.JoinPath 可以减少重复解析，并清楚地保持路径与查询参数的职责边界。

相关问题

• JoinPath 会不会删除 URL 的查询参数？不会，base 中已有的查询参数仍属于返回结果。
• 路径段可以直接写中文吗？可以，但应按路径段语义处理；需要把特殊字符作为单个段时，优先使用 PathEscape。
• 为什么不直接用字符串拼接？字符串拼接不会自动处理重复斜杠、点段、转义和基础地址解析错误。