c.Query()将%28解码为(是因为url.ParseQuery自动解码query string，而路径段中%28保留是因path未被自动解码；模板渲染时再编码括号是html/template在URL上下文中执行RFC 3986编码的正常行为。
为什么 c.Query() 会把 %28 解码成 (，但你看到的 URL 里还是 %28？
这不是 Gin 的 bug，而是浏览器、HTTP 协议栈和 Go 标准库共同作用的结果。浏览器在发送请求时，会对 URL 中的 (、)、空格等字符做 url.PathEscape（不是 url.QueryEscape）级别的编码；Gin 的 c.Query() 调用的是 url.ParseQuery，它只解码 query string 部分（即 ?key=value 里的 value），而不会碰 path segment。所以如果你的 URL 是 /api/v1/file/(report)/detail?name=test%28abc%29：
-
c.Param("file")拿到的是%28report%29（因为 path 没被自动 decode） -
c.Query("name")拿到的是test(abc)（query string 被标准库自动 decode） - 模板里直接写
{{.url}}渲染出的src属性，仍会触发html/template的 URL 上下文编码，把(再变成%28
c.Param() 拿到的带编码字符怎么安全还原？
别用 url.QueryUnescape 处理 c.Param() 返回值——它专为 query string 设计，对 path segment 可能误解码（比如把 %2F 当成 / 导致路径穿越）。正确做法是用 url.PathUnescape：
// ✅ 安全还原路径参数
pathParam := c.Param("filename")
decoded, err := url.PathUnescape(pathParam)
if err != nil {
c.AbortWithStatusJSON(400, gin.H{"error": "invalid path encoding"})
return
}
// decoded 现在是原始字符串，如 "(report).pdf"
注意：如果路由定义为 /download/:filename，且客户端传入 /download/%28report%29.pdf，c.Param("filename") 就是 %28report%29.pdf，必须显式 url.PathUnescape 才能得到可读文件名。
如何让模板渲染时不重复编码括号？
模板里 src="{{.url}}" 触发的是 URL 上下文编码，不是 HTML 转义。即使你传入的是 template.URL("http://a.com/(data)")，html/template 仍会按 RFC 3986 对 path segment 中的 ( 做 url.PathEscape，输出 %28。这不是错误，而是保障跨代理/CDN 兼容性的必要行为。如果你确定该 URL 已完全合法且无需再编码：
- 确保传入模板的 URL 字符串本身已由
url.JoinPath或url.URL构造，而非拼接原始字符串 - 避免手动拼接
"http://" + host + "/" + param—— 这种方式无法保证 path segment 安全 - 若必须动态构造，用
url.URL{Scheme: "https", Host: "x.com", Path: "/"}; u.Path += url.PathEscape(segment)
ShouldBindQuery 对编码参数的处理边界在哪？
c.ShouldBindQuery(&v) 底层调用 url.ParseQuery，只解码 query string，且要求键值对格式严格。它不处理 path、header 或 body 中的编码内容。常见陷阱：
- 当 query string 含嵌套 JSON（如
?filter=%7B%22name%22%3A%22a%22%7D），ShouldBindQuery会把它当普通字符串解码为{"name":"a"}，但不会进一步 JSON 解析 - 如果 query 中有未闭合的百分号（如
?q=abc%），url.ParseQuery会返回 error，ShouldBindQuery也会失败 - 它对空格的处理是兼容的：
q=a+b和q=a%20b都会被解码为"a b"
真正容易被忽略的点是：URL 编码不是一层“开关”，而是分上下文（path/query/fragment）、分标准（RFC 3986 vs RFC 1738）、分阶段（浏览器发送 → 服务器解析 → 模板渲染）的多层转换。硬要绕过某一层编码，往往带来更隐蔽的安全或兼容性问题。
