net/url.JoinPath 组合接口路径并保留转义的实践示例

在 Go 里拼接 REST 接口地址时，net/url.JoinPath 适合处理“已有 URL + 若干路径段”的组合：它会清理结果中的 ./ 和 ../，同时要求传入的路径段已经是 URL 转义形式。最稳妥的做法是把基础地址、资源标识和查询参数分开处理，路径标识先用 url.PathEscape，最后再设置 RawQuery。

官方资料：https://pkg.go.dev/net/url#JoinPath

这篇只讨论接口路径的组合边界，不把 URL 路径当成文件系统路径，也不把查询字符串直接塞进 JoinPath 的参数里。

先把接口路径和用户标识拆开

接口地址通常有三层信息：固定的服务地址、表示资源层级的路径段、用于筛选或分页的查询参数。JoinPath 只负责第二层和基础地址的组合。把三层混成一个字符串，最容易在标识包含斜杠、问号或百分号时产生歧义。

如果只需要字符串形式，也可以使用包级函数 url.JoinPath(base, elem...)；如果后面还要设置查询参数、检查主机或复用 URL 对象，则使用 url.Parse 配合 u.JoinPath 更自然。

路径段先转义，再交给 JoinPath

package main

import (
    "fmt"
    "net/url"
)

func resourceURL(base, resourceID string) (string, error) {
    u, err := url.Parse(base)
    if err != nil {
        // 基础地址解析失败时不要继续拼接，避免把错误隐藏在结果字符串里。
        return "", err
    }

    escapedID := url.PathEscape(resourceID)
    // 这里只把一个资源标识当作一个路径段，斜杠会保留为转义文本。
    u = u.JoinPath("v1", "records", escapedID)
    return u.String(), nil
}

func main() {
    result, err := resourceURL("https://api.example.test/", "team/a 01")
    if err != nil {
        // 真实请求前先返回错误，调用方可以记录并选择重试或终止。
        panic(err)
    }
    fmt.Println(result)
}

这里的关键不是“多写一个函数”，而是明确 resourceID 的语义。team/a 01 是一个标识时，先转义能避免其中的斜杠被拆成两级路径。JoinPath 的文档要求路径元素已经处于转义形式；不要把同一段先转义、再把结果当普通文本重复转义。

JoinPath 会清理点段，但不会替你定义业务规则

JoinPath 会对结果路径做清理，./ 和 ../ 不会原样保留在最终路径中。这对组合版本号、资源名和固定接口层级很方便，但也意味着它不是“原样连接器”。如果你的业务需要保留输入文本的逐字符表示，应该在进入 URL 组合前单独保存原值。

func cleanedPath(base string, segments ...string) (string, error) {
    u, err := url.Parse(base)
    if err != nil {
        // Parse 返回的错误比继续拼接一个不完整地址更容易定位。
        return "", err
    }

    // JoinPath 会做 URL 路径清理；这里的 segments 代表接口层级，不代表文件系统路径。
    u = u.JoinPath(segments...)
    return u.EscapedPath(), nil
}

还要注意“路径段已经转义”和“路径最终如何显示”是两个层次。URL.Path 表示解码后的路径语义，EscapedPath 返回适合放入请求目标的转义表示；只有在需要保留非默认的转义形式时，才进一步关注 RawPath。通常不要为了让输出字符串“看起来特殊”而手动修改 RawPath。

查询参数放到 URL 对象上处理

func listURL(base, owner string, page int) (string, error) {
    u, err := url.Parse(base)
    if err != nil {
        // 地址不合法时直接返回，让上层决定如何处理配置错误。
        return "", err
    }

    // owner 是路径段，先转义；page 是查询参数，不能混在 JoinPath 里。
    u = u.JoinPath("v1", "owners", url.PathEscape(owner), "records")
    query := u.Query()
    query.Set("page", strconv.Itoa(page))
    u.RawQuery = query.Encode()
    return u.String(), nil
}

上面的示例还需要导入 strconv。它故意把路径和 query 分成两个局部变量：读代码的人能看到哪个值会改变层级，哪个值只参与筛选。分页数字、排序字段等查询值不应被 PathEscape 处理，也不应直接通过字符串拼接附加到路径后面。

哪些边界值值得在发布前检查

1. 路径段含斜杠：确认它是一个标识，还是确实要表达多级资源；前者先 PathEscape，后者拆成多个参数。
2. 输入已经包含百分号：区分合法的已转义输入和普通文本百分号，避免重复转义。
3. 参数带问号或井号：它们属于标识时应作为路径段转义，属于 query 或 fragment 时使用各自的 URL 字段。
4. 基础地址已有路径：明确是继续追加到它后面，还是要替换路径；不要把 ResolveReference 的相对引用语义和 JoinPath 混用。
5. 输入含点段：把清理后的结果当作接口路径再审视一次，不能假设每个输入字符都会出现在输出中。

一句话总结：JoinPath 负责把“已经明确是路径的片段”组合成干净 URL 路径；PathEscape 负责把单个外部标识封装成一个安全路径段；查询参数则交给 URL.Query。三者职责分开，接口地址才不会因为一个用户标识或分页参数改变路径结构。

常见追问

JoinPath 能不能直接接带问号的字符串？

不建议。带问号的内容可能被当作路径文本或破坏你对 URL 组成部分的判断。应先把它明确为路径段并转义，或者使用 RawQuery 表示查询参数。

为什么不直接用字符串拼接？

字符串拼接无法自然表达路径清理、百分号编码和已有 URL 路径的边界。它可以用于极简单的固定常量，但只要有外部标识或 query，就应让 net/url 管理对应部分。