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 可以重复。
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)
}
}预期输出
/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) 并显式处理返回的错误。无论选择哪种方式,都应在进入业务逻辑前完成解析与校验,让后续代码只处理已验证的类型和值。