Go url.ParseQuery 遇到非法百分号时怎么保留有效参数

网关接收回调地址时，查询串里只要出现一个写坏的百分号，就很容易把“部分参数有效”和“整条请求失败”混成同一个结论。Go 的 url.ParseQuery 实际提供了更细的边界：它始终返回非 nil 的 url.Values，把能解码的参数保留下来，同时返回遇到的第一个解码错误。也就是说，不能因为 err != nil 就直接丢掉 map，也不能因为 map 有值就假装请求完全正常。

先看清 ParseQuery 的返回边界

先把问题缩小到一个混合查询串：前后有合法字段，中间故意放入 %ZZ。这个百分号后面不是两个十六进制数字，因此解码失败。关键观察点有两个：有效字段是否还在，以及错误是否只描述首个失败。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    raw := "page=2&tag=go%2Burl&bad=%ZZ&lang=zh"

    // 保留 Values 和 error 两个返回值，不要只写成 values, _。
    values, err := url.ParseQuery(raw)
    fmt.Println("values:", values)
    fmt.Println("error:", err)
}

在这个例子里，page、tag 和 lang 都是可解码项，bad 这一项被跳过；tag 中的 %2B 会还原为字面量加号。返回错误表示输入存在问题，但不等于所有字段都失效。

为什么非法字段会被跳过，而不是污染整个 Values

ParseQuery 处理的是 URL 编码的查询串，参数之间以 & 分隔；没有等号的项会被当作空值。源码中的解析逻辑会分别对键和值调用 QueryUnescape，某一项解码失败时记录错误并继续看后面的项，成功项才会写入 Values。所以它的契约可以压缩成下面这张表：

这里还有一个容易踩的坑：不要用 strings.ReplaceAll(raw, "+", " ") 或自行按字符替换来“修复”查询串。加号、百分号和路径段的语义属于不同边界；应让 net/url 负责查询组件的解码，再在业务层做字段校验。

高并发入口如何决定拒绝还是降级

在高并发回调入口，最稳妥的做法不是统一选择“有错就拒绝”或“有值就放行”，而是让字段风险决定策略。搜索筛选、分页和展示偏好通常可以采用安全白名单降级；签名、租户、权限、订单金额等字段只要解析出现错误，就不应继续使用部分结果。

func parsePublicQuery(raw string) (url.Values, error) {
    values, err := url.ParseQuery(raw)
    if err != nil {
        // 原始串只用于受控日志或关联 ID，避免把敏感参数完整打入日志。
        return values, fmt.Errorf("query decode failed: %w", err)
    }
    return values, nil
}

func readPage(raw string) (int, error) {
    values, err := url.ParseQuery(raw)
    if err != nil {
        // page 是低风险字段时可以降级，但仍需记录错误并限制默认值。
        values = url.Values{}
    }
    page := 1
    if text := values.Get("page"); text != "" {
        if _, scanErr := fmt.Sscanf(text, "%d", &page); scanErr != nil || page  100 {
            page = 1
        }
    }
    return page, err
}

示例中的降级只适合低风险读取接口，而且把默认值、范围和错误记录放在同一层。若业务必须区分“没有传 page”和“page 解码失败”，就不要只返回整数，还应返回一个状态值，避免调用方再次猜测。

把边界写进测试和日志，而不是留给线上猜

回归用例至少覆盖四类输入：合法百分号编码、非法百分号、重复键和未编码分号。测试断言不要只检查 err，还要检查有效项是否保留、坏项是否没有进入结果，以及敏感字段是否触发拒绝策略。日志中保留请求关联 ID、错误类型和字段名即可；原始查询串若可能含 token、手机号或签名，应先脱敏。

func checkQuery(raw string) (url.Values, error) {
    values, err := url.ParseQuery(raw)
    if err != nil {
        // 只记录错误类别和关联信息，避免把完整查询串当作普通日志。
        return values, err
    }
    return values, nil
}

最终的判断顺序可以简化为：先保留 Values 与 error，再确认错误涉及哪个字段，最后按字段风险选择拒绝或降级。这样既不会误伤一条含无关坏参数的普通请求，也不会让关键字段借助“map 还有值”绕过校验。

相关问题

ParseQuery 返回 error 时，Values 还能使用吗？

可以使用其中已成功解码的参数，但必须先确认业务允许部分结果，并对敏感字段重新做必填、格式和权限校验。

为什么 %2B 和裸加号的结果不同？

查询组件的解码规则会把裸加号解释为空格；%2B 表示编码后的字面量加号。需要传递加号时，应在生成查询串的一侧使用 url.QueryEscape 或 Values.Encode。

遇到坏参数时能不能把整段查询串重新编码？

不建议。重新编码会改变输入语义，也可能掩盖攻击或客户端 bug；应保留错误并按字段策略处理。