Go net/url Values.Encode 如何固定查询参数顺序

如果你用 Go 组装请求参数，先记住一个容易被误解的结论：url.Values.Encode() 能固定的是参数 key 的字典序，不是任意自定义顺序。相同 key 对应的多个值仍按切片顺序输出；如果第三方接口或签名协议要求“时间戳在前、签名在后”这类顺序，就不能指望 map 本身提供这层语义。

官方地址：https://pkg.go.dev/net/url

Values.Encode 固定的是 key 顺序，不是 map 遍历顺序

url.Values 的底层类型是 map[string][]string。Go 的 map 遍历顺序不应被业务依赖，所以 Encode 会先把所有 key 放入切片，再按字符串升序排列。这样即使插入顺序不同，只要 map 内容相同，普通查询字符串就能得到稳定结果。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	values := url.Values{}
	// Set 写入单值，Add 追加同一个 key 的多个值。
	values.Set("page", "2")
	values.Add("tag", "go")
	values.Add("tag", "url")
	values.Set("q", "net/url")

	// Encode 按 key 排序；同一 key 的值沿用切片顺序。
	fmt.Println(values.Encode())
}

这段代码的结果是 page=2&q=net%2Furl&tag=go&tag=url。注意排序发生在原始 key 上，斜杠等特殊字符则由查询参数编码处理；tag 的两个值没有因为 key 排序而互换。

普通请求直接使用稳定结果，别再手动排序一遍

对于常规 GET 请求，可以把 Encode 的结果直接交给 url.URL.RawQuery。Set 适合覆盖一个字段，Add 适合表达重复参数；如果直接写入 map，也要明确维护 []string 的业务顺序。

func buildURL(values url.Values) string {
	base, err := url.Parse("https://api.example.test/items")
	if err != nil {
		// 固定地址解析失败属于程序配置错误，不能带着半成品继续请求。
		panic(err)
	}
	base.RawQuery = values.Encode()
	return base.String()
}

这里不要再对完整查询串调用一次 url.QueryEscape，否则 & 和 = 也会被当成普通字符转义。编码应该发生在 key 和 value 这一层，而不是把已经组装好的查询串当成一个 value。

需要自定义顺序时，显式维护有序 key 列表

有些旧接口、验签文档或测试快照要求固定的非字典序。这时要把“顺序”从 map 中拿出来，单独保存为 []string。下面的最小实现仍复用 QueryEscape，只改变 key 的读取顺序；同一 key 的多个值仍按原切片顺序追加。

func encodeInOrder(values url.Values, order []string) string {
	parts := make([]string, 0, len(values))
	for _, key := range order {
		// 缺失 key 或空切片不会凭空生成参数片段。
		for _, value := range values[key] {
			// 只编码 key/value，避免把 & 和 = 一起转义。
			parts = append(parts, url.QueryEscape(key)+"="+url.QueryEscape(value))
		}
	}
	return strings.Join(parts, "&")
}

完整代码还需要导入 strings。例如把 order 设为 []string{"timestamp", "page", "sign"}，结果就会按这三个 key 的顺序生成，而不会被 Encode 改成字典序。order 最好来自明确的协议常量，别让调用方每次临时拼出一套不一致的顺序。

签名和重复参数要先写清楚规范化边界

“顺序固定”不等于“所有字段都排序”。验签前至少要确认四件事：key 是否按字典序、重复值是否按业务顺序、空值是否保留，以及空切片是否代表缺失。直接把业务参数交给排序函数，可能让请求看起来更稳定，却改变了服务端对重复字段的解释。

还有一个细节：url.Values 只会为实际遍历到的值生成片段。values["flag"] = []string{""} 会得到 flag=，而空切片不会输出 flag。如果服务端把“缺失”和“空值”区分开，这个差异要在测试用例中固定下来。

常见问题

能不能通过调整 Add 的调用顺序改变不同 key 的顺序？

不能。不同 key 最终按字典序排列；Add 的调用顺序只影响同一个 key 对应的值切片。

Values.Encode 会按 value 再排序吗？

不会。它按 key 排序，然后遍历每个 key 的 []string。如果协议要求 value 排序，需要复制切片后单独处理。

为什么不直接拼接字符串？

手写拼接很容易漏掉空格、斜杠、中文和 & 的转义。普通请求使用 Values.Encode，只有协议确实要求自定义顺序时才保留一个小型的有序封装。