Go url.URL Query 参数的稳定编码与排序方法

在 Go 中，查询参数不要用字符串拼接来“碰运气”排序。更稳妥的做法是把参数放进 url.Values，最后用 Encode() 生成 RawQuery：它会对键进行排序并完成 URL 编码；同一个键的多个值则按加入顺序保留。这样生成的地址适合请求、缓存键和需要重复计算的签名输入。

区分 URL.Query、RawQuery 和 url.Values

url.URL 的 RawQuery 是不带问号的原始编码字符串，例如 page=2&tag=go；Query() 会把它解析成 url.Values。后者本质是 map[string][]string，所以一个键可以有多个值，键名也区分大小写。

这几个对象不要混用：读取时可以调用 u.Query()，输出时应把编码后的结果赋给 u.RawQuery。直接改字符串会把空格、中文、斜杠和重复参数的处理责任推回业务代码。

用 Values.Encode 生成稳定的查询串

稳定编码的关键是只在最终边界调用一次 Encode。Set 覆盖同名参数，Add 追加同名参数，后者适合标签、批量 ID 这类天然多值字段：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    q := url.Values{}
    q.Set("page", "2")       // Set 覆盖旧值，适合唯一参数
    q.Add("tag", "go web")   // Add 保留多个值，空格会由 Encode 转义
    q.Add("tag", "url")
    q.Set("empty", "")       // 空字符串仍会编码为 empty=

    fmt.Println(q.Encode())    // 键按字典序输出，同键值按加入顺序输出
}

这段代码会得到类似 empty=&page=2&tag=go+web&tag=url 的结果。这里的稳定性来自键排序和确定的转义规则，不是来自 map 的遍历顺序。若业务协议要求同一个键的值也排序，需要先复制切片并由业务明确排序；不要误以为 Encode 会改变值的顺序。

规范化已有 URL 的 Query

已有地址可以先解析，再把修改后的 Values 一次性写回。这样既能保留路径、主机和片段，也能让查询串重新按规则编码：

package main

import (
    "fmt"
    "net/url"
)

func canonicalQuery(raw string) (string, error) {
    u, err := url.Parse(raw) // Parse 负责拆分 URL，各字段仍保持独立
    if err != nil {
        return "", err
    }
    q := u.Query()           // Query 返回可修改的 Values 副本
    q.Set("page", "2")      // 用 Set 避免旧 page 重复出现
    q.Add("scope", "read")  // Add 表示该键允许重复
    u.RawQuery = q.Encode()  // 只在写回边界编码一次
    return u.String(), nil
}

func main() {
    got, err := canonicalQuery("https://api.example.test/items?tag=go web&page=1")
    if err != nil {
        return // 生产代码应记录错误并交给调用方处理
    }
    fmt.Println(got) // 这里只展示结构化结果，不代表线上请求已执行
}

示例里的 api.example.test 只是文档占位域名，不是可访问的接口。真正发请求时仍要检查 HTTP 方法、超时和服务端返回；URL 规范化只解决参数表达，不会替代网络错误处理。

多值、空值与解析错误的处理清单

如果参数来自用户输入或第三方回调，建议显式调用 url.ParseQuery(u.RawQuery) 获取错误，再决定是拒绝请求还是保留合法字段。涉及签名时，还要固定参数是否允许空值、重复键和值排序规则，并在客户端与服务端使用同一套约定。

常见问题

Values.Encode 会按值排序吗？

不会。它按键排序，并按每个键对应切片的现有顺序输出值。值排序属于业务协议的一部分，需要业务代码先明确处理。

RawQuery 能直接写入已经编码的字符串吗？

可以，但调用方必须保证它是合法的编码查询串。更安全的日常写法是维护 url.Values，最后由 Encode 统一生成，避免二次编码。

为什么 Query 没有返回 error？

URL.Query() 是便捷读取方法，坏的参数对调用方不可见；需要审计或严格拒绝时，直接对 RawQuery 使用 url.ParseQuery 并处理返回错误。