Go net/url 处理重复查询键

Go 里遇到 ?tag=go&tag=http 这样的重复查询键时，不要先用字符串分割再猜哪个值有效。net/url 会把同一个键保存为多个值：需要全部值就取切片，需要单值就明确取第一个或主动覆盖。官方文档入口：https://pkg.go.dev/net/url。

重复查询键为什么要用 Values 保存

查询参数不是“一键对应一个字符串”的结构。一个筛选条件经常会出现多个值，例如标签、状态或多选框提交的内容。url.Values 的类型是 map[string][]string，因此 tag=go&tag=http 可以表示成 "tag": ["go", "http"]。解析时，ParseQuery 会返回合法参数，并把遇到的第一个解码错误作为错误结果返回。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // ParseQuery 将重复键保存在同一个键对应的切片中。
    values, err := url.ParseQuery("tag=go&tag=http&page=2")
    if err != nil {
        // 解析错误不能静默忽略，否则后续参数可能已经不完整。
        panic(err)
    }
    fmt.Println(values["tag"])
    fmt.Println(values.Get("page"))
}

这里的重点是：重复键的顺序仍然体现在切片中，单值参数则可以用 Get 读取。图 1 展示解析后的多值集合和重新编码之间的静态关系，它是结构说明图，不是运行截图。

Get 和直接取切片的语义不同

values.Get("tag") 只返回第一个值；官方文档明确说明，想访问多个值应直接读取 map。这个差别很容易在分页、筛选和权限参数中造成隐蔽问题：如果接口约定支持多选，直接使用 Get 就会静默丢掉后续值。

func readTags(values url.Values) ([]string, bool) {
    // 直接读取切片，保留重复参数在请求中的顺序。
    tags, ok := values["tag"]
    if !ok || len(tags) == 0 {
        return nil, false
    }

    // 复制切片，避免调用方修改解析结果后影响当前业务对象。
    result := append([]string(nil), tags...)
    return result, true
}

若业务只接受一个值，使用 Get 也可以，但要在代码语义中写清“首值优先”。若业务需要去重，应在业务层处理，而不是把 URL 的重复键直接当成错误；不同接口可能把重复值解释为 OR、重复提交或非法输入。

Add、Set、Del 怎样处理同一个键

构造或修改查询参数时，三个方法承担不同职责：

func buildQuery(tags []string, page string) string {
    values := url.Values{}
    for _, tag := range tags {
        // Add 保留每个标签，不能用 Set 放在循环里，否则只剩最后一个。
        values.Add("tag", tag)
    }
    if page != "" {
        // page 只保留一个值，所以这里用 Set 表达覆盖语义。
        values.Set("page", page)
    }
    values.Del("debug") // 删除调用方不应透传的可选参数。
    return values.Encode()
}

如果把 Set 误用在循环里，最后生成的查询串只有最后一个 tag。反过来，如果把本应唯一的 page 用 Add 多次追加，服务端就必须额外定义冲突处理规则。

Encode 负责转义和稳定生成查询串

修改完成后用 Encode 生成查询串，不要手工拼接键和值。它会进行 URL 编码，并按键排序；同一键的多个值会连续输出，例如两个标签会形成两个 tag=... 对。键排序有利于日志比较和缓存键稳定，但不代表业务可以依赖 map 的遍历顺序。

func appendQuery(base string, tags []string) (string, error) {
    u, err := url.Parse(base)
    if err != nil {
        // 先确认基础 URL 可解析，再修改 RawQuery。
        return "", err
    }
    query := u.Query()
    for _, tag := range tags {
        // Encode 会处理空格、斜杠等需要转义的字符。
        query.Add("tag", tag)
    }
    u.RawQuery = query.Encode()
    return u.String(), nil
}

选择重复键策略前先确认接口契约

同样的 URL 写法，在不同服务端可能代表不同业务含义。调用外部 API 前先确认它是否支持数组参数、是否要求逗号分隔、是否只接受单值，以及重复值的顺序是否重要。Go 代码只负责忠实表达参数，不应擅自把多值压成单值。

• 多选参数：用 Add，读取时直接处理 []string。
• 唯一参数：用 Set，必要时在业务层拒绝重复输入。
• 删除参数：用 Del，不要把空字符串当成删除。
• 输出查询串：统一用 Encode，避免特殊字符导致格式错误。

常见问题

url.Values.Get 会返回最后一个重复值吗？

不会。它返回该键关联切片中的第一个值；需要其他值时应直接访问切片。

Encode 会不会丢掉重复查询键？

不会。只要切片中保留多个元素，Encode 会为每个元素生成一个键值对。

能不能用 map[string]string 自己保存查询参数？

可以处理明确唯一的内部参数，但它无法自然表达重复键。只要接口支持多值，就应使用 url.Values 或等价的多值结构。