Go url.JoinPath 拼接动态路径时怎样避免编码错误

我在给外部 API 拼资源路径时，最容易踩的坑不是域名，而是把“一个动态值”误当成了普通字符串。比如资源名是 team/alpha beta，直接用斜杠拼接，服务端会把它看成两个路径段；直接对整条 URL 做转义，又可能连协议和分隔符一起破坏。

这类场景可以把职责拆开：动态值如果代表一个路径段，先用 url.PathEscape；再用 url.JoinPath 合并基础路径。JoinPath 负责连接和清理路径，但不会替你判断动态值的业务边界。

适用范围：本文只讨论路径元素的转义与清理，不讨论查询参数；查询参数应交给 url.Values 和 Encode。

先把动态值当作一个路径段

先问自己一个问题：资源名里的斜杠是数据，还是层级？如果 team/alpha 表示一个资源名，斜杠就是数据，必须编码成 %2F；如果它本来就代表两级目录，就应该传入两个路径元素，而不是先把它当作一个整体。

这一步的边界很重要：PathEscape 面向单个路径段，会把斜杠等特殊字符编码；QueryEscape 面向查询字符串，不能拿来替代路径段转义。

用 PathEscape 后再 JoinPath

下面的写法把“编码一个动态段”和“连接路径”分成两个动作，读代码时也更容易检查：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    base := "https://api.example.com/v1"
    resource := "team/alpha beta"

    // 先把资源名当成一个路径段，避免其中的斜杠改变层级。
    escapedResource := url.PathEscape(resource)
    // JoinPath 只负责连接路径并清理多余的路径片段。
    endpoint := url.JoinPath(base, "records", escapedResource)

    fmt.Println(endpoint)
}

这里的关键不是把所有输入都无脑 PathEscape，而是先确定输入契约：resource 是单个标识符，还是已经拆好的路径列表。若业务上确实是多级路径，应使用多个元素，例如 url.JoinPath(base, "records", "team", "alpha")，不要把完整多级路径当作一个段。

识别 JoinPath 的清理边界

JoinPath 会把路径元素连接起来，并清理 ./、../ 和重复斜杠。它解决的是路径规范化，不是“原样保存每个字符串”。因此，下面两件事不要混为一谈：

尤其要注意已经带百分号的输入。如果调用方传入的是原始资源名，就在进入 JoinPath 前统一按路径段处理；如果输入契约已经明确是 escaped path，就不要再次编码，否则可能出现双重转义。边界应由接口文档写清楚，而不是在字符串拼接处猜测。

在请求前检查路径结果

构造完 URL 后，检查应聚焦于路径本身：解析 URL，查看 EscapedPath 是否保留了预期的编码；查询参数则另行使用 RawQuery 或 Query 处理。不要用“能打印出来”作为唯一判断，因为打印结果看不出动态值究竟是一个段还是多个段。

u, err := url.Parse(endpoint)
if err != nil {
    // 解析失败时立即返回，避免把不完整的地址交给 HTTP 客户端。
    return err
}

fmt.Println("escaped path:", u.EscapedPath())
// RawQuery 属于查询部分，与路径段编码是两套规则。
fmt.Println("query:", u.RawQuery)

可以把这条经验固化成团队约定：函数参数若表示一个资源 ID，就接收原始值并在函数内部只编码一次；若表示已编码的路径，则在命名和文档中明确 escaped，避免调用方重复处理。

常见问题

为什么不能先拼接再 PathEscape？
因为整条 URL 中的协议、主机、斜杠和查询分隔符都有结构含义；路径段编码应发生在结构拼接之前。

PathEscape 后还要不要调用 JoinPath？
要。前者确定动态值在一个路径段内的编码，后者负责把基础路径和多个元素连接并做路径清理，两者职责不同。

把动态路径拆成“值的语义”和“路径的结构”后，url.JoinPath 就不再是一个凭经验试出来的字符串工具，而是一个边界清楚的标准库组件。