当前位置: 首页 > 文档资料 > Faygo 用户手册 >

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

优质
小牛编辑
130浏览
2023-12-01

4.2 结构体类型Handler

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

4.2.1 用法展示

示例:

  1. type Addition struct {
  2. // <in:query> 定义query类型请求参数;
  3. // 参数名为字段名转为默认的snake格式(默认格式可自定义),即'the_one';
  4. // 该参数值会被自动转为int类型;
  5. // <range: 0:100> 当其大小不在[0,100]范围时,faygo自动返回错误,错误模板可以自定义;
  6. // <desc:plus number> 定义参数描述为'plus number'
  7. TheOne int `param:"<in:query> <desc:plus number> <range: 0:100>"`
  8. // <in:query> 定义query类型请求参数;
  9. // <name:other> 参数名被指定为'other';
  10. // 该参数值会被自动转为int类型;
  11. // <desc:other plus number> 定义参数描述为'other plus number'
  12. OtherOne int `param:"<in:query> <name:other> <desc:other plus number>"`
  13. }
  14. // 实现Handler接口
  15. func (a *Addition) Serve(ctx *faygo.Context) error {
  16. return ctx.String(200, "(%d) + (%d) = %d", a.TheOne, a.OtherOne, a.TheOne+a.OtherOne)
  17. }

伪请求:

  1. 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示例

tagkeyrequiredvaluedesc
paramin有且只有一个path(参数位置)为空时自动补全,如URL http://www.abc.com/a/{path}
paramin有且只有一个query(参数位置)如URL http://www.abc.com/a?b={query}
paramin有且只有一个formData(参数位置)请求表单,如 a=123&b={formData}
paramin有且只有一个body(参数位置)请求Body
paramin有且只有一个header(参数位置)请求头
paramin有且只有一个cookie(参数位置)请求cookie,支持:*http.Cookiehttp.Cookiestring[]byte
paramname(如id)自定义参数名
paramrequiredrequired参数是否必须
paramdesc(如id)参数描述
paramlen(如3:6``3)字符串类型参数的长度范围
paramrange(如0:10)数字类型参数的数值范围
paramnonzerononzero是否能为零值
parammaxmb(如32)当前Content-Typemultipart/form-data时,允许使用的最大内存,当设置了多个时使用较大值
paramregexp(如^\w+$)使用正则验证参数值
paramerr(如密码格式错误)自定义参数绑定或验证的错误信息

NOTES:

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

4.2.3 Struct Handler 字段类型说明

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

baseslicespecial
string[]string[][]byte
byte[]byte[][]uint8
uint8[]uint8*multipart.FileHeader (仅formData参数使用)
bool[]bool[]*multipart.FileHeader (仅formData参数使用)
int[]int*http.Cookie (仅net/http下的cookie参数使用)
int8[]int8http.Cookie (仅net/http下的cookie参数使用)
int16[]int16struct (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)来修改全局默认的解析方法。