Go net/url.URL.PathEscape 怎样避免路径参数被错误拼接

我在给接口拼接资源地址时，最容易忽略的不是域名，而是“这个动态值究竟属于路径，还是属于查询参数”。如果把用户输入直接接到路径后面，值里只要出现斜杠、空格或问号，最终 URL 就可能被解析成另一层路径或查询串。

动态值代表一个路径段时，先调用 url.PathEscape，再把它放进路径；动态值代表查询参数时，则使用 url.Values 编码。不要用 QueryEscape 代替路径段编码，也不要把已经编码的值重复编码。

官方地址：https://pkg.go.dev/net/url#PathEscape

这篇只处理一个具体边界：Go 标准库怎样保护单个路径参数。重点是理解编码对象，而不是给整条 URL 反复调用字符串替换。

先判断这个值是不是一个路径段

URL 中的 / 用来分隔路径层级，? 用来引出查询串，# 则会进入片段部分。假设接口地址是 /users/{name}，其中 name 是一个整体标识，而不是新的子路径，那么它应当被当作“一个路径段”处理。

直接拼接的写法看起来很直观，但它把数据和 URL 语法混在了一起：

// 直接拼接会让参数中的斜杠参与路径分层。
rawPath := "/users/" + name
requestURL := "https://api.example.com" + rawPath

例如 name 是 team/blue 时，结果会自然变成 /users/team/blue，这已经不是一个名为 team/blue 的单段标识了。问题不在字符串连接本身，而在于没有先声明数据的边界。

PathEscape 保护的到底是什么

url.PathEscape 接收一个字符串，返回适合放入 URL 路径段的转义形式。它保护的是“单个路径段”，不是整条 URL，也不是已经包含斜杠分隔符的完整路径。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    name := "team/blue review"
    // 只编码动态路径段，让其中的斜杠和空格不再改变路径层级。
    escapedName := url.PathEscape(name)
    path := "/users/" + escapedName

    fmt.Println(path)
}

这里的关键是先编码 name，再把结果放到固定的 /users/ 后面。不要把 /users/ 一起传给 PathEscape，否则固定的路径分隔符也会失去原本的结构意义。

不要用 QueryEscape 处理路径参数

我第一次遇到这个问题时，直觉是看到“Escape”就拿来复用。实际上，路径和查询串是 URL 的两个不同位置。PathEscape 面向路径段，QueryEscape 面向查询参数的值；两者对空格等字符的处理语义并不应该混用。

所以，PathEscape 不是“通用 URL 加密函数”。它只负责某个明确位置的字符表示；位置判断错了，换一个 Escape 函数也只是把问题推迟。

用 url.URL 组装完整地址

当地址同时有路径参数和查询参数时，结构化设置字段比多段字符串拼接更容易检查。路径段先经过 PathEscape，查询值交给 url.Values，最后由 url.URL.String 生成完整文本。

package main

import (
    "fmt"
    "net/url"
)

func buildURL(name, keyword string) string {
    query := url.Values{}
    // 查询值交给 Values 统一编码，不和路径段规则混用。
    query.Set("q", keyword)

    u := url.URL{
        Scheme:   "https",
        Host:     "api.example.com",
        Path:     "/users/" + url.PathEscape(name),
        RawQuery: query.Encode(),
    }
    return u.String()
}

func main() {
    // name 是一个路径段，keyword 是查询参数，二者走不同编码路径。
    fmt.Println(buildURL("team/blue review", "Go URL 编码"))
}

这段代码的重点不是记住字段名，而是让数据流清楚：Path 放路径，RawQuery 放已经由 Values.Encode 生成的查询串。RawPath 是 URL 结构中用于保留特定转义形式的字段，通常不需要手动设置；除非确实需要保留与 Path 对应的非默认转义表示，否则不要为了“看起来更编码”而随意填写它。

解码、空值和重复转义要分开处理

如果收到的是一个已经放在路径中的转义值，可以使用 url.PathUnescape 还原它；但不要在不清楚数据状态时盲目解码。解码两次可能把原本想保留的字面量变成路径语法，编码两次则会出现类似 %252F 的重复转义。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    escaped := "team%2Fblue"
    // 只对明确知道是 PathEscape 结果的值做一次逆操作。
    value, err := url.PathUnescape(escaped)
    if err != nil {
        // 生产代码应把非法转义交给请求参数错误处理流程。
        fmt.Println("invalid path segment:", err)
        return
    }
    fmt.Println(value)
}

空字符串也要按业务定义处理：它可以代表空的标识，也可能意味着请求缺少必填参数。编码函数不会替你做业务校验；在调用 PathEscape 前先判断必填项，通常比生成一个看似合法但没有资源含义的路径更稳妥。

常见问题

PathEscape 能不能直接处理完整路径？ 不建议。它面向单个路径段；完整路径中的斜杠应该由路径结构保留，再逐个编码动态段。

路径参数里本来就允许斜杠怎么办？ 那它可能不是单个路径段，而是多段路径或需要重新定义接口协议。先明确路由边界，再决定逐段编码还是让服务端接收原始路径。

为什么还要使用 url.URL？ 当地址同时包含路径、查询、片段或用户信息时，结构化字段能让每种数据走自己的编码规则，减少拼接时的边界错误。

PathEscape 后还需要再调用 QueryEscape 吗？ 不需要。一次选择与数据位置匹配的编码方式即可，重复编码会改变原本的字面内容。