Go 结构体标签

在 Go 语言中,如果需要让结构体字段跨包使用,字段名的首字母就必须大写,比如写成 UserName、UserAge。但在实际开发中,把数据转成 JSON 格式发给前端网页或手机 App 时,对方通常要求字段名采用全小写或下划线格式(如 "user_name")。

为了给结构体附加这类字段转换规则,Go 语言提供了 “结构体标签(struct tag)” 语法。其中,“tag” 是 “标签” 的意思。

结构体标签语法

在定义结构体时,结构体标签紧跟在字段的数据类型后面,使用一对英文反引号(`)括起来,这与前面定义多行字符串使用的符号相同。

结构体标签就像贴在快递盒外面的 “分拣条码”。平时我们在 Go 代码里直接读写结构体字段时,标签不会产生任何影响。只有把结构体交给 encoding/json 等标准库处理时,标准库才会在底层通过反射读取反引号里的配置规则。

Go 结构体标签的读取生效机制

语法:

type 结构体名 struct {
    字段名 字段类型 `键1:"值1" 键2:"值2"`
}

说明:

反引号内部由一个或多个 键:"值" 形式的键值对组成。其中,“键” 用来指定这个标签是给哪个库看的,比如 json 表示给 JSON 标准库使用,db 表示给数据库框架使用。英文双引号里面的 “值” 则是具体的配置规则。

常用 json 结构体标签

在实际开发中,结构体标签最常用的场景就是配合 encoding/json 标准库控制 JSON 数据的字段名和输出格式。常用的 json 标签写法如下表所示。

常用 json 标签
标签写法 说明
`json:"name"` 指定 JSON 字段名
`json:"-"` 始终忽略并隐藏该字段
`json:"name,omitempty"` 值为默认零值时自动省略
`json:"name,string"` 将数字或布尔值转为字符串

下面我们通过 3 个例子来看看这些标签的具体用法。为了直观看到转换效果,示例中会先借用标准库的 json.Marshal() 函数把结构体转成 JSON 文本,具体用法后面在 “JSON 解析与序列化” 一节中还会详细介绍。

示例 1:指定 JSON 字段名

package main

import (
    "encoding/json"
    "fmt"
)

// 不带标签的结构体
type User1 struct {
    UserName string
    UserAge  int
}

// 带有 json 标签的结构体
type User2 struct {
    UserName string `json:"user_name"`
    UserAge  int    `json:"user_age"`
}

func main() {
    u1 := User1{UserName: "Jack", UserAge: 20}
    data1, _ := json.Marshal(u1)
    fmt.Println(string(data1))

    u2 := User2{UserName: "Jack", UserAge: 20}
    data2, _ := json.Marshal(u2)
    fmt.Println(string(data2))
}

运行结果如下。

{"UserName":"Jack","UserAge":20}
{"user_name":"Jack","user_age":20}

分析:

在这个例子中,json.Marshal() 会返回转换后的字节切片([]byte)和错误结果共 2 个返回值。这里我们使用下划线 _ 忽略第 2 个返回值,再通过 string(data1) 将字节切片转成字符串打印出来。

对比两行输出结果可以看出:User1 没有添加结构体标签,转换出的 JSON 默认保留原有的大写字段名。而 User2 配置了 json:"user_name" 和 json:"user_age" 标签,输出时就会采用指定的小写名称。

反过来,以后把 JSON 数据解析回结构体时,标准库同样会根据这套标签自动匹配字段。

在实际项目中,像用户密码这类敏感信息不能发给前端,而像邮箱这类选填项为空时也不希望输出多余字段。此时又应该怎么配置标签呢?请看下面例子。

示例 2:隐藏字段与省略零值

package main

import (
    "encoding/json"
    "fmt"
)

type Account struct {
    Username string `json:"username"`
    Password string `json:"-"`
    Email    string `json:"email,omitempty"`
}

func main() {
    acc := Account{
        Username: "Jack",
        Password: "123456",
        Email:    "",
    }

    data, _ := json.Marshal(acc)
    fmt.Println(string(data))
}

运行结果如下。

{"username":"Jack"}

分析:

Password 字段后面的 json:"-" 表示在转换成 JSON 时始终忽略该字段,不会输出到结果中,常用于保护密码、密钥等敏感信息。

可能有些小伙伴会觉得奇怪:“既然首字母小写的字段本来就不会转成 JSON,为什么密码还要写成大写的 Password 再加 json:"-" 呢?”

其实道理很简单。在 Go 项目内部,登录校验或数据库读写等其他包的代码都需要访问 acc.Password,所以字段首字母必须大写公开。但把数据转成 JSON 返回给前端时,又必须把密码藏起来,这时就需要加上 json:"-" 了。

Email 字段后面的 json:"email,omitempty" 使用了 omitempty 选项,其中 “omit(省略)” 和 “empty(空)” 合起来,表示字段为默认零值时自动省略。书写时要注意,字段名与 omitempty 之间用英文逗号紧挨着连接,逗号前后不能有空格。

注意: omitempty 判断的 “空” 指的是 Go 语言各数据类型的默认零值。除了空字符串 "" 之外,整数 0 和布尔值 false 也会被当成零值直接省掉。因此,如果某个字段的数值 0 具有实际业务含义(比如考试得分为 0),小伙伴们就不要给它添加 omitempty 选项。

此外,同一个结构体在后端开发中通常既要转成 JSON 返回给前端,又要存入数据库表中。我们也可以在一对反引号里同时添加多个不同用途的标签。

示例 3:同时添加多个标签

package main

import (
    "encoding/json"
    "fmt"
)

type Staff struct {
    ID   int64  `json:"id,string" db:"staff_id"`
    Name string `json:"name" db:"staff_name"`
}

func main() {
    s := Staff{ID: 1001, Name: "Lucy"}
    data, _ := json.Marshal(s)
    fmt.Println(string(data))
}

运行结果如下。

{"id":"1001","name":"Lucy"}

分析:

在 Staff 结构体中,我们在同一对反引号里同时写上了 json 标签和 db 标签,中间使用英文空格隔开。同时,json:"id,string" 把整数编号 1001 转成了带双引号的字符串 "1001" 输出。

为什么后端经常把 int64 编号转成字符串发给前端呢?因为前端 JavaScript 处理超过 16 位的超长整数(比如分布式订单号)时容易丢失末尾精度,加上 ,string 转成字符串就能彻底避开这个问题。

书写标签的注意事项

需要注意的是,结构体标签本质上只是一段普通字符串。一旦里面的格式敲错了,编译器在编译阶段并不会报错,只会让标签失去作用,因此小伙伴们平时书写时一定要留心以下 3 点:

  • 冒号前后不能有空格:键与值之间紧跟英文冒号(:),我们必须写成 json:"id",不能在冒号后面多敲空格。
  • 多个标签之间用空格隔开:如果一个字段同时带有多个标签,标签与标签之间使用英文空格分隔,不能使用逗号分隔。
  • 字段名首字母必须大写:只有首字母大写的公开字段,才能被 encoding/json 等外部包访问并读取标签。

日常写代码时,以下 3 种错法最容易导致标签不生效:

// 错误方式 1
ID int `json: "id"`

// 错误方式 2
ID int `json:"id", db:"staff_id"`

// 错误方式 3
id int `json:"id"`

在上面代码中,错误方式 1 在冒号后面多加了空格,错误方式 2 误用逗号分隔两个标签。错误方式 3 则把字段名 id 写成了小写,属于未公开字段,转换时会被直接忽略。平时只要发现导出的 JSON 字段名不对或少了字段,优先排查这 3 个地方即可。

给站长反馈

绿叶网正在不断完善中,小伙伴们如果发现任何问题,还望多多给站长反馈,谢谢!

邮箱:lvyenet@vip.qq.com

「绿叶网」服务号
绿叶网服务号放大
关注服务号,微信也能看教程。
绿叶网服务号