Go net/url 怎样只修改查询参数而保留路径

在 Go 中给已有地址追加分页、筛选或回调参数时，最稳妥的做法是先用 url.Parse 解析，再通过 URL.Query() 取出参数集合，修改后用 Values.Encode() 写回 RawQuery。这样不会因为字符串拼接误伤路径、片段或原有转义。

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

只改查询参数时，编辑 url.Values，最后赋给 u.RawQuery；不要把整条 URL 当普通字符串拼接。

为什么不要直接拼接 URL 字符串

直接写 base + "?page=2" 只适合你完全控制输入、且确认原地址没有查询串的情况。真实地址可能已经有 ?、重复键、中文值、片段标识符，甚至路径中包含需要保留的转义。字符串拼接很容易出现第二个问号、参数没有编码，或者把新参数放到片段之后。

net/url 的职责就是把这些部分分开。解析后，u.Path、u.RawQuery 和 u.Fragment 各自表达不同语义，更新查询参数时只应触碰 RawQuery。

先解析 URL，再处理错误

下面的函数接收一个已有地址，先解析并返回错误。示例只负责构造新地址，不发送网络请求。

package main

import (
    "fmt"
    "net/url"
)

func updateQuery(raw string) (string, error) {
    // 先解析完整地址，避免把路径、查询串和片段混在字符串里处理。
    u, err := url.Parse(raw)
    if err != nil {
        return "", fmt.Errorf("解析 URL 失败: %w", err)
    }

    // Query 返回可编辑的 Values；这里修改的是查询参数集合。
    values := u.Query()
    values.Set("page", "2")
    values.Set("keyword", "Go URL")

    // Encode 负责查询参数转义，再把结果写回 RawQuery。
    u.RawQuery = values.Encode()
    return u.String(), nil
}

func main() {
    // 原地址已有路径、筛选参数和片段，更新后这些部分仍应保留。
    result, err := updateQuery("https://example.com/docs/search?sort=desc#install")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(result)
}

这里的关键不是 Set 本身，而是“解析—修改 Values—编码—写回”的边界。解析失败时立即返回，调用方可以决定记录日志、提示用户还是放弃构造。

用 Query 和 Encode 安全改写查询参数

Values 是 map[string][]string，因此同一个键可以对应多个值。Set 会替换这个键的全部旧值，Add 会追加一个值，Del 会删除这个键，Get 只读取第一个值。

func changeFilters(raw string) (string, error) {
    // Parse 保留原 URL 的 Host、Path 和 Fragment，避免手动切分地址。
    u, err := url.Parse(raw)
    if err != nil {
        return "", err
    }

    values := u.Query()
    // Set 适合分页和排序这类只允许一个值的参数。
    values.Set("page", "3")
    values.Set("sort", "created_at")
    // Del 删除旧筛选，避免把调用方已经取消的条件继续带上。
    values.Del("draft")
    // Encode 会进行查询串需要的转义，并按照键名稳定输出。
    u.RawQuery = values.Encode()
    return u.String(), nil
}

如果业务本来允许多选条件，例如 tag=go&tag=web，不要用 Set 覆盖已有值，而应先 Del 再按业务顺序多次 Add。最后统一调用一次 Encode，避免半编码状态在多个函数之间传递。

几个容易误判的边界

• 空值不是缺失。values.Set("q", "") 编码后仍可能表现为 q=；如果要移除参数，应使用 Del。
• 重复键要先确定语义。Get 只取一个值，读取全部值应使用 values["tag"] 或 values.Has 配合业务判断。
• 片段不是查询参数。#install 属于 Fragment，不会进入 Query；不要把它拼到查询串中。
• 不要把已编码值再次当原文编码。把 %2F 当成普通文本再次传入，可能得到不同的地址语义。

可以用一张小表记住常用操作：

总结与常见问题

Go 修改已有 URL 的查询参数，可以固定成四步：url.Parse 解析，Query 取集合，Set/Add/Del 编辑，Encode 写回 RawQuery。这样路径、主机和片段保持独立，参数转义也交给标准库处理。

为什么改了 Query 但原 URL 没变化？

Query() 返回的是可编辑的 Values 副本，修改后必须把 values.Encode() 赋给 u.RawQuery，再调用 u.String() 取结果。

什么时候使用 Add 而不是 Set？

当接口把同名参数解释为多选列表时使用 Add；分页、排序这类单值参数通常用 Set，这样不会意外保留旧值。