Go net/url.URL.JoinPath 拼接接口地址：斜杠清理与查询参数边界

接口地址通常来自配置，资源路径却来自业务变量，最容易出错的地方就是把两段字符串直接用 + 拼起来：基础地址末尾有没有斜杠、资源片段开头有没有斜杠、查询参数是不是被当成路径的一部分，都会在上线后变成偶发的 404。Go 的 net/url 提供了 URL.JoinPath，适合把路径片段交给 URL 结构处理，再单独设置查询参数。

先看清直接拼接为什么会留下隐患

下面的代码看起来简单，却把“路径规则”和“字符串格式”混在了一起：

base := "https://api.example.com/v1/"
resource := "/users/42"
endpoint := base + resource
// endpoint 可能得到 https://api.example.com/v1//users/42

双斜杠有时会被服务端容忍，有时会触发路由重定向；如果资源片段里还带有 ? 或 #，它们又会改变 URL 的语义。问题不在于字符串拼接速度，而在于调用方没有明确告诉程序哪一部分是路径、哪一部分是查询。

最小配方：解析基础地址后加入路径片段

把入口收敛成一个小函数，调用点就不需要反复处理斜杠：

package endpoint

import "net/url"

func withPath(rawBase string, parts ...string) (*url.URL, error) {
    base, err := url.Parse(rawBase)
    if err != nil {
        return nil, err
    }
    if base.Scheme == "" || base.Host == "" {
        return nil, fmt.Errorf("base URL must include scheme and host")
    }
    base.JoinPath(parts...)
    return base, nil
}

示例里还需要导入 fmt。这里保留显式的 scheme 和 host 检查，是因为 JoinPath 只解决路径拼接，不会替你判断一个配置是否是可发请求的绝对地址。

JoinPath 改的是 Path，不是查询参数

JoinPath 接收的是路径片段。把 "users/42"、"users" 和 "42" 分开传入，语义比手工拼接清晰；不要把 "users?active=1" 当成查询参数写进片段，后续代码很难再判断它到底属于哪一层。

u, err := url.Parse("https://api.example.com/v1/")
if err != nil {
    return err
}
u.JoinPath("users", "42")

q := u.Query()
q.Set("active", "true")
q.Set("page", "2")
u.RawQuery = q.Encode()
fmt.Println(u.String())
// https://api.example.com/v1/users/42?active=true&page=2

查询值中的空格、中文和 & 会由 Values.Encode 处理。路径片段和查询值使用不同的 API，正是这段代码最值得保留的边界。

四个容易误判的路径边界

重复斜杠通常会被清理

基础地址是 https://api.example.com/v1/，片段写成 "/users/" 时，调用方不必再为首尾斜杠做条件分支。输出仍要用测试锁定，因为重构时最容易悄悄换回字符串拼接。

点号片段会参与路径规范化

路径里的 . 和 .. 有特殊含义。不要把未经约束的用户输入直接当作路径片段；如果业务只允许资源 ID，应先做字符集和长度校验，再调用 JoinPath。它不是权限校验，也不是目录访问安全边界。

已有查询参数要先保留再追加

如果基础 URL 已经包含 ?tenant=demo，直接给 RawQuery 赋新字符串会覆盖原参数。更稳妥的做法是调用 u.Query() 取得副本，修改后重新编码。

片段中的百分号不要随便预编码

路径值和查询值都有转义规则。调用方如果先把字符串编码一次，再交给 URL API，可能得到双重转义。建议在边界测试中加入空格、中文、百分号和斜杠，直接检查最终 EscapedPath 或完整字符串。

用表格驱动测试把拼接结果固定下来

这类工具函数不需要复杂测试框架，几个输入就能覆盖主要风险：

func TestWithPath(t *testing.T) {
    cases := []struct {
        name string
        base string
        parts []string
        want string
    }{
        {"slashes", "https://api.example.com/v1/", []string{"/users/", "/42"}, "https://api.example.com/v1/users/42"},
        {"query", "https://api.example.com/v1?tenant=demo", []string{"users"}, "https://api.example.com/v1/users?tenant=demo"},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            got, err := withPath(tc.base, tc.parts...)
            if err != nil {
                t.Fatal(err)
            }
            if got.String() != tc.want {
                t.Fatalf("got %q, want %q", got.String(), tc.want)
            }
        })
    }
}

实际项目还应补充空片段、非 ASCII 查询值、已有重复键以及 .. 片段等测试。测试断言最好比较完整 URL，同时在确实关心编码细节的场景单独断言 Path、RawQuery 和 EscapedPath。

一个可复用的请求构造顺序

1. 从配置读取基础地址，用 url.Parse 解析。
2. 检查 Scheme 和 Host，确认它是预期的服务入口。
3. 调用 JoinPath 加入固定路径和已经校验过的业务片段。
4. 用 Query、Set 或 Add 写查询参数，再赋回 RawQuery。
5. 在发送前记录不含凭据的最终 URL，并用单元测试锁定典型边界。

这里别急着把所有字符串都交给一个“万能拼接器”。路径、查询、认证头和请求体本来就是不同层次；分开构造，排查 404、参数丢失和编码异常都会更直接。

常见问题

JoinPath 会自动检查域名是否可信么？

不会。它只处理 URL 的路径部分。服务地址来自配置或用户输入时，仍要单独限制 scheme、host 和允许的目标范围。

查询参数能直接拼在 JoinPath 的最后一个片段里吗？

不建议。把查询值交给 url.Values，再设置 RawQuery，可以避免路径和查询语义混在一起。

JoinPath 能替代所有 URL 安全校验吗？

不能。它不负责认证、授权、SSRF 防护或业务 ID 校验。它解决的是路径拼接和 URL 表达，不是完整的请求安全策略。

把 URL 的每一层交给对应 API

URL.JoinPath 的价值不只是少写几个斜杠，而是把路径片段从普通字符串里分离出来。基础地址先解析，路径用 JoinPath，查询用 Values，最后用测试确认完整输出；这条小规则足以消掉接口客户端里一批隐蔽的边界 bug。