Go url.ParseQuery 返回错误时还能不能使用已解析参数

先说结论：url.ParseQuery 返回错误时，第二个返回值 url.Values 仍然不是空结果。它会保留已经成功解码的合法参数，error 描述遇到的第一个解码错误。能不能继续使用这些字段，取决于你的请求是否允许“部分成功”，而不是看到 err != nil 就认定整个 map 无效。

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

实战判断可以记成一句话：Values 负责告诉你解析到了什么，error 负责告诉你哪里不完整；业务层必须决定这两者组合起来是否足够可信。

先看 ParseQuery 的返回值

接口收到的查询串经常不是“全对”或“全错”这么简单。例如下面的输入中，page=2 和 q=go 是合法片段，bad=%ZZ 却不是有效的 URL 编码：

package main

import (
	"fmt"
	"net/url"
)

func main() {
	// 混合一个合法参数和一个非法百分号编码，观察 Values 与 error 的关系。
	query := "page=2&q=go&bad=%ZZ"
	values, err := url.ParseQuery(query)

	fmt.Printf("page=%q q=%q\n", values.Get("page"), values.Get("q"))
	if err != nil {
		// err 描述首个解码错误，但不代表 values 被置为 nil。
		fmt.Println("parse error:", err)
	}
}

按照标准库的返回约定，values 仍然可以读取已经成功解析的键，err 则保留错误信息。这里的“部分成功”不是把非法片段修复后继续使用，而是合法片段和错误状态同时返回。

哪些片段会被保留，哪些会触发错误

ParseQuery 期望输入由 key=value 片段组成，并用 & 分隔。没有等号的片段会被当作值为空的键；但未编码的分号会被视为无效设置。百分号后面不是两个十六进制字符，同样会导致解码错误。

因此，不能用“只要 map 里有数据就说明查询串完整”来判断。更稳妥的做法是同时检查错误和你真正关心的字段：

func readPage(query string) (int, error) {
	// 先拿到部分结果，再按业务规则决定是否接受它。
	values, err := url.ParseQuery(query)
	if err != nil {
		// 对分页参数这类关键字段，发现任何编码错误就拒绝整批输入。
		return 0, fmt.Errorf("invalid query: %w", err)
	}

	pageText := values.Get("page")
	if pageText == "" {
		// 合法解析不等于字段齐全，缺少必需字段仍要单独处理。
		return 0, errors.New("page is required")
	}

	page, err := strconv.Atoi(pageText)
	if err != nil || page 

这段代码选择了“错误即拒绝”，因为分页参数会影响资源范围。它没有把 ParseQuery 的错误吞掉，也没有把缺失字段、类型错误和编码错误混成一个不透明的默认值。

保留合法参数，还是拒绝整批请求

部分结果是否可用，要看参数之间有没有强依赖。日志筛选接口里，q=go 即使旁边的可选排序参数损坏，可能仍有记录价值；但转账金额、权限范围、分页游标这类字段一旦出现编码错误，继续使用剩下的字段就容易形成错误请求。

如果确实允许保留部分字段，也要先做白名单和单字段校验，不能把整个 url.Values 直接下传：

func acceptedFilters(query string) (url.Values, error) {
	// 这个策略只保留独立的可选筛选字段，不接受关键控制字段的部分成功。
	values, parseErr := url.ParseQuery(query)
	allowed := make(url.Values)
	for _, key := range []string{"q", "label"} {
		if items, ok := values[key]; ok {
			allowed[key] = append([]string(nil), items...)
		}
	}
	if parseErr != nil {
		// 调用方可以记录 parseErr，同时继续使用白名单内的合法筛选条件。
		return allowed, fmt.Errorf("query partially accepted: %w", parseErr)
	}
	return allowed, nil
}

这个版本把“部分接受”显式写进函数契约：返回的 map 只包含允许的筛选键，调用方仍能看到错误。若业务不需要这种策略，直接在 parseErr != nil 时返回错误会更简单。

兼容和安全边界

第一，不要把 Values.Get 的空字符串当作“参数不存在”与“参数存在但值为空”完全等价；需要区分时直接读取 map。第二，Values 的键是大小写敏感的，白名单应使用固定键名。第三，记录错误时避免把原始查询串完整写入日志，因为其中可能包含敏感值。

最后，错误策略要和接口契约一致：允许降级的可选筛选项可以保留合法字段，但权限、金额、资源标识和游标等关键字段应在任何解析错误下拒绝整批请求。这样既利用了 ParseQuery 的非 nil 返回值，也不会把“部分成功”误装成“请求完全有效”。

常见问题

ParseQuery 返回 error 后，Values 一定为空吗？
不一定。标准库会返回包含已经找到的合法参数的非 nil map，error 描述首个解码错误。

能不能忽略 error 只使用 Values？
只有在业务明确允许部分成功、并且已经做了字段白名单和单字段校验时才可以；关键请求参数不应这样处理。