README
¶
query
提供了将 web 请求中的查询参数解析到结构体的操作。
type State int8
const (
StateLocked State = iota+1
StateDelete
)
// 实现 query.UnmarshalQueryer 接口
func (s *State) UnmarshalQuery(data string) error {
switch data {
case "locked":
*s = StateLocked
case "delete":
*s = StateDelete
default:
return errors.New("无效的值")
}
}
type struct Query {
Page int `query:"page,1"`
Size int `query:"size,20"`
States []State `query:"state,normal"`
}
func handle(w http.ResponseWriter, r *http.Request) {
q := &Query{}
errors := query.Parse(r.URL.Query(), q)
if len(errors) > 0 {
// TODO
return
}
// 请求参数为 /?page=1&size=2&state=normal,delete
// 则 q 的值为
// page = 1
// size = 2
// states = []State{StateLocked, StateDelete}
//
// 参数 state 也可使用以下方式
// /?page=1&size=2&state=normal&normal=delete
}
版权
Documentation
¶
Overview ¶
Package query 提供将查询参数解析到结构体的相关操作
struct tag
通过 struct tag 的方式将查询参数与结构体中的字段进行关联。 struct tag 的格式如下：
`query:"name,default"`
其中 name 为对应查询参数的名称，若是为空则采用字段本身的名称； default 表示在没有参数的情况下，采用的默认值，可以为空。 若是将整个值设置为 -，则表示忽略当前字段。
数组：
如果字段表示的是切片，那么查询参数的值，将以半角逗号作为分隔符进行转换写入到切片中。 struct tag 中的默认值，也可以指定多个：
type Object struct {
Slice []string `query:"slices,1,2"`
}
以上内容，在没有指定参数的情况下，Slice 会被指定为 []string{"1", "2"}
若 URL 中指定了 /?slices=4,5,6，则 Slice 的值会被设置为 []string{"4", "5", "6"}
如果值中有逗号，则可以使用 slices=v1&slices=v2,v3 的方式将值解析成 []string{"v1", "v2,v3"}
默认值：
默认值可以通过 struct tag 指定，也可以通过在初始化对象时，另外指定：
obj := &Object{
Slice: []int{3,4,5}
}
以上内容，在不传递参数时，会采用 []int{3,4,5} 作为其默认值，而不是 struct tag 中指定的 []int{1,2}。
Index ¶
Constants ¶
const Tag = "query"
Tag 在 struct tag 的标签名称
Variables ¶
This section is empty.
Functions ¶
func ParseWithLog ¶ added in v3.1.0
ParseWithLog 将查询参数解析至 v 中
如果 queries 中的元素，实现了 Unmarshaler 或是 encoding.TextUnmarshaler， 则会调用相应的接口解码。
如果有错误，则调用 log 方法进行处理，log 原型如下：
func(name string, err error)
其中的 name 表示查询参数名称，err 表示解析该参数时的错误信息。
v 只能是指针，如果是指针的批针，请注意接口的实现是否符合你的预期。
NOTE: ParseWithLog 适合在已经有错误处理方式的代码中使用，比如库的作者。 一般情况下 Parse 会更佳合适。
Types ¶
type Unmarshaler ¶
Unmarshaler 该接口实现在了将一些特定的查询参数格式转换成其它类型的接口
比如一个查询参数格式如下：
/path?state=locked
而实际上后端将 state 表示为一个数值：
type State int8 const StateLocked State = 1
那么只要 State 实现 Unmarshaler 接口，就可以实现将 locked 转换成 1 的能力。
func (s *State) UnmarshalQuery(data string) error {
if data == "locked" {
*s = StateLocked
}
}
如果找不到 Unmarshaler 接口，会尝试去查找是否也实现了 encoding.TextUnmarshaler， 所以如果对象有已经实现了 encoding.TextUnmarshaler， 则不需要再去实现 Unmarshaler，除非两者的解码方式是不同的。
NOTE: 空值不会调用该接口。
Source Files