操作与中间件 - 结构体类型Handler

优质

小牛编辑

134浏览

2023-12-01

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)来修改全局默认的解析方法。