Go / 系统课时

解析查询参数

解析查询参数

查询参数常用于过滤、分页和排序,但只调用 Values.Get 会把“参数缺失”和“参数显式为空”都读成空字符串。本篇把解析规则前移到请求入口,统一处理缺失、重复、多值、类型转换和非法输入,让后续业务只接收已验证的数据。

学习目标

  • 使用 Request.URL.Query 读取单值和多值查询参数
  • 区分参数缺失、显式空字符串与重复出现
  • 为分页、排序等参数定义默认值、类型转换与白名单校验

从 url.Values 看清原始输入

r.URL.Query() 返回 url.Values,本质上是 map[string][]string。因此每个键同时包含“是否出现”和“出现了哪些值”两类信息。

请求 读取结果 含义
/items q["status"] 的 ok 为 false 参数缺失
/items?status= 切片含一个空字符串,ok 为 true 参数显式为空
/items?tag=go&tag=web q["tag"] 含两个元素 同名参数重复出现

q.Get("status") 在前两种情况下都会返回空字符串,所以只要接口需要区分“未提供”和“显式传空”,就应使用 map 查询形式。对于明确支持多值的参数,例如标签过滤,则保留整个切片。

在解析阶段完成默认值和校验

下面把查询参数解析成一个明确的业务结构。page 缺失时默认为 1,但空值、重复值和非正整数都报错;sort 缺失时使用 created_at,且只接受白名单;status 允许空字符串但只能出现一次;tag 可以重复。

go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "strconv"
)

type listQuery struct {
    Page          int      `json:"page"`
    Sort          string   `json:"sort"`
    StatusPresent bool     `json:"statusPresent"`
    Status        string   `json:"status"`
    Tags          []string `json:"tags"`
}

func parseListQuery(r *http.Request) (listQuery, error) {
    q := r.URL.Query()
    result := listQuery{Page: 1, Sort: "created_at"}

    if values, ok := q["page"]; ok {
        // page 是单值参数:重复或显式为空都拒绝。
        if len(values) != 1 || values[0] == "" {
            return listQuery{}, fmt.Errorf("page must appear once and cannot be empty")
        }
        page, err := strconv.Atoi(values[0])
        if err != nil || page < 1 {
            return listQuery{}, fmt.Errorf("page must be an integer >= 1")
        }
        result.Page = page
    }

    if values, ok := q["sort"]; ok {
        if len(values) != 1 || (values[0] != "created_at" && values[0] != "name") {
            return listQuery{}, fmt.Errorf("sort must be created_at or name")
        }
        result.Sort = values[0]
    }

    if values, ok := q["status"]; ok {
        result.StatusPresent = true
        if len(values) != 1 {
            return listQuery{}, fmt.Errorf("status must appear at most once")
        }
        result.Status = values[0]
    }

    // tag 明确支持多值,因此保留请求中的全部值及顺序。
    result.Tags = append([]string(nil), q["tag"]...)
    return result, nil
}

func main() {
    targets := []string{
        "http://example.test/items?page=2&status=&tag=go&tag=web&sort=name",
        "http://example.test/items?page=abc",
    }

    for _, target := range targets {
        req, err := http.NewRequest(http.MethodGet, target, nil)
        if err != nil {
            panic(err)
        }

        parsed, err := parseListQuery(req)
        if err != nil {
            fmt.Printf("%s -> 400 %s\n", req.URL.RequestURI(), err)
            continue
        }

        data, err := json.Marshal(parsed)
        if err != nil {
            panic(err)
        }
        fmt.Printf("%s -> 200 %s\n", req.URL.RequestURI(), data)
    }
}

预期输出

text
/items?page=2&status=&tag=go&tag=web&sort=name -> 200 {"page":2,"sort":"name","statusPresent":true,"status":"","tags":["go","web"]}
/items?page=abc -> 400 page must be an integer >= 1

第一个请求里 statusPresent 为 true,而 status 仍为空字符串,因此调用方可以准确识别“显式传空”。在真实 HTTP Handler 中,只需把 parseListQuery 返回的错误映射为 400 响应;解析成功后再把 listQuery 交给业务逻辑即可。

不要把字符串直接当成业务类型

查询字符串最终都是文本。分页数字应通过 strconv.Atoi 等函数转换后再检查范围;布尔值、时间和枚举也应使用对应解析函数或白名单,不要把转换推迟到业务逻辑深处。

排序参数尤其不能未经检查就直接拼进 SQL。将外部字符串映射到有限的内部排序字段,既能稳定 API 契约,也能避免把任意输入当成数据库标识符。

明确定义重复参数的语义

HTTP 查询字符串允许同一个键出现多次,因此接口必须明确重复值代表什么。标签、分类等集合条件通常适合接受多值;页码、排序方式等单值条件更适合在重复出现时直接拒绝,避免客户端依赖“取第一个”或“取最后一个”的隐式行为。

还有一个严格性边界:Request.URL.Query() 会忽略解析查询字符串时出现的部分格式错误。如果接口必须拒绝非法百分号编码等问题,可以改用 url.ParseQuery(r.URL.RawQuery) 并显式处理返回的错误。无论选择哪种方式,都应在进入业务逻辑前完成解析与校验,让后续代码只处理已验证的类型和值。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

解析查询参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通