query

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 (q *Query) SanitizeQuery(errors map[string]string) {
    if q.Page < 0 {
        errors["page"] = "不能小于零"
    }

    // 其它字段的验证
}

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
}

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

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
• type Errors
  • func Parse(queries url.Values, v interface{}) (errors Errors)
  • func (err Errors) Add(key, val string)
  • func (err Errors) Set(key, val string)
• type Sanitizer
• type Unmarshaler

Constants

const Tag = "query"

Tag 在 struct tag 的标签名称

Types

type Errors

type Errors map[string][]string

Errors 表示一组错误信息的集合

键名查询参数名称，键值则为在解析和验证过种中返回的错误信息。

func Parse

func Parse(queries url.Values, v interface{}) (errors Errors)

Parse 将查询参数解析到一个对象中

返回的是每一个字段对应的错误信息。

func (Errors) Add

func (err Errors) Add(key, val string)

Add 为查询参数 key 添加一条新的错误信息

func (Errors) Set

func (err Errors) Set(key, val string)

Set 将查询参数 key 的错误信息改为 val

type Sanitizer

type Sanitizer interface {
	// 参数 errors 用来保存由函数中发现的错误信息。
	//
	// 其中的键名为错误字段名称，键值为错误信息。
	SanitizeQuery(errors Errors)
}

Sanitizer 表示对一个查询参数构成的结构体进行数据验证和内容修正的接口

type Unmarshaler

type Unmarshaler interface {
	// data 表示由查询参数传递过来的单个值。
	UnmarshalQuery(data string) error
}

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
    }
}

NOTE: 空值不会调用该接口。