Go url.Values 怎样稳定输出重复查询参数

Go 里要稳定输出重复查询参数，直接使用 url.Values：它本质上是 map[string][]string，同一个键的多个值放在切片里；Add 负责追加，Set 负责替换，Get 只返回第一个值，最后用 Encode 生成查询字符串。Encode 会按键排序，但不会改变同一键的值切片顺序。

先把重复参数放进值切片

查询字符串里的 tag=go&tag=url 不是两个不同的键，而是一个键对应两个值。url.Values 把这个关系直接表达成 map[string][]string：键名是 map 的键，重复出现的值按加入顺序保存在切片里。

如果是构造请求过滤条件、批量选择标签或传递多选项，可以这样写：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	values := url.Values{}
	// Add 追加同名参数，保留每一次选择的顺序。
	values.Add("tag", "go")
	values.Add("tag", "url")
	// Set 只适合唯一参数；它会替换 page 之前保存的值。
	values.Set("page", "2")

	fmt.Println(values["tag"])
	fmt.Println(values.Encode())
}

这里的 tag 对应一个长度为 2 的值切片，page 只有一个值。调用 Set 前如果已经有旧值，旧切片会被替换；因此“同名参数需要累加”时要固定使用 Add。

读取时区分第一个值和全部值

Get 的语义是取某个键关联的第一个值。它适合读取 page、sort 这类按约定只能出现一次的参数；对重复参数使用 Get，会悄悄丢掉后面的选择。

func readTags(values url.Values) ([]string, string) {
	// 直接取 map 中的切片，才能保留所有重复值。
	tags := values["tag"]
	// Get 只读取第一个值，适用于单值参数的快速读取。
	page := values.Get("page")
	return tags, page
}

如果参数可能不存在，直接访问 map 得到的切片可能是 nil，可以用 values.Has("tag") 区分“键不存在”和“切片存在但为空值”等业务情况。对于只允许一个值的字段，还应该在业务层明确重复出现时采用首值、拒绝还是取最后一个，不能让 Get 的默认行为替代规则。

用 Encode 让键的顺序稳定

Values.Encode 会把键编码后按字典序输出，并按每个键的值切片顺序展开重复参数。也就是说，下面的 map 插入顺序不重要，但 tag 切片中 go 和 url 的先后仍然会保留：

func encodeFilters() string {
	values := url.Values{}
	// map 的写入先后不作为最终键顺序的依据。
	values.Add("z", "last")
	values.Add("tag", "go")
	values.Add("tag", "url")
	values.Add("a", "first")
	// Encode 负责键排序和 URL 转义，同时保留 tag 的值顺序。
	return values.Encode()
}

这个结果的确定性很适合生成请求日志、缓存键或签名输入，但要注意“稳定”不等于“所有值都自动排序”。如果 tag=go&tag=url 与 tag=url&tag=go 在业务上是两个不同请求，就不能为了追求字符串相同而排序值。

业务明确无序时，再复制并排序重复值

有些过滤条件是集合语义，例如标签选择只关心成员而不关心顺序。这时可以先复制一份 url.Values，再只排序指定键或全部值，避免修改调用方正在使用的切片：

package queryutil

import (
	"net/url"
	"sort"
)

func Canonical(values url.Values) string {
	cloned := make(url.Values, len(values))
	for key, source := range values {
		// 复制切片，避免排序时改动调用方的原始参数。
		cloned[key] = append([]string(nil), source...)
		// 只有业务把同名值定义为无序集合时才这样排序。
		sort.Strings(cloned[key])
	}
	// Encode 继续负责键排序和每个值的 URL 编码。
	return cloned.Encode()
}

这个函数适合把“值顺序无意义”的过滤条件归一化。它不适合权限范围、优先级列表或服务器约定顺序的参数；这些场景应该保留原始切片顺序，并把顺序纳入请求语义。

写回 URL 时使用 RawQuery，严格解析时使用 ParseQuery

从已有 URL 增加重复参数时，先通过 Query 拿到 Values，修改后再把 Encode 的结果写入 RawQuery。如果输入来自外部并且必须知道是否存在格式错误，则改用 url.ParseQuery；URL.Query 会静默丢弃格式错误的值对。

func addTags(rawURL string, tags []string) (string, error) {
	u, err := url.Parse(rawURL)
	if err != nil {
		// URL 本身解析失败时，不继续拼接查询字符串。
		return "", err
	}
	values := u.Query()
	for _, tag := range tags {
		// 每个标签都作为同名参数追加，而不是覆盖上一项。
		values.Add("tag", tag)
	}
	// RawQuery 只保存编码后的查询部分，不要手工拼接未转义字符串。
	u.RawQuery = values.Encode()
	return u.String(), nil
}

如果需要严格处理外部传入的查询文本，可以把 u.RawQuery 交给 url.ParseQuery，检查返回的错误后再决定是否继续。这样能把“可用参数”和“解析失败”分开，不会因为 Query 的静默丢弃而误判输入完整。

生产代码里的四个边界

把重复查询参数用于接口请求、缓存键或签名输入时，可以按下面四点收口：

最后还要限制可接受的键集合，并避免把令牌、密码等敏感值直接写入普通日志。url.Values 负责容器和编码，不负责替业务决定重复参数的合法性；稳定输出的关键，是先定义顺序语义，再选择是否排序。

常见问题

为什么连续调用 Set 后只剩一个查询参数？

因为 Set 会把键关联的全部旧值替换为新值。需要保留多个同名值时改用 Add。

Encode 会不会按值排序？

不会。它按键排序，并按每个键的值切片顺序展开。只有你在业务上确认值无序时，才应复制切片后自行排序。

Get 能拿到重复参数的全部值吗？

不能。Get 只返回第一个值；需要全部值时直接读取 values[key]，并根据业务规则处理空切片。

URL.Query 和 ParseQuery 有什么区别？

URL.Query 便于快速读取，但会静默丢弃格式错误的值对；需要检查解析错误时，直接调用 url.ParseQuery 并处理返回的 error。