Go URL 查询参数怎样避免重复编码

把搜索词、筛选条件或分页参数拼到 URL 后，最常见的异常是服务端收到 %252F、%252B 这类结果。它通常不是 Go 多编码了一次，而是调用方先把值做成了查询编码文本，随后又把这段文本交给 url.Values.Encode 当作普通值再次编码。稳定的做法是：业务层一直保留原始字符串，使用 url.Values 组装参数，最后只在写入 RawQuery 时编码一次。

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

先把“原始值”和“已编码文本”分开

假设筛选条件的原始值是 Go + URL/中文。它里面的加号、斜杠和非 ASCII 字符都属于参数数据，不应该在业务层提前替换成百分号文本。把原始值交给 Values.Set 后，Encode 会把加号写成 %2B、斜杠写成 %2F，空格使用查询字符串的加号表示。

package main

import (
	"fmt"
	"net/url"
)

func buildSearchURL(rawKeyword string) (string, error) {
	u, err := url.Parse("https://example.com/search")
	if err != nil {
		// 解析失败时直接返回，避免在不完整的 URL 上继续拼接参数。
		return "", err
	}

	q := u.Query()
	q.Set("keyword", rawKeyword)
	q.Set("page", "2")
	// Encode 只在这一处执行，RawQuery 保存最终的查询字符串。
	u.RawQuery = q.Encode()
	return u.String(), nil
}

func main() {
	// 这里传入原始业务值，不要先调用 QueryEscape。
	result, err := buildSearchURL("Go + URL/中文")
	if err != nil {
		// 调用方应保留解析错误，避免把错误 URL 发到下游。
		fmt.Println("build url:", err)
		return
	}
	fmt.Println(result)
}

关键边界是 q.Set 与 q.Encode 之间：前者保存值，后者序列化值。如果先写 url.QueryEscape("Go + URL/中文")，得到的 Go+%2B+URL%2F%E4%B8%AD%E6%96%87 会被再次当成普通字符串，百分号就会变成 %25。

修改既有查询时只改 Values

已有 URL 可能同时包含追踪参数、分页参数和业务筛选条件。不要直接在 RawQuery 后面拼接 &keyword=...，因为你需要自己处理问号、重复键和特殊字符。Query 会把现有查询解析成 url.Values，修改后再统一编码。

func addFilter(rawURL string, filter string) (string, error) {
	u, err := url.Parse(rawURL)
	if err != nil {
		// 输入 URL 不合法时不返回一个看似可用的半成品。
		return "", err
	}

	q := u.Query()
	q.Set("filter", filter) // Set 表示覆盖同名参数。
	q.Add("scope", "detail") // Add 保留同名键的多值语义。
	// 重新编码会按查询格式处理键和值，避免手工拼接遗漏转义。
	u.RawQuery = q.Encode()
	return u.String(), nil
}

Set 和 Add 的选择要跟接口语义一致：一个筛选条件通常用 Set，多选标签则可以多次 Add。如果参数值为空，Set("q", "") 仍然会保留 q=；是否把它删掉，应由业务规则决定，而不是靠字符串拼接的偶然结果。

外部已经编码的输入要先判断来源

如果值来自表单或业务对象，它通常是原始值，直接交给 Set。如果值明确来自一个已经编码过的查询组件，例如上游接口把 %2F 作为编码后的参数值传递过来，那么应先解码一次，再交给 Values；但不要对所有含百分号的字符串无条件解码，因为字面量 100% 并不是合法的百分号转义。

func normalizeEncodedValue(encoded string) (string, error) {
	value, err := url.QueryUnescape(encoded)
	if err != nil {
		// 百分号后缺少两个十六进制字符时，拒绝猜测输入含义。
		return "", err
	}
	return value, nil
}

func buildFromEncodedValue(encoded string) (string, error) {
	value, err := normalizeEncodedValue(encoded)
	if err != nil {
		return "", err
	}
	q := url.Values{}
	q.Set("path", value)
	// 解码一次后再统一编码，避免把已编码输入再次套一层。
	return "https://example.com/item?" + q.Encode(), nil
}

这里的“先解码一次”只适用于调用协议已经明确说输入是查询编码文本的场景。若业务真正想传递字面量 %2F，就应该把 %2F 当作原始数据交给 Set，最终结果出现 %252F 反而是正确的，因为接收端解码一次后应得到字面量 %2F。

路径转义和查询转义不是一回事

PathEscape 用于一个路径段，QueryEscape 用于单个查询字符串值；两者的适用位置不同。实际构造包含多组参数的 URL 时，优先让 url.Values.Encode 统一处理查询部分，只有在把一个独立业务标识放进路径段时才调用 PathEscape。

可以用下面的清单快速排查重复编码：

• 检查传给 Set 或 Add 的值是否已经包含 %2F、%20 等编码片段。
• 检查代码是否同时调用了 QueryEscape 和 Values.Encode。
• 检查是否把路径段交给了查询编码函数，或把完整查询串当成单个值写入。
• 检查修改 u.Query() 后是否真的把编码结果写回 u.RawQuery。

常见问题

为什么结果里出现 %252F？

通常说明原始值中的百分号已经代表一段编码文本，随后又被 Values.Encode 按普通字符编码了一次。先确认输入协议，再决定保留字面量还是先 QueryUnescape。

查询参数可以直接字符串拼接吗？

简单常量偶尔可以，但只要出现用户输入、空格、加号、中文或重复键，就应改用 url.Values，把转义和多值语义交给标准库。

PathEscape 能替代 Values.Encode 吗？

不能。它们服务于 URL 的不同部分。路径段和查询值的分隔符规则不同，混用会让服务端解析出与预期不同的结构。

把参数值保持为原始数据，最后只保留一个明确的编码边界，Go 的 URL 构造就容易维护：已有查询用 Query 取出，参数用 Set/Add 修改，最终统一写回 RawQuery。