Go URL 参数被二次编码的拼接排查

Go 里 URL 参数出现 %25、%2B，或者服务端收到的值多了一层百分号，通常不是 Go “多编码了一次”，而是同一段数据先被编码，再把编码结果当成原文交给了第二个编码函数。排查时先记住一句话：查询参数交给 url.Values，路径段交给 PathEscape 或 URL.JoinPath，不要在字符串拼接阶段重复处理。

最稳的修复方式是让业务变量始终保存未编码的原文，直到 URL 的对应字段负责最后一次编码。

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

先做一个最小复现：看到 %25 就回查编码入口

假设搜索词是 Go+URL。第一次把它作为查询值编码后，+ 会变成 %2B；如果再把这段结果交给 QueryEscape，百分号本身就会变成 %25。最终服务端解码一次，只能得到上一层的编码文本，而不是原始搜索词。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	keyword := "Go+URL"
	first := url.QueryEscape(keyword)
	second := url.QueryEscape(first)

	// 第一次编码已经完成，第二次会把百分号也编码掉。
	fmt.Println(first)  // Go%2BURL
	fmt.Println(second) // Go%252BURL
}

看到 %25 时，沿着值的生命周期往回找：它是否已经来自 QueryEscape、Values.Encode 或某个 HTTP 客户端的 URL 重建？只保留一个最终编码点，问题通常就能收敛。

项目目标：用 url.Values 统一构造查询参数

这个小项目只做一件事：接收未编码的关键词和过滤条件，构造一个可发送的搜索 URL。查询参数不要手写 ?q=，也不要把 QueryEscape 的结果塞进 Values.Set；Values.Set 接收原文，Encode 才负责生成 RawQuery。

package main

import (
	"fmt"
	"net/url"
)

func buildSearchURL(base, keyword, kind string) (string, error) {
	u, err := url.Parse(base)
	if err != nil {
		// 基础地址解析失败时立即返回，避免继续拼出半截 URL。
		return "", err
	}
	q := u.Query()
	q.Set("q", keyword)    // 这里放未编码的原文。
	q.Set("kind", kind)    // Encode 会统一处理空格、加号和中文。
	u.RawQuery = q.Encode() // 只在 URL 重建前编码一次。
	return u.String(), nil
}

func main() {
	result, err := buildSearchURL("https://example.com/search", "Go+URL", "docs")
	if err != nil {
		fmt.Println("parse url:", err)
		return
	}
	fmt.Println(result)
}

这里的关键不是记住某个输出，而是保持数据职责稳定：业务层传入 Go+URL，Values 保存它，最后的 Encode 生成查询串。若你的上游变量已经是 Go%2BURL，应先回到上游修正，而不是再调用一次解码或编码去“抵消”。

路径参数要按段处理，不要拿 QueryEscape 代替 PathEscape

查询和路径的分隔符规则不同。QueryEscape 面向查询组件；PathEscape 面向一个路径段，会把段内的斜杠等特殊字符编码。Go 官方还提供了 URL.JoinPath，它接收已经按路径段规则处理的元素，并返回新的 URL。

func buildFileURL(base, owner, file string) (string, error) {
	u, err := url.Parse(base)
	if err != nil {
		// 基础地址错误时不继续修改 URL。
		return "", err
	}
	// owner 和 file 都是独立路径段，斜杠不能被当成新的层级。
	joined := u.JoinPath(url.PathEscape(owner), url.PathEscape(file))
	return joined.String(), nil
}

常见错误是先把 file 用 QueryEscape 处理，再通过字符串加斜杠拼到路径后面。这样既混用了语义，又会让后续的 URL 重建再次观察到百分号。路径问题优先看 Path 和 EscapedPath()：前者是解码后的逻辑路径，后者才是用于输出的转义路径。

从 URL 字段排查：谁在重复拼接，谁就应该退出

把请求发送前的 URL 拆成三个观察点，能快速定位重复编码：

• Query()：读取查询值，适合确认业务层看到的原文。
• RawQuery：保存已经编码的查询串，适合确认 Encode 是否被调用了两次。
• Path 与 EscapedPath()：分别观察逻辑路径和输出路径，适合定位路径段误用查询编码。

如果请求构造器接收的是一个完整的已编码 URL，就不要再把它拆成字符串片段重复 Escape；更好的接口是接收原始字段，内部统一使用 url.URL。如果必须兼容旧接口，先明确它的参数契约：字段是原文还是已编码文本，并在边界处只做一次转换。

一张表完成验收

验收时不必盯着完整字符串猜测。先确认业务变量仍是原文，再看 Query().Get 是否符合预期，最后看 RawQuery 和 EscapedPath() 是否各自只承担一次输出编码。这个顺序能把“值错了”和“表示错了”分开。

相关问题

为什么不能统一使用 QueryEscape？因为查询组件和路径段的保留字符不同；路径中的斜杠需要被当作段内数据时，应使用 PathEscape。

已经拿到 %2B，应该再 QueryUnescape 吗？不要把解码当成默认修复。先确认这个值的接口契约；如果它本应是原文，应修复上游，让后续只接收原文。

URL.String 会不会再次编码？String 会按 URL 字段生成合法表示，所以更应该把原文放进正确字段，而不是提前把一段完整 URL 编好后再塞回字段。