net/url 解析原始查询参数并保留编码信息

在 Go 里处理 URL 查询参数，最容易踩的坑是把“原始编码文本”和“解码后的业务值”当成同一种数据。更稳妥的做法是：需要保留签名、缓存键或审计原文时读取 u.RawQuery；需要业务筛选时使用 url.ParseQuery(u.RawQuery) 并检查错误；只有明确接受静默丢弃异常片段时，才使用 u.Query()。

一句话记忆：RawQuery 保留原样，Query 方便但不报告解析错误，ParseQuery 同时给出有效值和错误。重复参数不要用 Get 代替 map 切片读取。

先分清原始查询与解码结果

url.Parse 会把问号之后的内容放到 URL.RawQuery，这个字段不包含开头的 ?，仍然保留百分号编码。u.Query() 实际上基于 RawQuery 调用解析逻辑，但会忽略错误；url.ParseQuery 则返回有效的 url.Values 和错误值，适合生产入口做明确决策。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // 原始串保留 %2B 等编码，适合参与签名或写入审计日志。
    raw := "https://example.com/callback?token=a%2Bb&tag=go&tag=url"
    u, err := url.Parse(raw)
    if err != nil {
        panic(err)
    }

    // Query 适合简单业务读取，但不会把异常片段的错误交给调用方。
    fmt.Println("raw:", u.RawQuery)
    fmt.Println("query tag:", u.Query()["tag"])

    // ParseQuery 保留所有有效键值，并让入口决定是否拒绝异常输入。
    values, err := url.ParseQuery(u.RawQuery)
    if err != nil {
        panic(err)
    }
    fmt.Println("token:", values.Get("token"))
    fmt.Println("all tags:", values["tag"])
}

这个例子里，RawQuery 是 token=a%2Bb&tag=go&tag=url，而业务值中的 token 是 a+b。同一个参数在原始层和业务层的形态不同，日志、签名和过滤器应明确使用哪一层。

用 ParseQuery 保留重复值并处理错误

url.Values 的本质是 map[string][]string。因此 tag=go&tag=url 不应该只调用 Get("tag")，否则只会得到第一个值。对重复参数有业务意义的场景，例如多标签、多个范围或多个回调目标，应直接读取切片。

package main

import (
    "fmt"
    "net/url"
)

func parseTags(rawQuery string) ([]string, error) {
    // ParseQuery 会返回已成功解析的值，同时报告第一个解码错误。
    values, err := url.ParseQuery(rawQuery)
    if err != nil {
        return nil, fmt.Errorf("解析查询参数失败: %w", err)
    }

    // 直接读取切片，避免 Get 丢失同名参数的后续值。
    tags := append([]string(nil), values["tag"]...)
    return tags, nil
}

func main() {
    tags, err := parseTags("tag=go&tag=url&scope=backend")
    if err != nil {
        panic(err)
    }
    fmt.Println(tags)
}

如果请求来自外部客户端，建议把解析错误转换成明确的 400 响应或审计事件，而不是继续执行一个可能缺少条件的查询。错误分支应包含原始请求的关联 ID，不要把 token 等敏感值直接写入日志。

按用途选择数据形态

生产代码可以把用途分成三类：签名和缓存键依赖字节级稳定性，应使用 RawQuery；业务筛选依赖解码后的值，应使用 ParseQuery；审计既要记录原文，又要记录结构化字段，应该同时保留原始串和经过脱敏的 Values，而不是只记录其中一个。

处理分号、加号和异常百分号

查询值中的加号按表单查询语义通常会解码为空格，因此需要表达字面量加号时应使用 %2B。未编码的分号会使相关设置无效并产生错误；孤立的百分号或后面不是两位十六进制字符时，也应视为输入错误。不要先用字符串替换手动“修复”编码，否则可能改变签名原文。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // %2B 表示字面量加号，普通 + 会按查询表单规则解码为空格。
    raw := "name=A+B&literal=A%2BB&broken=%ZZ"
    values, err := url.ParseQuery(raw)

    // 先输出结构化结果，再根据错误决定是否拒绝请求。
    fmt.Printf("values=%#v\n", values)
    if err != nil {
        fmt.Println("reject malformed query:", err)
    }
}

是否拒绝应由接口契约决定：严格的签名回调、管理接口和分页参数通常应拒绝；兼容历史客户端的查询入口可以记录错误并采用降级策略，但要把降级范围写清楚，不能让每个调用点各自猜测。

把解析策略封装成可审计的请求入口

建议在 HTTP handler 进入业务层之前完成解析，返回一个只暴露必要字段的结构体。这样签名校验可以拿到原始查询，业务代码只接收规范化后的切片，错误处理和日志脱敏也集中在一处。

type QueryInput struct {
    Raw string
    Tags []string
}

func buildQueryInput(u *url.URL) (QueryInput, error) {
    // 保留原始串供验签或关联审计，但不把它直接打印到日志。
    values, err := url.ParseQuery(u.RawQuery)
    if err != nil {
        return QueryInput{}, fmt.Errorf("invalid query: %w", err)
    }

    // 复制切片，避免后续代码意外修改解析结果的底层数组。
    tags := append([]string(nil), values["tag"]...)
    return QueryInput{Raw: u.RawQuery, Tags: tags}, nil
}

在真正的 handler 中，先做请求大小、参数数量和敏感字段脱敏，再把 QueryInput 传给业务服务。这样做不是为了增加抽象层，而是为了让“原始值用于什么、解码值用于什么”成为可以审查的接口契约。

常见误区与结论

• 误区一：把 RawQuery 当成已经解码的 map。它仍是问号后的编码文本。
• 误区二：用 Query().Get 处理重复键。它只返回第一个值，应该读取 Values[key]。
• 误区三：遇到坏参数仍使用 Query。需要错误信息时改用 ParseQuery。
• 误区四：先手工替换 +、% 再解析。这样可能破坏原始签名和错误定位。

最终可以用一条工程规则收尾：原始查询用于证明“请求带来了什么”，解析后的 Values 用于表达“业务要使用什么”。两者同时存在并不重复，关键是不要在签名、缓存、审计和业务筛选之间交叉使用。

相关问题

RawQuery 会包含开头的问号吗？

不会。URL.RawQuery 保存的是问号之后的编码查询串；需要重新拼接 URL 时由 URL.String 负责补上问号。

为什么 Query 没有返回 error？

它是便捷方法，会静默丢弃格式错误的值对。对外部输入做严格处理时直接调用 url.ParseQuery。

如何保留同一个参数的多个值？

使用 values["tag"] 读取切片，不要只使用 values.Get("tag")。