Go URL 查询值乱码时的编码排查步骤

Go 服务拿到 URL 查询值后出现乱码，先不要急着给字符串再做一次转码。最有效的排查顺序是：保留 r.URL.RawQuery，只让 net/url 解码一次，再检查结果是不是有效 UTF-8。多数问题最终落在手工拼接、把 + 当普通字符、重复编解码，或上游本来就发送了非 UTF-8 字节。

先做一个只观察不修复的诊断接口

排错的第一步不是猜字符集，而是同时记录三个层次：原始查询字符串、标准库解析后的业务值、业务值的 UTF-8 有效性。RawQuery 保存问号之后仍处于编码状态的内容，而 URL.Query() 会返回解析后的 url.Values。两者并排观察，才能判断异常是在请求到达前还是在服务端二次处理后出现。

package main

import (
	"encoding/hex"
	"encoding/json"
	"net/http"
	"unicode/utf8"
)

type debugResult struct {
	RawQuery string `json:"raw_query"`
	Value    string `json:"value"`
	Hex      string `json:"hex"`
	ValidUTF8 bool  `json:"valid_utf8"`
}

func debugQuery(w http.ResponseWriter, r *http.Request) {
	// Query().Get 已完成查询组件的标准解码，不再手工解码。
	value := r.URL.Query().Get("q")
	result := debugResult{
		RawQuery: r.URL.RawQuery,
		Value: value,
		Hex: hex.EncodeToString([]byte(value)),
		ValidUTF8: utf8.ValidString(value),
	}

	// 明确响应字符集，避免把展示层误判成查询解析问题。
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	_ = json.NewEncoder(w).Encode(result)
}

func main() {
	http.HandleFunc("/debug", debugQuery)
	_ = http.ListenAndServe(":8080", nil) // 示例省略生产级错误处理。
}

若 RawQuery 已经与发送端预期不同，问题在客户端、网关或代理边界；若 RawQuery 正确而业务值异常，再检查服务端是否额外调用了解码函数。十六进制字段只用于看清字节，不应作为最终业务值保存。

用 url.Values 构造请求，排除手工拼接

最常见的根因是客户端直接写 "?q=" + keyword。只要值中含有空格、加号、百分号、井号或与号，这种拼接就可能改变查询结构。标准库的 url.Values.Encode 会把键和值按查询组件规则编码，并生成可直接放入 RawQuery 的字符串。

func buildSearchURL(baseURL, keyword string) (string, error) {
	u, err := url.Parse(baseURL)
	if err != nil {
		return "", err
	}

	// 让 Values 负责转义，不把用户输入直接拼到 URL 中。
	values := u.Query()
	values.Set("q", keyword)
	u.RawQuery = values.Encode()
	return u.String(), nil
}

例如关键词是 C++ 入门，正确编码必须保住两个真正的加号，并让空格使用查询组件允许的表示方式。发送端和接收端都交给 net/url 后，服务端读取到的仍应是原始关键词。

把加号变空格与中文乱码分开判断

QueryUnescape 与路径解码有一个关键差异：查询组件中的裸 + 会解码为空格。因此，q=C++ 不是三个普通字符的可靠传输形式，解析后可能得到带空格的值；真正的加号要由 QueryEscape 或 Values.Encode 写成 %2B。

func comparePlus() {
	// QueryEscape 会保留“加号是数据”这个语义。
	encoded := url.QueryEscape("C++ 入门")
	decoded, err := url.QueryUnescape(encoded)
	if err != nil {
		log.Print(err)
		return
	}
	log.Printf("encoded=%s decoded=%s", encoded, decoded)
}

如果现象只是加号变空格，不要引入 GBK、GB18030 或 Unicode 修复逻辑；这是查询语义问题。反过来，如果字节序列解码后出现替换字符或 utf8.ValidString 返回 false，才继续检查字符集边界。

看到百分号残留时检查重复编解码

查询值已经通过 r.URL.Query().Get 取得后，再调用一次 url.QueryUnescape，会把业务数据中的 %xx 继续解释成字节。另一个方向是先 QueryEscape，再把结果交给 Values.Encode，百分号会再次被转义成 %25。这两种情况都不是“中文编码不兼容”，而是编解码次数不对称。

func readKeyword(r *http.Request) string {
	// 正确：入口处由 URL.Query 统一解析一次。
	return r.URL.Query().Get("q")
}

func buildQuery(keyword string) string {
	values := url.Values{}
	// 正确：传入原始业务字符串，不预先调用 QueryEscape。
	values.Set("q", keyword)
	return values.Encode()
}

排查时可以搜索代码中的 QueryEscape、QueryUnescape、PathEscape 和 PathUnescape。查询值使用查询 API，路径段使用路径 API；不要因为它们都产生 %XX 就混用。

只有确认非 UTF-8 来源后才做字符集转换

Go 的字符串可以容纳任意字节，但很多文本处理逻辑默认内容是 UTF-8。百分号解码只负责把 %AB 还原成字节，并不会自动猜测这些字节原来属于 UTF-8、GBK 还是其他字符集。如果 utf8.ValidString(value) 为 false，并且上游协议明确声明使用 GBK，就应在系统入口完成一次受控转换，再让内部统一使用 UTF-8。

func requireUTF8(value string) error {
	// 不猜字符集，只在边界处拒绝无效 UTF-8。
	if !utf8.ValidString(value) {
		return fmt.Errorf("query q is not valid UTF-8")
	}
	return nil
}

不要看到乱码就逐个尝试字符集转换。没有协议依据时，自动猜测容易把原本正确的数据再次破坏。更稳妥的做法是让发送端统一按 UTF-8 生成查询值；确有历史系统时，把字符集声明、转换位置和失败策略写进接口契约。

按三组样例完成接口验收

最后不要只测一个中文词。至少准备普通中文、含加号与空格的值、含百分号的业务文本三组输入，并同时核对客户端构造结果、服务端 RawQuery 和最终业务值。这样可以一次覆盖字符、查询语义和重复解码三个边界。

验收通过的标准不是“页面看起来正常”这一条，而是：发送端只编码一次，RawQuery 与预期一致，服务端只解码一次，业务字符串是有效 UTF-8，响应层明确使用 UTF-8。沿这条链路逐层比对，URL 查询值乱码通常可以很快收敛到具体边界。