Go url.ParseQuery 为什么在边界输入上得到空结果

如果 url.ParseQuery 看起来返回了一个空结果，先不要把问题归结为“Go 没有解析参数”。它始终返回一个非 nil 的 url.Values，但会跳过空项、含未转义分号的项或解码失败的项，同时通过 err 告诉你输入并不完整。最常见的误判是只看 map，不看错误。

本文只讨论标准库 net/url 的边界行为：查询项如何切分、为什么一整段会被忽略、哪些有效参数仍会保留，以及业务代码应该怎样把“部分结果”与“完整成功”区分开。

排查口诀：先看查询串是不是按 & 分隔，再看每个键和值能否 URL 解码，最后同时判断 values 和 err。不要用“map 为空”替代错误判断。

ParseQuery 约定的查询串形状是什么

官方文档把输入定义为一组由 & 分隔的 key=value 设置。没有等号的项也合法，会被解释成一个空字符串值；查询键可以重复，结果中的同名键会对应多个值。

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

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 用 & 分隔多个参数；同名键会累积成切片。
	values, err := url.ParseQuery("page=2&tag=go&tag=web&debug")
	if err != nil {
		// 生产代码应先记录 err，再决定是否拒绝这次输入。
		fmt.Println("parse error:", err)
	}

	// debug 没有等号，库会把它解释成空字符串值。
	fmt.Printf("page=%q tags=%q debug=%q\n", values["page"], values["tag"], values["debug"])
}

这里的返回值不是 map[string]string，而是 url.Values，本质上是 map[string][]string。因此读取一个键时要考虑“没有值”“有一个值”和“有多个值”三种情况。

为什么未转义分号会让结果看起来为空

ParseQuery 只把 & 当作查询项分隔符。按照当前标准库实现，如果某个已经切出的查询项包含未转义的分号，整项会被标记为无效并跳过，同时返回一个表示分号分隔符无效的错误。

例如，下面的输入只有一个查询项，因为中间没有 &：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 分号没有被 & 分开；这一整项会被跳过，而不是拆成两个键值对。
	values, err := url.ParseQuery("name=go;lang=zh")
	fmt.Printf("values=%v\n", values)
	fmt.Printf("err=%v\n", err)
}

这时常见的观察结果是 values 为空、err 非空。根因不是“分号不能出现在值里”，而是它作为未转义的查询项分隔符出现在了一个项内部。若分号只是数据本身，应先按 URL 规则编码；若输入来自不受控客户端，则应在入口拒绝或明确兼容它，而不是静默替换。

如果分号项旁边还有合法项，合法项仍可能被保留：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// bad=1;two=2 是坏项，但后面的 ok=1 仍是独立的合法项。
	values, err := url.ParseQuery("bad=1;two=2&ok=1")
	fmt.Printf("ok=%q, all=%v, err=%v\n", values["ok"], values, err)
}

所以“map 不是空的”也不能证明输入完全正确；它可能只是包含了被保留下来的部分结果。

非法百分号转义为什么只影响部分键值

键和值都会经过 URL 解码。像 %E4%BD%A0 这样的百分号序列可以表示已编码的数据；像 %ZZ 这样的序列无法解码，对应的键或值会被跳过，并把解码错误放进返回的 err。解析器继续处理其它由 & 分开的项，因此结果可能是“部分成功”。

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// bad=%ZZ 无法解码；lang=go 是独立的有效项，应继续保留。
	values, err := url.ParseQuery("bad=%ZZ&lang=go")
	if err != nil {
		// err 表示输入存在问题，不应被忽略或只打印 map。
		fmt.Println("query is not fully valid:", err)
	}
	fmt.Printf("lang=%q, bad-present=%t\n", values["lang"], values.Get("bad") != "")
}

还有一个容易忽略的细节：如果前面已经遇到一种错误，后面再次遇到解码错误，返回值描述的是先遇到的错误。排查时应保留原始查询串，并把 err 与请求上下文一起记录，不能根据 map 中剩下的值猜测完整输入。

空串、无等号和重复键分别怎么处理

这三种情况经常被一起误报成“空结果”，但语义不同：

尤其不要用 len(values) == 0 代替 err == nil。空输入本来就可以合法地产生长度为零的 map；反过来，非空 map 也可能只是错误输入留下的部分结果。

生产代码怎样把部分结果和完整成功分开

如果查询参数影响权限、分页范围、排序字段或写入内容，建议把 ParseQuery 封装成“先解析、再按业务必需键校验”的小函数。下面的示例不替换标准库语义，只把错误处理和必需参数判断集中起来。

package queryutil

import (
	"fmt"
	"net/url"
)

// ParsePageQuery 只接受完整可解码的查询串，并校验 page 的业务必需性。
func ParsePageQuery(raw string) (url.Values, error) {
	values, err := url.ParseQuery(raw)
	if err != nil {
		// 部分结果不能直接当成成功结果返回，避免坏参数悄悄生效。
		return nil, fmt.Errorf("invalid query: %w", err)
	}
	if values.Get("page") == "" {
		// 无等号或缺少 page 都会落到空字符串，需要单独做业务判断。
		return nil, fmt.Errorf("missing page parameter")
	}
	return values, nil
}

如果业务确实需要“尽量读取合法字段”，也可以在记录 err 后使用返回 map，但要把状态命名为部分结果，并明确哪些字段允许缺失。不能把这种兼容策略伪装成完整解析成功。

排查时可以按这张清单判断

1. 确认传给 ParseQuery 的是查询串本身，而不是带 ? 的完整 URL；完整 URL 应先用 url.Parse 后读取 URL.Query()。
2. 把输入按字节保留下来，检查参数之间是否使用 &，是否混入了未转义分号。
3. 检查键和值中的百分号序列，特别是截断的或非十六进制的转义。
4. 同时输出或记录 len(values)、关键键和 err，不要只打印 map。
5. 对权限、金额、分页和写入类参数，只有 err == nil 且业务字段完整时才继续。

常见追问

ParseQuery 返回 nil map 吗？

按标准库契约，它返回非 nil map。调用方如果看到 nil，通常是自己在出错分支把返回值改成了 nil，或使用了另一个解析函数。

为什么有错误但仍然能读到参数？

解析按查询项继续进行，坏项被跳过，独立的有效项可以留在 map 中。这是部分结果，不代表整串有效。

可以把分号替换成 & 再解析吗？

只有在协议明确规定分号就是历史分隔符、且你接受兼容带来的歧义时才应这么做。对一般业务输入，更稳妥的是要求调用方正确编码并在 err != nil 时拒绝。

什么时候应该使用 URL.Query？

当手里是完整 URL 时，先解析 URL，再调用 u.Query() 更自然；当手里已经是裸查询串时，使用 url.ParseQuery 并显式处理错误。

归根结底，Go url.ParseQuery 的“空结果”通常是输入项被跳过后的表象。把分隔规则、URL 解码和 err 放在一起看，才能判断这是合法空输入、局部可读结果，还是应该拒绝的坏查询串。