Go url.ParseQuery 返回错误时为什么仍有部分 Values

Go 的 url.ParseQuery 返回错误时仍然有部分 Values，不是返回值被“污染”，而是它明确采用了部分成功语义：逐段解析查询串，能完整解码的参数先写入 map，遇到错误只记录第一个错误并跳过当前参数，继续处理后面的内容。因此业务代码不能只看 err，也不能只看 Values。

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

实用结论：如果查询参数来自不可信请求，通常把非 nil 的错误当作整次输入失败；只有在明确允许“尽可能读取合法字段”的协议中，才在记录错误后使用已解析的部分值。

先用一个坏参数复现部分成功

下面把非法的 %ZZ 放在中间。第一段和最后一段都能正常解码，所以返回的 map 仍然包含它们；错误描述的是当前输入存在解码失败，而不是 map 一定为空。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 中间参数的百分号转义非法，用来观察“部分值 + error”。
	query := "page=2&bad=%ZZ&tag=go&tag=net%2Fhttp"
	values, err := url.ParseQuery(query)
	if err != nil {
		// 记录错误；不要把它误解为 values 必然不可用。
		fmt.Println("parse error:", err)
	}

	// 合法参数仍会保留，重复键按出现顺序追加。
	fmt.Printf("page=%q tags=%q\\n", values.Get("page"), values["tag"])
}

parse error: invalid URL escape "%ZZ"
page="2" tags=[go net/http]

这里的关键不是 Go 对错误“放宽了”，而是函数契约本身就承诺返回所有已发现的有效查询参数。空片段会跳过；没有等号的片段会被当作空值，例如 flag 等价于键为 flag、值为空字符串。

ParseQuery 为什么不会遇错立即返回

从实现顺序看，每轮先按 & 取出一个片段，再检查分号、拆分键和值，分别进行 QueryUnescape。只有键和值都成功解码后，才执行 m[key] = append(m[key], value)。键或值任意一侧失败，当前片段不写入，但循环仍会继续。

错误变量只在尚未有错误时接收当前错误，所以多个坏片段并存时，调用方得到的是第一个解码错误。这个设计同时满足两件事：调用方知道输入不完全可信；调试时还能看到哪些字段在错误之前或之后仍然有效。

四类边界要分别处理

参数数量限制是另一种容易混淆的情况：它不是“解析了一半”，而是在开始逐段处理前就因数量超限退出。当前 Go 源码还允许通过 GODEBUG=urlmaxqueryparams 调整相关上限，但应用层不应把它当成放宽外部请求约束的理由。

HTTP 入口如何选择严格策略

URL.Query() 会静默丢弃格式错误的值对，适合已经确认输入可信、只想便捷读取的场景；需要判断请求是否合法时，应直接对 RawQuery 调用 ParseQuery，并在发现错误后停止业务处理。

func parseRequiredQuery(raw string) (url.Values, error) {
	// 先保留合法值，便于日志定位；对外接口仍采用全量拒绝。
	values, err := url.ParseQuery(raw)
	if err != nil {
		return nil, fmt.Errorf("invalid query: %w", err)
	}
	// 只有无错误时才把结果交给后续校验和业务逻辑。
	return values, nil
}

如果协议确实允许部分读取，例如批量导入中的可选字段，应把错误和原始片段一起记录，并明确告诉调用方哪些字段被接受、哪些被丢弃。不要把“有部分 Values”当成输入完全有效的信号。

常见追问

为什么 err != nil 仍然可以调用 values.Get？因为 ParseQuery 保证返回非 nil map，并保留已找到的合法参数；但这不等于整个查询串通过校验。

如何获得所有错误而不是第一个错误？标准库只返回第一个解码错误。若必须逐项报告，可先按协议拆分片段，再对每项调用 url.QueryUnescape，同时保留与 ParseQuery 一致的编码规则。