go struct标签详解

结构体标签

标签定义

Tag是结构体在编译阶段关联到成员的元信息字符串，在运行的时候通过反射的机制读取出来。

结构体标签由一个或多个键值对组成。键与值使用冒号分隔，值用双引号括起来。键值对之间使用一个空格分隔，具体的格式如下：

`key1:"value1" key2:"value2" key3:"value3"...`  // 键值对用空格分隔
复制代码

key会指定反射的解析方式，如下： json(JSON标签) orm(Beego标签)、gorm(GORM标签)、bson(MongoDB标签)、form(表单标签)、binding(表单验证标签)

标签选项

type Student struct {
    ID   int     `json:"-"`            // 该字段不进行序列化
    Name string  `json:name,omitempy`  // 如果为类型零值或空值，序列化时忽略该字段
    Age  int     `json:age,string`     // 指定类型，支持string、number、boolen
}
复制代码

注：encoding/json官方文档

json标签

JSON说明

JSON数组可以用于编码Go语言的数组和slice；由于JSON对象是一个字符串到值的映射，写成一系列的name:value对形式，因此JSON的对象类型可以用于编码Go语言的map和结构体。

将Go语言中结构体slice转为JSON的过程叫编组(marshaling)，编组通过json.Marshal函数完成。在编码时，默认使用Go语言结构体的成员名字作为JSON的对象（通过reflect反射技术）。只有导出的结构体成员才会被编码。

如果在结构体slice编码成JSON的时候使用自定义的成员名，可以使用结构体成员Tag来实现。

JSON标签

type User struct {
    ID   int `json:"id"`  // 编码后的字段名为 id
    Name string           // 编码后的字段名为 自定义成员名 Name
    age  int              // 未导出字段不能编码
}
复制代码

json为键名的标签对应的值用于控制encoding/json包的编码和解码的行为，并且encoding/...下面其它的包也遵循这个约定。

gorm标签

模型定义

模型是标准的 struct,由基本数据类型以及实现了 Scanner 和 Valuer 接口的自定义类型及其指针或别名组成。

GORM 定义一个 gorm.Model 结构体，如下所示：

type Model struct {
  ID        uint           `gorm:"primaryKey"`
  CreatedAt time.Time
  UpdatedAt time.Time
  DeletedAt gorm.DeletedAt `gorm:"index"`
}
复制代码

gorm为键名的标签遵循GORM的解析规则，GORM支持如下tag，tag名大小写不敏感，建议使用camelCase风格，多个标签定义用分号(;)分隔

[知识点] Gorm建表时 AUTO_INCREMENT 不生效的问题

// AUTO_INCREMENT 不生效
Id  uint64 `gorm:"column:id;primaryKey;type:bigint(20);autoIncrement;comment:'主键'"`
// AUTO_INCREMENT 不生效
Id  uint64 `gorm:"column:id;type:bigint(20);autoIncrement;comment:'主键'"`
// AUTO_INCREMENT 生效 gorm会自动根据字段类型设置数据库字段类型并设置为主键
Id  uint64 `gorm:"column:id;autoIncrement;comment:'主键'"` //写成AUTO_INCREMENT也可以
复制代码

示例：

// 内容模型
type Content struct {
    Model
    NewsId   uint64  `gorm:"column:news_id"`
    Content  string  `gorm:"column:content"`
}
复制代码

知识点 自定义唯一索引

// Go 版本：go1.16.6   Gorm 版本：v1.9.16
// 尝试用 uniqueIndex 创建不生效,有解决方法的同学欢迎评论区留言 普通索引是生效的
Email string `gorm:"column:email;type:varchar(50);uniqueIndex:uidx_email"` // 不生效
Email string `gorm:"column:email;type:varchar(50);index:idx_email"`        // 生效

// 创建唯一索引 建表时会创建名称为 email 的唯一索引
Email string `gorm:"column:email;type:varchar(50);unique"`
// 创建自定义名称 uidx_email 的唯一索引
Email string `gorm:"column:email;type:varchar(50)" sql:"unique_index:uidx_email"`
复制代码

知识点 自动更新时间

GORM约定使用CreatedAt、UpdatedAt追踪创建/更新时间。如果定义了这种字段，且默认值为零值，GORM在创建、更新时会自动填充当前时间。要使用不同名称的字段，您可以配置autoCreateTime、autoUpdateTime标签，如果想要保存 UNIX（毫/纳）秒时间戳，而不是 time，只需简单地将 time.Time 修改为 int 即可，毫/纳秒参数可以看上面表格示例。

// 时间自动创建和更新
type User struct { 
    // 自定义字段  使用时间戳填纳秒数充更新时间 
    Updated   int64 `gorm:"autoUpdateTime:nano"` 
    //自定义字段  使用时间戳毫秒数填充更新时间 
    Updated   int64 `gorm:"autoUpdateTime:milli"` 
    //自定义字段  使用时间戳秒数填充创建时间 
    Created   int64 `gorm:"autoCreateTime"` 
    // 默认创建时间字段  在创建时如果该字段值为零值，则使用当前时间填充 
    CreatedAt time.Time 
    // 默认更新时间字段  在创建时该字段值为零值或者在更新时，使用当前时间戳秒数填充 
    UpdatedAt int      
}
复制代码

注：GORM模型 官方文档

关联标签

GORM的关联类型有多重类型：belongs to、has one、has many、many to many具体结构体定义可参考问文档，关联模式使用的标签选项如下所示：

示例：

// 新闻模型
type News struct {
    Model
    Title   string   `gorm:"column:title;type:string;not null,default:''"`
    Content Content  `gorm:"foreignKey:NewsId" json:"content"` //指定外键
}
复制代码

注：GORM关联模型 官方文档

form标签

Gin中提供了模型绑定，将表单数据和模型进行绑定，方便参数校验和使用。

模型绑定

// 表单数据
type LoginForm struct {
    Email     string    `form:"emial"`    
    Password  string    `form:"password"`
}
// model 或 service 层Model
type Email struct {
    Email       string
    Password    string
}
复制代码

通过 form:"email" 对表单email数据进行绑定。然后通过Bind()、ShouldBind()等方法获取参数值。

func EmailLogin (c *gin.Context) {
    var email LoginForm
    if err := c.ShouldBind(&email); err != nil {
        ...
    }
    // 获取表单数据局
    args := Email {
        Email:     email.Email,
        Password:  email.Password,
    }
    // 对参数进行后续使用
    ...
}
复制代码

binding标签

Gin对于数据的校验使用的是 validator.v10 包，该包提供多种数据校验方法，通过binding:""标签来进行数据校验。

我们对上面的表单模型添加数据校验标签如下：

type LoginForm struct {
    Email     string    `form:"emial" binding:"email"`    
    Password  string    `form:"password" binging:"required,min=6,max=10"`
}
复制代码

特殊符号说明：

• 逗号（,）:分隔多个标签选项，逗号之间不能有空格，否则panic；
• 横线（-）:跳过该字段不做校验；
• 竖线（|）:使用多个选项，满足其中一个即可。

binding标签选项：

必需校验

范围校验

范围验证: 切片、数组和map、字符串，验证其长度；数值，验证大小范围

示例：

type User struct {
    Name string `form:"name" binding:"required,min=1,max=10"`
    Age  unit8  `form:"age" binding:"lte=150,gte=0"`
    sex  string `form:"sex" binding:"oneof=male female"`
}
复制代码

注：文档地址

字符串校验

示例：

type User struct {
    Name string `form:"name" binding:"required,contains=ac,endswith=ck"`
}
复制代码

注：文档地址

字段校验

示例：

// 跨不同结构体字段相等
type Struct1 struct { 
    Field1 string `validate:eqcsfield=Struct2.Field2` 
    Struct2 struct { 
        Field2 string 
    } 
}
// 同一结构体字段相等验证
type Email struct { 
    Email  string `validate:"lte=4"` 
    Pwd    string `validate:"min=10"` 
    Pwd2   string `validate:"eqfield=Pwd"`
}
// 同一结构体字段验证不相等
type User struct { 
    Name     string `validate:"lte=4"` 
    Age      int `validate:"min=20"` 
    Password string `validate:"min=10,nefield=Name"`
}
复制代码

其他校验

示例：

type User struct { 
    Name     string  `validate:"required,min=1,max=10"` 
    Email    int     `validate:"required,email"`
    birthday string  `validate:"datetime=2006-01-02"`
    Pwd      string  `validate:"required,alphanum"`
    Score    srring  `validate:"numeric"`
}
复制代码

注：文档地址

ini标签

在使用go-ini库操作.ini配置文件的时候，如果需要将配置文件字段映射到结构体变量，如果键名与字段名不相同，那么需要在结构标签中指定对应的键名。标准库encoding/json、encoding/xml解析时可以将键名app_name对应到字段名AppName，而go-ini库不可以，所以需要在结构体标签指定对应键名。

## 配置文件 cnf.ini
app_name  = awesome web
log_level = DEBUG
复制代码

// 配置文件映射 结构体
type Config struct {
  AppName   string `ini:"app_name"`  // ini标签指定下键名
  LogLevel  string `ini:"log_level"`
}
复制代码

参考文章

• GORM文档
• golang常用库：字段参数验证库-validator使用
• go-playground/validator 的常用关键字
• Go每日一库go-ini

作者：紬绎青蛙 链接：https://juejin.cn/post/7005465902804123679