参数规则

概述

在 go-zero 中,我们通过 api 语言来声明 HTTP 服务,然后通过 goctl 生成 HTTP 服务代码,在之前我们系统性的介绍了 API 规范

在 go-zero 中已经内置了一些参数校验的规则,接下来我们来看一下 go-zero 中的参数接收/校验规则吧。

参数接收规则

在 api 描述语言中,我们可以通过在 tag 中来声明参数接收规则,目前 go-zero 支持的参数接收规则如下:

参数规则 - 图1接收规则说明参数规则 - 图2生效范围示例
jsonjson 序列化请求体&响应体json:"foo"
path路由参数请求体path:"id"
formpost 请求的表单(支持 content-type 为 form-datax-www-form-urlencoded) 参数请求接收标识,get 请求的 query 参数接收标识请求体form:"name"
headerhttp 请求体接收标识请求体header:"Content-Length"
参数规则 - 图3温馨提示

go-zero 中不支持多 tag 来接收参数,即一个字段只能有一个 tag,如下写法可能会导致参数接收不到:

  1. type Foo {
  2. Name string `json:"name" form:"name"`
  3. }

参数校验规则

在 api 描述语言中,我们可以通过在 tag 中来声明参数接收规则,除此之外,还支持参数的校验,参数校验的规则仅对 请求体 有效,参数校验的规则写在 tag value中,目前 go-zero 支持的参数校验规则如下:

参数规则 - 图4接收规则说明示例
optional当前字段是可选参数,允许为零值(zero value)json:"foo,optional"
options当前参数仅可接收的枚举值json:"gender,options=[foo,bar]"
default当前参数默认值json:"gender,default=male"
range当前参数数值有效范围,仅对数值有效,写法规则详情见下文温馨提示json:"age,range=[0:120]"
参数规则 - 图5range 表达式值规则
  1. 左开右闭区间:(min:max],表示大于 min 小于等于 max,当 min 缺省时,min 代表数值 0,当 max 缺省时,max 代表无穷大,min 和 max 不能同时缺省
  2. 左闭右开区间:[min:max),表示大于等于 min 小于 max,当 max 缺省时,max 代表数值 0,当 min 缺省时,min 代表无穷大,min 和 max 不能同时缺省
  3. 闭区间:[min:max],表示大于等于 min 小于等于 max,当 min 缺省时,min 代表数值 0,当 max 缺省时,max 代表无穷大,min 和 max 不能同时缺省
  4. 开区间:(min:max),表示大于 min 小于 max,当 min 缺省时,min 代表数值 0,当 max 缺省时,max 代表无穷大,min 和 max 不能同时缺省