Go net/url 怎么只编码查询参数而不破坏路径斜杠

要只编码查询参数，最稳妥的做法是先解析基准 URL，再用 u.Query() 取得 url.Values，修改参数后把 q.Encode() 重新赋给 u.RawQuery。不要对整条 URL 调用 url.QueryEscape，也不要把路径和查询字符串混在一个普通字符串里编码。

查询参数和路径片段为什么不能用同一种编码

URL 中的 / 在路径里通常表示层级，在查询参数值里却只是需要转义的普通字符。空格也有类似差异：查询编码通常把空格写成 +，而路径片段编码不能把加号当成空格。标准库因此提供了不同的编码入口。

例如，url.QueryEscape("a/b+c") 的结果会把斜杠、加号都当作查询值内容处理；url.PathEscape("a/b+c") 则只把片段内部的斜杠隔离出来。这里的关键不是记住百分号结果，而是先确定数据要放到 URL 的哪个组件。

只改查询参数时让 URL 对象负责重组

如果路径已经来自配置或路由，修改参数时不要重新拼接 path + "?" + query。下面的写法只触碰查询部分，路径中的斜杠不会被二次编码。

package main

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

func main() {
    base, err := url.Parse("https://api.example.com/repos/team/core/files/a/b")
    if err != nil {
        log.Fatal(err) // 解析失败时不要继续拼接半成品 URL
    }

    q := base.Query()
    q.Set("keyword", "a/b + c") // 斜杠在这里是查询值内容
    q.Set("page", "2")
    base.RawQuery = q.Encode() // 只重编码查询键和值

    fmt.Println(base.String())
}

输出中的路径仍是 /repos/team/core/files/a/b，而查询值里的斜杠、加号和空格会按查询规则转义。Values.Encode 还会按键排序，这对缓存键和测试断言更友好；不要依赖手写参数的顺序。

动态路径片段要单独转义，不能把层级斜杠一起编码

另一类常见需求是把用户输入放进路径，例如文件名或资源标识。此时应该先明确输入是“一个片段”还是“多个层级”。单个片段使用 PathEscape；真正的层级分隔符由 URL 结构拼接。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    tenant := url.PathEscape("team/a") // 输入是一个片段，内部斜杠不能新增层级
    file := url.PathEscape("设计稿 v2.txt")

    u := url.URL{
        Scheme: "https",
        Host:   "api.example.com",
        Path:   "/tenants/" + tenant + "/files/" + file, // 这里的斜杠才是结构分隔符
    }
    fmt.Println(u.String())
}

如果业务输入本来就是多个层级，应先按业务边界拆分，再逐段编码，不能先把整段路径当成一个片段。反过来，如果接口把带斜杠的标识视为单一 ID，PathEscape 编码出的 %2F 就应该保留。

需要保留原始 %2F 时读取 EscapedPath

url.Parse 后，URL.Path 体现的是解码后的路径；因此原始 URL 中的普通斜杠和 %2F 在 Path 里可能看起来一样。标准库会在有效时保留 RawPath 这个编码提示，输出时应调用 EscapedPath()，而不是直接读取 RawPath。

package main

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

func main() {
    u, err := url.Parse("https://api.example.com/files/a%2Fb?download=1")
    if err != nil {
        log.Fatal(err) // % 编码不完整时，先处理 Parse 错误
    }

    fmt.Println("Path:", u.Path)              // 解码后的 /files/a/b
    fmt.Println("EscapedPath:", u.EscapedPath()) // 有效时保留 /files/a%2Fb
}

只有在确实需要保留输入 URL 的转义表现时才关心这条边界。普通的 URL 构造仍然优先设置 Path，让 String() 负责生成合法表示；手工同时修改 Path 和 RawPath 容易造成两者不一致。

把编码责任收回到 URL 的组件边界

排查“路径斜杠消失”时，先检查是否对完整 URL 或已经编码的查询字符串再次调用了 QueryEscape。修复时按这张清单执行：路径结构交给 URL，查询参数交给 Values，单个动态片段交给 PathEscape，已有原始路径编码交给 EscapedPath。这样每个百分号编码都只发生一次，调用方也更容易写出稳定的单元测试。

相关问题

QueryEscape 和 Values.Encode 有什么区别？

QueryEscape 只处理一个字符串；Values.Encode 处理参数键和值的集合，并生成可放入 RawQuery 的完整查询串。

为什么查询参数里的空格变成了加号？

这是查询组件的编码规则。读取时使用 QueryUnescape 或 URL.Query，不要拿路径解码规则替代它。

能不能直接修改 RawQuery？

可以，但前提是你已经拥有合法的编码查询串。需要增删改参数时，使用 u.Query() 和 q.Encode() 更不容易漏掉转义和重复键。