Go url.URL 怎样只替换查询参数而保留路径编码

在 Go 里拿到一个 url.URL 后，只改查询参数看起来很简单，但如果把整条 URL 当成字符串重拼，路径中的百分号编码就可能被误解。更稳妥的做法是：保留 URL 对象本身，只通过 Query 取出查询参数，修改后再把 Values.Encode() 的结果写回 RawQuery。

官方文档：https://pkg.go.dev/net/url

最小写法：只动 RawQuery

先解析原始 URL，再修改查询参数。Query 返回的是 url.Values，它适合处理同名参数；完成修改后，调用 Encode 生成规范化的查询字符串。

u, err := url.Parse("https://example.com/a%2Fb/report?tag=old&draft=1")
if err != nil {
    return err // 输入不是合法 URL 时，不继续修改
}

q := u.Query()
q.Set("tag", "new") // Set 会替换 tag 的全部值
q.Del("draft")      // 删除不再需要的参数
u.RawQuery = q.Encode()

fmt.Println(u.String())

这段写法的关键不在于 Set 或 Del 本身，而在于没有重新拼接路径。路径仍由 u.Path、u.RawPath 等字段共同描述，只有查询部分被重新编码。

Path、RawPath 和查询参数是三件事

URL.Path 是解码后的路径语义，URL.RawPath 是可选的原始编码提示，URL.RawQuery 则是问号后面的编码文本。它们的职责不同，不要用 Path 去代替整段原始路径。

例如路径中存在 %2F 时，Path 可能表现为带有斜杠语义的解码值；要观察可发送的转义路径，应使用 EscapedPath()。而更新查询参数时，只写回 RawQuery，就不会因为一次路径重建而混入额外的编码转换。

重复参数、空查询和编码陷阱

查询参数不是简单的键值字典。同一个键可以有多个值，因此根据需求选择 Set、Add 或 Del：

q := u.Query()
q.Add("tag", "extra") // 在已有 tag 后追加一个值
q.Set("page", "2")    // page 只保留一个值
q.Del("draft")        // 删除 draft 的全部值
u.RawQuery = q.Encode()

Values.Encode() 会把键和值进行查询编码，并按键排序输出。这个过程适合生成新的查询文本，但它不承诺保留原查询字符串的书写顺序或重复键的原始排版。若业务只关心参数语义，这正是应该使用的方式；若业务要求逐字保留原始查询文本，就不应先把它转换成 Values。

还要注意两个边界：

• 查询为空时，给 RawQuery 赋空字符串通常会移除查询部分；不要为了保留结尾问号而误以为 RawQuery 就够了。
• 不要用字符串替换直接改 ?a=1&b=2。参数值中的 &、空格和百分号都可能让这种替换产生误命中。

完整片段：保留路径后替换查询

package main

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

func main() {
    u, err := url.Parse("https://example.com/a%2Fb/report?tag=old&tag=keep&draft=1")
    if err != nil {
        log.Fatal(err) // 解析失败时停止，避免输出半成品 URL
    }

    q := u.Query()
    q.Set("tag", "new")
    q.Del("draft")
    u.RawQuery = q.Encode()

    fmt.Println("escaped path:", u.EscapedPath())
    fmt.Println("final URL:", u.String())
}

按代码逻辑，输出中的查询部分会只保留更新后的 tag，路径则继续由 URL 对象负责转义。真正需要保留的是“修改查询字段，再统一序列化”的边界，而不是某个固定的输出顺序。

常见问题

为什么不直接修改 URL 字符串？

字符串不知道路径、查询键和值的边界。参数值里出现转义字符或重复参数时，文本替换容易误改路径或其他参数。

什么时候应该用 RawQuery，而不是 Query？

读取和修改参数时使用 Query；已经得到新的 url.Values 后，使用 Encode 的结果写入 RawQuery。不要把未经编码的键值直接塞进 RawQuery。

只改一个参数会不会改变其他参数？

Set 只替换指定键，其他键仍会进入 Encode 结果；但查询字符串会重新规范化，原始顺序和排版不要作为可依赖的格式。