goframe结构体标签和命令行标签

元数据gmeta

基础标签

更多了解：https://swagger.io/specification/

g.Meta `path:"/profile" method:"get" summary:"展示个人资料页面" tags:"个人"`
g.Meta `mime:"text/html" type:"string" example:"<html/>"`

常见 OpenAPIv3 标签	说明	备注
path	结合注册时的前缀共同构成接口 URI 路径	用于 g.Meta 标识接口元数据
tags	接口所属的标签，用于接口分类	用于 g.Meta 标识接口元数据
method	接口的请求方式：GET/PUT/POST/DELETE…(不区分大小写)	用于 g.Meta 标识接口元数据
deprecated	标记该接口废弃	用于 g.Meta 标识接口元数据
summary	接口/参数概要描述	缩写 sm
description	接口/参数详细描述	缩写 dc
in	参数的提交方式：header/path/query/cookie
default	参数的默认值	缩写 d
mime	接口的 MIME 类型，例如 multipart/form-data，默认为 application/json。	用于 g.Meta 标识接口元数据
type	参数的类型，特殊参数需要手动设置，例如 file	仅用于参数属性

扩展标签

在OpenAPI规范里面，所有名称以x-开头的标签是开发者可自定义的扩展标签。扩展标签可以在任意的接口、属性中以Golang struct tag的形式定义，在接口文档生成时，将会作为独立的字段返回。例如：

type GetListReq struct {g.Meta `path:"/user" tags:"User" method:"get" x-group:"User/Info" summary:"Get user list with basic info."`Page   int `dc:"Page number" d:"1" x-sort:"1"`Size   int `dc:"Size for per page." d:"10" x-sort:"2"`
}

struct tag标签

Tag(简写)	全称	描述	相关文档
v	valid	数据校验标签。	Struct 校验 - 基本使用
p	param	自定义请求参数匹配。	请求输入 - 对象处理
d	default	请求参数默认值绑定。	请求输入 - 默认值绑定
orm	orm	ORM 标签，用于指定表名、关联关系。	数据规范 - gen dao / 模型关联 - 静态关联 - With 特性
dc	description	通用结构体属性描述，ORM 和接口都用到。属于框架默认的属性描述标签。

参数映射:p/param/params

使用了p标签来指定该属性绑定的参数名称。password1参数将会映射到Pass1属性，password2将会映射到Pass2属性上。其他属性采用默认的转换规则即可，无需设置tag。

type User struct{Id    intName  stringPass1 string `p:"password1"`Pass2 string `p:"password2"`
}

转换：json

如果对象没有绑定json标签，因此返回的JSON字段将会为其属性名称。

type RegisterRes struct {Code  int          Age int    `json:"age"`Pwd *struct{} `json:"pwd,omitempty"`// 这里的字段json名需要和嵌套的字段json名一致，否则无效
}

默认值绑定: default/d

从v1.15版本开始，Request请求对象支持通过struct tag的方式为输入对象的属性绑定默认值。默认值的struct tag名称为d(也可以使用default)。

type GetListReq struct {g.Meta `path:"/" method:"get"`Type   string `v:"required#请选择内容模型" dc:"内容模型"`Page   int    `v:"min:0#分页号码错误"      dc:"分页号码" d:"1"`
}

描述：description/dc

type SellSpec struct {Id        uint        `description:"主键"`CreatedAt *gtime.Time `description:"创建时间"`UpdatedAt *gtime.Time `description:"更新时间"`
} 

校验tag规则：valid/v

文档链接：https://goframe.org/pages/viewpage.action?pageId=1114367

格式：[属性别名@]校验规则[#错误提示]

• 属性别名 和 错误提示 为非必需字段，校验规则 是必需字段。
• 属性别名 非必需字段，指定在校验中使用的对应struct属性的别名，同时校验后返回的error对象中的也将使用该别名返回。例如在处理请求表单时比较有用，因为表单的字段名称往往和struct的属性名称不一致。大部分场景下不需要设置属性别名，默认直接使用属性名称即可。
• 校验规则则为当前属性的校验规则，多个校验规则请使用|符号组合，例如：required|between:1,100。
• 错误提示 非必需字段，表示自定义的错误提示信息，当规则校验时对默认的错误提示信息进行覆盖。

type User struct {Uid   int    `v:"uid      @integer|min:1#|请输入用户ID"`Name  string `v:"name     @required|length:6,30#请输入用户名称|用户名称长度非法"`Pass2 string `v:"password2@required|password3|same:Pass1#|密码格式不合法|两次密码不一致，请重新输入"`
}

参数的提交方式: in

header/path/query/cookie

命令管理：预定义的标签

在结构化设计中，我们使用了一些结构体标签，大部分来源于Command命令的属性，这里我们来介绍一下：

标签	缩写	说明	注意事项
name	-	命名名称	如果是输入参数结构体，在未指定 name 时将会自动读取方法名称作为 name
short	-	命令缩写
usage	-	命令使用
brief	-	命令描述
arg	-	表示该输入参数来源于参数而不是选项	仅用于属性标签
orphan	-	表示该选项不带参数	属性通常为 bool 类型
description	dc	命令的详细介绍
additional	ad	命令的额外描述信息
examples	eg	命令的使用示例
root	-	指定子级命令名称是父级命令	仅用于主命令对象结构体 Meta 标签
strict	-	表示该命令严格解析参数/选项	当输入不支持的参数/选项时，返回错误
config	-	表示该命令的选项数据支持从指定的配置读取	配置来源于默认的全局单例配置对象