Go 怎样稳定编码重复查询参数

我在给 Go 请求拼筛选条件时，最容易踩的坑不是转义，而是把重复参数当成普通字符串处理。只要参数可能出现 tag=go&tag=web 这样的形式，就应该让 url.Values 保存一个键对应的多个值，再由 Encode 统一生成查询串。这样键的排列是稳定的，同一个键下的值也会按加入顺序保留。

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

本文只讨论重复查询参数和编码顺序；示例中的域名与参数是教学数据，不代表实际接口。

为什么重复参数要用 Add

url.Values 的本质是 map[string][]string：一个键可以对应一个字符串切片。我的经验是，单值参数用 Set，可重复参数从一开始就用 Add，不要先拼成逗号分隔的字符串再交给服务端猜。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    values := url.Values{}
    // Set 表示这个键只保留一个值，重复调用会覆盖旧值。
    values.Set("page", "2")
    // Add 追加同一个键的值，适合多选标签或重复过滤条件。
    values.Add("tag", "go")
    values.Add("tag", "web")

    // Encode 负责统一转义并生成可放进 URL 的查询串。
    fmt.Println(values.Encode())
}

这段代码的结果中，tag 会出现两次，而不是变成一个无法区分的 go,web。当服务端按多值参数解析时，这种表达更直接，也不会因为标签本身含有逗号而产生歧义。

Encode 为什么能稳定排列查询参数

Values.Encode() 会先按键排序，再输出每个键对应的值。也就是说，page、tag、sort 在 map 中的插入先后不会改变键的排列；但同一个键的值切片仍然按照加入顺序输出。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    values := url.Values{}
    // 故意按非字典顺序写入，观察 Encode 的键排序规则。
    values.Add("sort", "desc")
    values.Add("tag", "go")
    values.Add("tag", "web")
    values.Add("page", "2")

    // 同键值顺序仍是 go、web，键本身按 Encode 的规则排列。
    fmt.Println(values.Encode())
}

因此，应该把“稳定”理解为两层：键的顺序由编码器统一整理，同键值的顺序由切片维护。若业务要求标签本身也按字典序排列，需要在调用 Add 之前自行排序；Encode 不会替你重排同一个键的值。

把 Encode 结果交给 URL

如果已经有一个 url.URL，不要手写 ?tag=go&tag=web，直接把编码结果放进 RawQuery。这样路径、查询参数和转义各自有清晰的责任边界。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    endpoint := url.URL{
        Scheme: "https",
        Host:   "api.example.test",
        Path:   "/items",
    }
    values := url.Values{}
    // 空格、中文和特殊字符交给 Values 编码，不手写百分号转义。
    values.Add("tag", "Go 基础")
    values.Add("tag", "web/api")
    values.Set("page", "2")

    // RawQuery 只接收不带问号的编码结果。
    endpoint.RawQuery = values.Encode()
    fmt.Println(endpoint.String())
}

这里的关键边界是：RawQuery 要填查询串本身，不要再加一个 ?；而 URL.String() 会负责把它放到 URL 的问号后面。接口签名、签名串或缓存键如果依赖查询参数文本，就应统一从同一份 Values 编码，避免一处手写、一处库编码造成差异。

Set、Add、Get 和直接读取该怎么选

我通常会在函数边界处决定参数是否允许重复：允许就接收或返回 []string，不允许就用 Set 并在业务层拒绝多余输入。不要因为 Get 返回了第一个值，就误以为 URL 中只有一个同名参数。

两个容易忽略的边界

第一，url.Values 的键区分大小写，Tag 和 tag 是两个不同键；第二，Encode 只负责生成编码结果，不负责判断服务端是否接受重复参数。服务端契约若要求逗号列表、JSON 数组或单值字段，客户端就要按契约选格式。

如果把编码结果用于签名，除了键排序，还要确认签名协议是否规定同键值排序、空值处理和空格编码方式。Go 的 Encode 适合生成标准查询串，但不能代替第三方协议的规范化规则。

为什么我明明 Add 了两个值，Get 只返回一个？

因为 Get 的语义就是取该键的第一个值。需要完整列表时读取 values[key]，或遍历这个切片。

Encode 会按 Add 的顺序输出所有参数吗？

不会。键会按排序后的顺序输出；同一个键下的多个值才保持切片顺序。要让同键值也稳定排序，应在写入前准备好确定顺序的切片。

RawQuery 里要不要手动加问号？

不要。给 RawQuery 赋值时只放 values.Encode() 的结果，问号由 URL.String() 组合。

参考资料：https://pkg.go.dev/net/url#Values