Go url.Values 怎么传重复参数：Add、Set 与服务端解析边界

标签筛选接口经常需要传多个同名参数，例如 label=go&label=http。在 Go 里，url.Values 能准确表达这种数据，但 Add 和 Set 的区别很容易让“多选”变成“只剩最后一项”。真正要核对的不是 URL 看起来长不长，而是构造、编码、服务端解析后的值是否一路一致。

需要保留同名参数的每个值时用 Add；需要把一个键替换成唯一值时用 Set。发送前检查 Encode，接收端用 Query().Get 还是取完整切片，也要和接口约定保持一致。

先把同名参数的接口约定写清楚

下面用商品列表接口举例：前端可以一次筛选多个标签，约定格式是 /products?label=go&label=http&sort=latest。这和逗号拼接的 label=go,http 是两种不同协议，服务端不能凭感觉混着解析。

用 Add 和 Set 区分追加与覆盖

url.Values 的底层可以理解为 map[string][]string。同一个键对应一组值，所以多选参数要追加，单值参数要覆盖：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    q := url.Values{}
    q.Add("label", "go")
    q.Add("label", "http")
    q.Set("sort", "latest")

    fmt.Println(q.Encode())
    // label=go&label=http&sort=latest
}

如果把第二次调用写成 q.Set("label", "http")，前一个 go 就会被替换。这个错误通常不会触发异常，只会让筛选结果悄悄变少，因此单元测试应该直接断言完整 URL 或解析后的切片。

Encode 负责编码，不负责替你定义协议

Encode 会对空格、中文和保留字符进行 URL 编码，并按键名排序。排序是为了让结果稳定，不能据此推断业务参数的顺序；同一个键的多个值仍然由切片顺序决定。

q := url.Values{}
q.Add("label", "Go 网络")
q.Add("label", "a&b")
rawQuery := q.Encode()
// label=Go+%E7%BD%91%E7%BB%9C&label=a%26b

不要把用户输入直接拼到 "?label=" + value 后面。除了中文和空格，&、=、+ 都可能被误读成参数边界或空格。构造阶段统一使用 Values，接口日志里再记录编码后的查询串。

服务端取值时别把 Get 当成全部结果

接收端的 url.Values 同样保存切片。Get 只是方便读取第一个值，适合 sort 这类单值字段；多选标签要直接取键对应的切片，并限制数量和长度：

func labelsFromRequest(r *http.Request) ([]string, error) {
    values := r.URL.Query()["label"]
    if len(values) > 20 {
        return nil, fmt.Errorf("too many labels")
    }
    for _, label := range values {
        if len(label) == 0 || len(label) > 32 {
            return nil, fmt.Errorf("invalid label")
        }
    }
    return values, nil
}

还要区分“键不存在”和“键存在但值为空”。Query()["label"] 在没有该键时返回 nil，但传入 ?label= 时会得到包含空字符串的切片。这个差异会影响“未筛选”和“筛选空标签”的业务语义。

四个容易漏掉的边界

• 调用顺序。Add 的值按追加顺序保留；如果服务端把顺序当作优先级，就把这一点写进接口测试。
• 空格编码。Encode 对查询参数中的空格使用 + 表示，服务端应使用标准解析器还原，不要手写替换。
• 数量上限。多选参数必须限制键数量、单项长度和总查询串大小，避免把解析后的切片直接交给昂贵查询。
• 重复键策略。如果接口只允许单值，就在服务端拒绝重复键或明确取首值；不要让不同语言客户端各自猜规则。

常见问题：url.Values 该怎么选方法

多选参数能不能用逗号拼接？

可以，但那是另一种接口约定。逗号本身出现在值里时还要再设计转义规则；如果服务端天然支持重复键，Add 更直接。

Set 会不会增加一个新值？

当键不存在时会创建一个值；当键已经存在时会清空旧切片再放入新值。因此它表达的是“这个键最终只有一个值”。

为什么 Get 读不到第二个 label？

Get 只返回第一个值。需要全部值时使用 r.URL.Query()["label"]，并在业务层完成去重、数量限制和合法性校验。

Encode 的参数顺序能当作业务顺序吗？

不能把键名排序当成业务排序。若参数顺序有意义，应在同一个键的切片顺序或独立的优先级字段中表达，并由服务端明确解释。

把查询参数当成一条可验收的数据链

这类问题最适合用三段断言验收：构造端断言 Values 里的切片内容，传输端断言 Encode 后的查询串，接收端断言 Query()["label"] 的完整结果。只检查最终列表数量不够，因为“少传一个标签”和“业务确实没有匹配项”会得到同样的空结果。