Go net/url 怎样读取查询参数

在 Go 接口里，查询参数通常来自 URL 中 ? 后面的查询串。最常用的读取方式是先用 url.Parse 得到 URL 对象，再调用 u.Query() 获得 url.Values。单值可以用 Get，重复键要直接读取切片；如果空字符串和参数缺失需要区分，就再配合 Has。

官方资料：https://pkg.go.dev/net/url

例如 ?page=2&tag=go&tag=net&empty= 中，page 是一个值，tag 是两个值，而 empty 虽然值为空，键本身仍然存在。

先把完整 URL 解析成 URL 对象

url.Parse 负责把原始字符串解析成 *url.URL。不要直接截取问号后面的文本，否则还要自己处理转义、重复键和非法百分号。

package main

import (
    "fmt"
    "log"
    "net/url"
)

func main() {
    raw := "https://example.com/search?page=2&tag=go&tag=net&empty="

    // 先解析完整 URL，解析失败时不要继续读取查询参数。
    u, err := url.Parse(raw)
    if err != nil {
        log.Fatal(err)
    }

    // Query 将 RawQuery 解码为 Values，键和值的关系由标准库维护。
    values := u.Query()
    fmt.Println(values)
}

这里的关键边界是：URL.RawQuery 保存编码后的查询串，URL.Query() 返回解码后的 Values。官方文档说明，Query 会静默丢弃格式错误的 value pair；若业务必须知道是否存在格式错误，应该使用后文的 ParseQuery。

用 Query 读取常规单值和多值参数

url.Values 本质上是 map[string][]string。因此，读取方式取决于业务是否允许同名键出现多次。

// values 来自上一节的 u.Query()。
page := values.Get("page")
tags := values["tag"]

fmt.Println("page:", page)
fmt.Println("tags:", tags)

// Get 只取第一个值；需要全部值时直接访问 map。
if len(tags) == 0 {
    fmt.Println("没有 tag 参数")
}

对 ?tag=go&tag=net，values.Get("tag") 只得到 go，而 values["tag"] 得到 []string{"go", "net"}。分页、排序这类通常只允许一个值的参数可以使用 Get；筛选标签、批量 ID 等场景要明确读取切片，并决定是否拒绝重复值。

用 Has 区分缺失参数和空字符串

Get 在没有值时返回空字符串，所以 ?empty= 与完全没有 empty 看起来一样。需要区分时，先用 Has 判断键是否存在，再读取值。

// Has 判断键是否出现，Get 再读取它的第一个值。
if !values.Has("empty") {
    fmt.Println("empty 未提交，使用默认策略")
} else if values.Get("empty") == "" {
    fmt.Println("empty 已提交，但值为空")
} else {
    fmt.Println("empty:", values.Get("empty"))
}

同理，直接写 if values.Get("page") == "" 只能说明“没有可用的第一个字符串”，不能说明用户是否传过这个键。对于必填参数，先判断 Has，再做整数、枚举或长度校验，错误信息会更准确。

需要错误信息时改用 ParseQuery

如果查询串来自外部请求，业务有必要知道是否存在坏的转义或非法参数对，就不要只调用 u.Query()。可以把 u.RawQuery 交给 url.ParseQuery，同时拿到 Values 和 error。

// ParseQuery 保留解析错误，适合需要拒绝坏请求的入口层。
values, err := url.ParseQuery(u.RawQuery)
if err != nil {
    // 这里可以返回 400，而不是把坏参数静默当成不存在。
    log.Printf("invalid query: %v", err)
    return
}

// 解析成功后仍按单值、多值和空值规则读取。
fmt.Println(values.Get("page"))

可以这样做选择：

常见问题

为什么 Get 读不到第二个同名参数？

因为 Values.Get 的语义就是返回指定键关联的第一个值。需要全部值时访问 values["key"]，并在业务层决定重复值是否有效。

Query 和 ParseQuery 应该怎么选？

只关心可用参数时用 Query 更简洁；需要识别非法转义或坏参数对时，用 ParseQuery 接收并处理错误。

空查询串会报错吗？

空查询串会得到空的 Values。真正需要注意的是把“键不存在”和“键存在但值为空”混为一谈，此时用 Has 做存在性判断。

总结：url.Parse 负责得到 URL 对象，Query 负责便捷读取，Get 适合单值，直接访问 Values 适合多值，Has 负责区分缺失与空值，而严格入口应使用 ParseQuery 留住错误。