Go url.PathUnescape 遇到不完整百分号编码怎样处理

在 Go 里处理路径参数时，url.PathUnescape 遇到不完整的百分号编码不会“尽量还原”，而是返回错误。只要输入中出现一个 %，后面不是两个十六进制字符，就应该把它当作坏路径处理，不要继续把解码结果交给路由、文件访问或权限判断。

官方地址：https://pkg.go.dev/net/url#PathUnescape

最稳妥的写法是始终同时接收解码字符串和 error：error 不为空就结束当前请求；只有 error 为空时，解码后的路径才可以进入后续业务逻辑。

PathUnescape 的错误边界在哪里

PathUnescape 是 PathEscape 的逆变换。它把形如 %AB 的三个字符转换成一个字节；但百分号后缺少两个字符，或者字符不是十六进制数字时，函数会返回错误。常见坏输入包括 docs%、docs%2 和 docs%GG。

这里的关键不是“错误字符串长什么样”，而是不要把第二个返回值丢掉。路径解码失败通常意味着输入在上游被截断、重复编码处理顺序不对，或者有人把查询参数规则误用到了路径上。

用返回值和 error 一起判断

下面的函数把解码封装在一个小边界里：成功时返回路径，失败时保留原始输入和错误上下文。示例没有把错误当成普通字符串继续拼接，也没有尝试删除百分号来“修复”输入。

package main

import (
    "fmt"
    "net/url"
)

// decodePath 只负责路径解码；失败时把原始输入放进错误上下文。
func decodePath(raw string) (string, error) {
    decoded, err := url.PathUnescape(raw)
    if err != nil {
        // 不修改坏输入，交给上层决定返回 400 或记录诊断信息。
        return "", fmt.Errorf("路径编码无效 %q: %w", raw, err)
    }
    return decoded, nil
}

func main() {
    path, err := decodePath("reports/%2F2026%2Foct")
    if err != nil {
        // 错误分支不能继续访问路由或文件系统。
        fmt.Println(err)
        return
    }
    fmt.Println(path)
}

如果输入是 reports/%2，函数应直接返回错误。即使某些字节已经成功解码，也不能把部分结果当成完整路径，因为调用方无法知道输入到底缺了哪个字节。

路径解码和查询解码不是一回事

PathUnescape 与 QueryUnescape 都会处理 %XX，但加号规则不同：路径解码会保留 +，查询解码则会把 + 解释为空格。比如 team+docs 经过 PathUnescape 仍是 team+docs，它不是带空格的路径名。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    // 路径中的加号通常就是加号，不应按表单查询规则转换。
    path, pathErr := url.PathUnescape("team+docs%2Freadme")
    // 查询字符串中的加号遵循 QueryUnescape 的表单语义。
    query, queryErr := url.QueryUnescape("team+docs%2Freadme")
    fmt.Printf("path=%q err=%v\n", path, pathErr)
    fmt.Printf("query=%q err=%v\n", query, queryErr)
}

所以，先判断数据来自路径还是查询，再选择函数。不要为了让某个样例“变成空格”而在路径上手动替换加号，这会把合法路径名改掉。

把解码放在业务边界

解码应发生在进入业务路由、拼接文件路径或执行资源权限判断之前。坏输入在这个边界结束，日志只保留必要的原始参数和错误类型；成功路径才把解码结果交给后续逻辑。

func handlePath(rawPath string) (string, int) {
    decoded, err := url.PathUnescape(rawPath)
    if err != nil {
        // 解码失败时返回客户端输入错误，不触碰后续资源。
        return "", 400
    }
    // 这里才进入路由、白名单或文件访问判断。
    return decoded, 200
}

如果业务还要求限制目录、拒绝特殊段或检查资源权限，那些是解码成功后的另一层规则，不能用“百分号格式正确”代替。格式合法只说明字节序列可解码，不代表路径一定允许访问。

几个容易混淆的问题

为什么不直接忽略 error？ 因为返回字符串可能只代表部分处理结果，继续使用会让错误输入穿过边界。

百分号后是小写字母可以吗？ 可以，十六进制不区分大小写；真正的问题是字符数量不足或不是十六进制字符。

PathUnescape 能替代路径安全检查吗？ 不能。它只做编码转换，目录范围、权限和资源存在性仍需由业务规则负责。

总结

• %XX 是 PathUnescape 能识别的完整编码单元。
• 尾部百分号、缺一个十六进制字符或出现非法字符，都应按错误处理。
• 路径用 PathUnescape，查询用 QueryUnescape；加号语义不要混用。
• 解码失败在路由和文件访问之前结束，解码成功后仍需执行独立的安全规则。