Go url.QueryUnescape 遇到非法百分号编码时怎么定位错误

我在接收外部查询参数时，最容易被忽略的不是中文解码，而是一个孤零零的百分号：例如 name=%E4%B8 少了一个字节，或者 name=%QZ 根本不是十六进制转义。Go 的 url.QueryUnescape 遇到这类输入不会给出半截结果，而是返回空字符串和 url.EscapeError。真正稳妥的做法是保留原始值，记录错误片段，再决定拒绝、修复还是交给上游处理。

判断口诀：每个百分号后面必须紧跟两个十六进制字符；查询参数里的 + 会变成空格；失败时不要拿空字符串覆盖原始输入。

官方文档：https://pkg.go.dev/net/url#QueryUnescape

我先把原始查询值和解码结果分开

一次排查中，日志里只剩下了“解码后的值”，而没有收到的原文。这样一来，错误信息只能告诉我们存在非法转义，却很难判断是哪个字段、哪一段输入出了问题。后来我把数据流固定成三个对象：原始字符串、解码后的字符串、错误值。只要解码失败，原始字符串仍然可以用于日志关联和上游修复。

这个分层也让文章里的两张图有了明确用途：第一张解释函数的输入和分支，第二张说明错误处理时为什么要保留原文。它们都是静态说明图，不是浏览器、终端或 Go 运行结果截图。

QueryUnescape 的返回值为何看起来像“什么都没解析”

QueryUnescape 是 QueryEscape 的逆操作。合法的 %2F 会还原成 /，而查询组件里的 + 会还原成空格。它要求百分号后面必须是两个十六进制字符，所以 %G1、结尾只有一个 %、以及 %E4%B8 都会失败。

失败时，标准库的解码函数返回的是空字符串和 EscapeError，不是“已经解码了一半的字符串”。因此下面这个写法有一个隐蔽问题：如果调用方忽略 err，就会把空字符串当成合法用户输入。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    samples := []string{"name=Go+教程", "path=%2Fapi%2Fv1", "bad=%G1", "short=%E4%B8"}
    for _, raw := range samples {
        value, err := url.QueryUnescape(raw)
        if err != nil {
            // 失败时保留 raw，不能用空字符串覆盖收到的原文。
            fmt.Printf("raw=%q decode failed: %v\n", raw, err)
            continue
        }
        // 成功结果可以交给后续业务，但 raw 仍建议保留在请求上下文中。
        fmt.Printf("raw=%q value=%q\n", raw, value)
    }
}

这里的 + 并不是所有 URL 部分都一样。PathUnescape 与 QueryUnescape 都会处理 %XX，但前者不会把加号改为空格。如果输入来自查询参数，优先使用 query 语义的函数；如果是在处理路径片段，再考虑路径语义。

把错误片段映射回原始字节位置

EscapeError 的错误文本会带上触发失败的片段，例如 invalid URL escape "%QZ"。它并不直接暴露字节下标，所以我通常先用 errors.As 取出错误类型，再对原始字符串做一次很小的扫描，把坏片段的起始位置和附近上下文放进日志。这样做不是重新实现解码，而是为排障补充定位信息。

package main

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

func isHex(c byte) bool {
    // 百分号编码只允许 ASCII 十六进制字符。
    return ('0' = len(raw) || !isHex(raw[i+1]) || !isHex(raw[i+2]) {
            end := i + 3
            if end > len(raw) {
                end = len(raw)
            }
            return i, raw[i:end], true
        }
        // 当前转义完整，跳过它的两个十六进制字节。
        i += 2
    }
    return -1, "", false
}

func main() {
    raw := "name=Go%20教程&next=%QZ"
    _, err := url.QueryUnescape(raw)
    if err == nil {
        fmt.Println("decode ok")
        return
    }

    var escapeErr url.EscapeError
    if errors.As(err, &escapeErr) {
        // 标准库错误保留坏片段；扫描结果补充它在原文中的字节位置。
        index, fragment, found := badEscapeAt(raw)
        fmt.Printf("fragment=%q error=%v\n", string(escapeErr), err)
        if found {
            fmt.Printf("byte_index=%d raw_fragment=%q\n", index, fragment)
        }
    }
}

示例中的扫描只关心百分号转义，不会把它当成第二套 URL 解码器。日志里同时保留标准库给出的坏片段和原文位置，遇到多个字段时还应该把字段名、请求标识等上下文一起记录。

ParseQuery 为什么可能“有值但仍然返回错误”

如果输入是一整段查询字符串，常见入口会变成 url.ParseQuery。它会逐项拆分键和值，分别调用 QueryUnescape；某一项出错时会记录错误并继续处理后面的项。因此返回的 url.Values 可能已经包含部分成功字段，同时函数仍然返回非空错误。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    values, err := url.ParseQuery("ok=1&bad=%QZ&name=Go+教程")
    // 允许保留 values 供诊断，但不能因为存在部分数据就当作整段输入有效。
    fmt.Printf("values=%v err=%v\n", values, err)
    if err != nil {
        // 生产接口通常在这里拒绝请求，并记录未解码的原始 query。
        fmt.Println("query contains an invalid escape")
    }
}

我的判断是：批量导入或后台排障可以把部分成功值放进诊断结果；鉴权、签名、路由和金额等边界则应该把整个 query 当作一个输入单元，只要返回错误就拒绝继续执行业务。

这几个处理习惯能减少二次事故

• 保留原始输入：解码前复制或记录必要的原文，不要只保存解码后的空字符串。
• 只解码一次：重复调用可能把原本合法的字面量百分号当成新的转义入口，边界代码要约定所有权。
• 区分 query 和 path：查询里的加号通常代表空格，路径中的加号通常就是加号。
• 不要静默替换：把 %QZ 改成普通文本会丢失上游错误，应该返回可理解的 4xx 或进入明确的修复流程。
• 记录坏片段而非整段敏感值：如果 query 可能包含隐私字段，只记录字段名、错误片段和请求关联标识。

最后的速查表

对我来说，定位非法百分号编码的关键不是“想办法让它解码成功”，而是让输入、错误和后续决策彼此可追溯：原始值留在边界，EscapeError 说明坏片段，必要时再用字节扫描补上下标，最终由业务层明确选择拒绝或修复。

相关问题

• 为什么 QueryUnescape 会把加号变成空格？因为它采用查询组件语义；处理路径片段时应比较 PathUnescape 的行为。
• 错误时可以使用返回字符串吗？不建议。标准库在非法转义时返回空字符串，调用方应该优先处理错误并保留原始输入。
• ParseQuery 有部分值时算成功吗？不算。它可能保留已解析字段，但非空错误仍表示整段查询存在问题。