结构体类型Handler

4.2 结构体类型Handler

当Handler中依赖较多的请求参数时，建议使用结构体类型。因为结构体类型的Handler支持自动绑定与校验请求参数的功能。

4.2.1 用法展示

示例：

type Addition struct {
    // <in:query> 定义query类型请求参数；
    // 参数名为字段名转为默认的snake格式（默认格式可自定义），即'the_one'；
    // 该参数值会被自动转为int类型；
    // <range: 0:100> 当其大小不在[0,100]范围时，faygo自动返回错误，错误模板可以自定义；
    // <desc:plus number> 定义参数描述为'plus number'
    TheOne int `param:"<in:query> <desc:plus number> <range: 0:100>"`

    // <in:query> 定义query类型请求参数；
    // <name:other> 参数名被指定为'other'；
    // 该参数值会被自动转为int类型；
    // <desc:other plus number> 定义参数描述为'other plus number'
    OtherOne int `param:"<in:query> <name:other> <desc:other plus number>"`
}
// 实现Handler接口
func (a *Addition) Serve(ctx *faygo.Context) error {
    return ctx.String(200, "(%d) + (%d) = %d", a.TheOne, a.OtherOne, a.TheOne+a.OtherOne)
}

伪请求：

http://localhost:8080/addition?the_one=2&other=-1

4.2.2 Struct Handler 字段标签

struct Hanlder 使用结构体标签来定义参数信息。其中参数位置in符合OpenAPI 2.0标准（Swagger2.0）。
见4.2.1示例

tag key required value desc
param in 有且只有一个 path （参数位置）为空时自动补全，如URL http://www.abc.com/a/{path}
param in 有且只有一个 query （参数位置）如URL http://www.abc.com/a?b={query}
param in 有且只有一个 formData （参数位置）请求表单，如 a=123&b={formData}
param in 有且只有一个 body （参数位置）请求Body
param in 有且只有一个 header （参数位置）请求头
param in 有且只有一个 cookie （参数位置）请求cookie，支持：*http.Cookie、http.Cookie、string、[]byte等
param name 否 (如id) 自定义参数名
param required 否 required 参数是否必须
param desc 否 (如id) 参数描述
param len 否 (如3:6``3) 字符串类型参数的长度范围
param range 否 (如0:10) 数字类型参数的数值范围
param nonzero 否 nonzero 是否能为零值
param maxmb 否 (如32) 当前Content-Type为multipart/form-data时，允许使用的最大内存，当设置了多个时使用较大值
param regexp 否 (如^\w+$) 使用正则验证参数值
param err 否 (如密码格式错误) 自定义参数绑定或验证的错误信息

NOTES :

  • 绑定的对象必须为结构体指针类型
  • 除*multipart.FileHeader外，绑定的结构体字段类型不能为指针类型
  • 只有在param:"type(xxx)"存在时，regexp 和 param 标签才有效
  • 若param标签不存在，将尝试解析结构体或结构体指针类型的匿名字段
  • 当结构体标签in为formData且字段类型为*multipart.FileHeader、multipart.FileHeader、[]*multipart.FileHeader或[]multipart.FileHeader时，该参数接收文件类型
  • 当结构体标签in为cookie，字段类型必须为*http.Cookie或http.Cookie
  • 标签in(formData)和in(body)不能同时出现在同一结构体
  • 不能存在多个in(body)标签

4.2.3 Struct Handler 字段类型说明

struct Hanlder 用于绑定请求参数的字段类型具有一定限制（可以由参数值string类型转换的类型本就是有限的），应该在以下范围内：

base slice special
string []string [][]byte
byte []byte [][]uint8
uint8 []uint8 *multipart.FileHeader (仅formData参数使用)
bool []bool []*multipart.FileHeader (仅formData参数使用)
int []int *http.Cookie (仅net/http下的cookie参数使用)
int8 []int8 http.Cookie (仅net/http下的cookie参数使用)
int16 []int16 struct (body参数使用或用于匿名字段扩展参数)
int32 []int32
int64 []int64
uint8 []uint8
uint16 []uint16
uint32 []uint32
uint64 []uint64
float32 []float32
float64 []float64

4.2.4 JSON等Body解析

使用<in:body>标签来解析JSON、XML等类型的请求体。默认为JSON解析方法。Handler通过增加Decode(dest reflect.Value, body []byte) error方法，可以自定义body参数解析方法。

或者，通过调用func SetBodydecoder(bodydecoder apiware.Bodydecoder)来修改全局默认的解析方法。