Go 拼接 URL 为什么不能直接用 filepath.Join

把接口地址写成 filepath.Join(base, "v1", "users") 看起来顺手，但它解决的是“当前操作系统上的文件路径”问题，不是 URL 问题。最稳妥的做法是：先把地址解析成 url.URL，再用 URL.JoinPath；动态路径片段单独用 url.PathEscape，查询参数则交给 url.Values。

结论：URL 使用斜杠和 URL 编码规则，文件路径使用操作系统规则。不要用 filepath.Join 代替 net/url 的路径 API。

为什么 filepath.Join 会把文件系统规则带进 URL

filepath.Join 的职责是拼接文件系统路径，文档明确它使用 OS-specific separator。在 Unix 上通常得到斜杠，在 Windows 上可能得到反斜杠；即使当前机器恰好输出斜杠，它仍然会按文件路径语义清理输入。文件系统里的“目录”，和 URL 中需要经过转义的“路径段”，不是同一个抽象。

还有一个容易忽略的边界：filepath.Join 返回的是普通字符串，它不知道哪部分是协议、主机、path、query 或 fragment。把 https://api.example.test、v1 和 users 当成文件名拼起来，后续代码也无法可靠判断某个问号究竟是查询起点，还是用户数据的一部分。

用 url.JoinPath 拼接 URL 路径

Go 的 net/url 从 Go 1.19 起提供 JoinPath。它会把路径元素接到已有 URL path 后，并清理 ./、../ 以及重复斜杠。已有 URL 需要先解析；解析失败必须返回，不要用字符串替换掩盖错误。

package main

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

func main() {
    // 先解析完整地址，让 scheme、host、path 和 query 保持独立。
    base, err := url.Parse("https://api.example.test/service/?token=demo")
    if err != nil {
        log.Fatal(err)
    }

    // 只追加路径片段；原有 query 不会被当成目录名处理。
    result := base.JoinPath("v1", "users")
    fmt.Println(result.String())
}

这个例子得到的结果仍然有协议、主机、路径和查询串。若只持有字符串，也可以调用 url.JoinPath(base, "v1", "users")，它会返回字符串和错误；需要继续修改 query 或 fragment 时，使用 *url.URL 更清晰。

路径参数、查询参数和相对地址要分开

JoinPath 的元素应当已经是 URL 路径形式。动态值本身代表一个路径段时，先转义，否则值里的斜杠会被理解成新的层级：

// PathEscape 把用户编号作为一个完整路径段，而不是多个目录。
userID := url.PathEscape("team/a 7")
detail := base.JoinPath("v1", "users", userID)

// 查询条件使用 Values，避免手工拼接 ?、& 和转义规则。
query := detail.Query()
query.Set("page", "2")
query.Set("keyword", "go/url")
detail.RawQuery = query.Encode()

路径片段中的 team/a 7 与查询值 go/url 有不同语义。前者要保持一个 segment，后者只是 query value。若需求是“把相对地址解析到站点根路径或当前目录”，那是 ResolveReference 的职责，不应拿 JoinPath 代替。

上线前用四项检查确认拼接方式

1. 看到完整 URL 就检查是否先 url.Parse，不要先把 scheme 和 host 当路径拼接。
2. 检查每个动态值的语义：路径段用 PathEscape，查询值用 Values.Set。
3. 用 Windows 构建或跨平台测试确认没有把 filepath.Separator 带进网络地址。
4. 为带空格、斜杠、..、已有 query 的输入写表驱动测试，确认最终的 String()。

一句话记忆：文件系统路径交给 filepath，纯斜杠路径交给 path，完整 URL 交给 net/url。选择正确的抽象，通常比事后替换反斜杠更可靠。

常见问题

只有一个 URL 字符串和一个资源名，也要 Parse 吗？

如果需要保留 query、fragment 或继续修改 URL，建议 Parse；如果只是已知格式的简单地址，可以使用包级 url.JoinPath，并处理它返回的错误。

url.JoinPath 会自动帮我转义用户输入吗？

不会把任意原始字符串当成安全路径段。动态值先按路径段语义调用 url.PathEscape；不要把整条用户输入 URL 直接塞进 path 元素。

参考：net/url JoinPath 文档、path/filepath Join 文档、path Join 文档。