Go url.Values.Encode 如何保证签名参数排序稳定

接口签名最怕的不是哈希算法写错，而是客户端和服务端拿到的“原文”不一样。Go 的 url.Values.Encode() 很适合生成查询参数的规范化文本：它会把 key 按字典序排列，并对 key、value 做 URL 编码。但这个保证有边界：同一个 key 的多个 value 仍按切片顺序输出，sig 是否排除、摘要算法和最终传输位置也不会由它自动决定。

要让签名参数排序稳定，先把业务参数放进同一个 url.Values，排除签名字段后只调用一次 Encode()，客户端和服务端都对这份完全相同的字符串计算签名。

url.Values.Encode 稳定的是键顺序，不是整个签名协议

url.Values 本质上是 map[string][]string。直接遍历 map 得不到可依赖的顺序，而 Encode() 会先整理 key，再输出类似 bar=baz&foo=quux 的 URL encoded 文本。因此参数插入顺序变化，只要 key 和 value 集合没有变化，单值参数通常仍得到同一串结果。

这里的“排序”只针对 key。空格、斜杠、美元符号等特殊字符还会经过查询字符串编码，签名协议必须把编码后的文本作为约定的一部分。服务端若先解码再用另一套规则拼接，哪怕业务含义相同，字节级签名也会不同。

生成签名时只对同一份规范化字符串计算摘要

比较稳妥的做法是把签名字段从参数容器中删除或单独保存，再把剩余参数编码一次。下面的示例把 HMAC-SHA256 作为示意算法；实际接口若规定了拼接前缀、换行符或十六进制大小写，应以接口协议为准。

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "net/url"
)

func signQuery(secret string, values url.Values) (string, string) {
    // Clone 后移除 sig，避免把旧签名再次放进待签名原文。
    unsigned := values.Clone()
    unsigned.Del("sig")
    // Encode 同时完成 key 排序和查询参数编码，结果就是唯一原文。
    canonicalQuery := unsigned.Encode()

    mac := hmac.New(sha256.New, []byte(secret))
    // 摘要必须读取与请求发送时完全相同的 canonicalQuery。
    _, _ = mac.Write([]byte(canonicalQuery))
    signature := hex.EncodeToString(mac.Sum(nil))
    return canonicalQuery, signature
}

func main() {
    values := url.Values{}
    values.Set("page", "2")
    values.Set("q", "go")
    values.Set("sig", "old-value")
    query, signature := signQuery("demo-secret", values)
    fmt.Println(query, signature)
}

这个写法的关键不是 HMAC 这一行，而是把 canonicalQuery 当作单一事实来源：签名使用它，请求的 query 也使用它。不要先对 Encode() 的结果做一次字符串替换，再把替换后的另一份文本发送出去。

重复参数和特殊字符要先定协议再写代码

Add("tag", "go") 和 Add("tag", "http") 会形成两个同名参数；如果改用 Set()，前一个值会被替换。签名接口若允许重复参数，应固定 value 的顺序，并让验签端按同样顺序构造 tag=go&tag=http。若接口只接受单值字段，则应在进入签名函数前拒绝重复 key，而不是悄悄取第一个值。

func buildValues() url.Values {
    values := url.Values{}
    // Add 保留同名参数的业务顺序，适用于协议明确允许重复 key 的场景。
    values.Add("tag", "go")
    values.Add("tag", "http")
    // Set 会覆盖已有切片；单值字段才使用它，避免误删业务值。
    values.Set("page", "2")
    // 空值也属于输入，是否省略必须由服务端协议决定。
    values.Set("cursor", "")
    return values
}

还要注意不要混用不同的转义规则：查询参数使用 QueryEscape 的约定，路径参数则是另一层语义。把已经编码的值再次传给 Set()，可能得到双重编码；签名前后的日志应记录字段名、规范化字符串和摘要输入长度，但不要记录真实密钥。

用客户端与服务端契约做回归检查

回归测试至少覆盖：不同插入顺序的普通 key、重复 key、空值、空格、/、+ 和非 ASCII 字符。测试断言应比较规范化字符串本身，再比较摘要；只比较最终 HTTP URL，往往看不出到底是排序、编码还是签名字段处理出了差异。

• 客户端记录的待签名串与服务端验签前重建的串必须逐字节一致。
• 服务端不要先把 query 解码成另一种 map，再自行拼接一遍，除非协议明确如此。
• sig、时间戳和 nonce 的纳入范围要写进接口契约，并为缺失、重复和过期情况分别测试。

常见问题

Encode 会把所有参数值也按字典序排序吗？

不会。它保证 key 的排序；同一个 key 对应的多个 value 仍按切片顺序输出。

签名时可以直接对原始 URL 做摘要吗？

只有接口协议明确规定原始 URL 才可以。更常见的做法是先确定字段集合和 URL 编码规则，再对统一的规范化 query 摘要。

为什么把 sig 放进 Values 后再 Encode 会验签失败？

因为客户端计算签名时通常不应把签名本身作为输入；服务端若排除它而客户端没有排除，双方的原文自然不同。

空参数要不要删除？

不要自行猜测。key= 和缺少 key 是两种输入，是否等价必须由接口协议和服务端实现共同约定。