Go net/url构造签名查询串时保持参数编码一致的方法

Go 用 net/url 生成签名查询串时，关键不是“把参数转成字符串”这么简单，而是让排序、编码和签名输入始终只有一个来源。推荐把业务参数先放进 url.Values，由 Values.Encode() 生成规范化查询串，再把这条已经编码的字符串同时用于签名和 URL.RawQuery。这样可以避开空格变成 + 还是 %20、键顺序不同、重复参数顺序变化等常见分歧。

先固定唯一的规范化查询串

url.Values 的底层是 map[string][]string，适合表达普通参数和重复键。它的 Encode() 会按键排序，并输出类似 bar=baz&foo=quux 的 URL encoded 形式。对签名接口来说，最重要的是不要依赖 Go map 的遍历顺序，也不要让调用方各自决定转义规则。

如果同一个键的多个值在业务上是无序集合，可以在放入 url.Values 前复制并排序；如果它们代表有先后关系的筛选条件或批量操作，则必须保留原顺序，并把这个约定写入协议。

package main

import (
    "fmt"
    "net/url"
    "sort"
)

// canonicalQuery 只对业务定义为无序的重复值排序，避免 map 顺序进入签名。
func canonicalQuery(params map[string][]string) string {
    values := make(url.Values, len(params))
    for key, items := range params {
        copied := append([]string(nil), items...)
        // 只有协议把重复值视为集合时才排序；有序列表不要这样做。
        sort.Strings(copied)
        for _, item := range copied {
            values.Add(key, item)
        }
    }
    return values.Encode()
}

func main() {
    params := map[string][]string{
        "scope": {"read", "write"},
        "note":  {"a+b / 中文"},
    }
    fmt.Println(canonicalQuery(params))
}

这段示例的输出顺序由键名决定，值中的加号、斜杠和中文也会由同一套查询编码规则处理。生产代码还应明确空值、缺失键和重复键的含义，不能把“空字符串”和“参数不存在”混为一谈。

区分查询参数编码与路径编码

QueryEscape 适合把一个字符串放进查询组件，QueryUnescape 是它的对应解码函数；而 PathEscape 面向 URL 路径段，两者的语义不能混用。尤其要注意，查询编码中的 + 会在 QueryUnescape 中还原为空格，真正的加号应以 %2B 进入查询串。

因此不要写出“先把整段查询串 QueryEscape，再手动拼键值”的组合，也不要把已经编码的值再次编码。最稳妥的边界是：业务层保存未编码的原始值，规范化层只调用一次 Values.Encode()，传输层直接使用结果。

签名和实际请求复用同一串

发送方应先构造 canonicalQuery，再把它原样交给签名函数和 RawQuery。不要先签名一份键值文本，再把参数重新放入 HTTP 客户端的结构化参数字段；后一个步骤可能改变空格、顺序或百分号表示。

package main

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

// sign 对规范化后的字节签名；签名函数不再接触未编码参数。
func sign(secret, canonical string) string {
    mac := hmac.New(sha256.New, []byte(secret))
    _, _ = mac.Write([]byte(canonical)) // hmac.Hash 的 Write 不会返回实际错误。
    return hex.EncodeToString(mac.Sum(nil))
}

// buildSignedURL 让 RawQuery 和 HMAC 使用同一个 canonicalQuery。
func buildSignedURL(base, secret string, params url.Values) (string, string, error) {
    parsed, err := url.Parse(base)
    if err != nil {
        return "", "", err
    }
    canonicalQuery := params.Encode()
    parsed.RawQuery = canonicalQuery
    return parsed.String(), sign(secret, canonicalQuery), nil
}

func main() {
    params := url.Values{}
    params.Set("action", "list")
    params.Set("filter", "a+b / 中文")
    requestURL, signature, err := buildSignedURL("https://api.example.test/items", "demo-secret", params)
    if err != nil {
        panic(err)
    }
    fmt.Println(requestURL)
    fmt.Println(signature)
}

示例里的域名只是占位地址，不代表真实服务。实际接入时，签名算法、密钥来源、签名字段名和时间戳窗口都应以服务端协议为准；这里要复用的核心只有一条：签名输入和发送出去的 RawQuery 必须来自同一变量。

接收端选择严格或兼容的验证边界

服务端收到请求后通常能从请求 URI 取得原始 RawQuery。严格协议可以先用 url.ParseQuery 解码，再调用 Encode() 得到规范串，并要求它与原始查询串完全一致；这样 q=a+b 和 q=a%20b 不会被当成两个都可签名的表示。

兼容旧客户端时，也可以允许多种等价编码，但必须约定“双方都对规范化结果签名”，并记录拒绝原因。ParseQuery 返回的是所有合法参数，同时会报告第一个解码错误；忽略这个 error 会把残缺查询当成完整请求。

// verifyCanonicalQuery 要求线上 RawQuery 就是 Values.Encode() 的结果。
func verifyCanonicalQuery(rawQuery, gotSignature, secret string) error {
    values, err := url.ParseQuery(rawQuery)
    if err != nil {
        return fmt.Errorf("解析查询串失败: %w", err)
    }
    canonical := values.Encode()
    if rawQuery != canonical {
        return fmt.Errorf("查询串不是规范编码")
    }
    expected := sign(secret, canonical)
    if !hmac.Equal([]byte(expected), []byte(gotSignature)) {
        return fmt.Errorf("签名不匹配")
    }
    return nil
}

这段接收端函数依赖前文的 sign，展示的是验证边界而不是完整 HTTP Handler。若协议规定重复键有序，就不能在发送端和接收端随意排序；若协议规定它们无序，则两端应使用同一排序规则，并覆盖空值、非 ASCII 文本、百分号和重复键测试。

常见问题

为什么同样的参数，签名有时只差一个字符？

优先比较原始查询串，重点看空格的 +/%20、加号的 %2B、键排序和重复值顺序。很多差异不是 HMAC 算法问题，而是签名前后发生了二次编码。

url.Values.Encode() 会不会按值排序？

它会按键排序；同一个键对应的切片顺序由调用方保留。值是否需要排序，取决于签名协议把重复参数定义为有序序列还是无序集合。

收到参数后直接用 r.URL.Query() 可以吗？

可以用于业务读取，但签名校验还要明确是否比较原始 RawQuery。只拿解析后的 map 做业务判断，不能证明客户端提交的编码形式符合严格签名协议。