在 Go 语言中,如果需要让结构体字段跨包使用,字段名的首字母就必须大写,比如写成 UserName、UserAge。但在实际开发中,把数据转成 JSON 格式发给前端网页或手机 App 时,对方通常要求字段名采用全小写或下划线格式(如 "user_name")。
为了给结构体附加这类字段转换规则,Go 语言提供了 “结构体标签(struct tag)” 语法。其中,“tag” 是 “标签” 的意思。
结构体标签语法
在定义结构体时,结构体标签紧跟在字段的数据类型后面,使用一对英文反引号(`)括起来,这与前面定义多行字符串使用的符号相同。
结构体标签就像贴在快递盒外面的 “分拣条码”。平时我们在 Go 代码里直接读写结构体字段时,标签不会产生任何影响。只有把结构体交给 encoding/json 等标准库处理时,标准库才会在底层通过反射读取反引号里的配置规则。

语法:
type 结构体名 struct {
字段名 字段类型 `键1:"值1" 键2:"值2"`
}说明:
反引号内部由一个或多个 键:"值" 形式的键值对组成。其中,“键” 用来指定这个标签是给哪个库看的,比如 json 表示给 JSON 标准库使用,db 表示给数据库框架使用。英文双引号里面的 “值” 则是具体的配置规则。
常用 json 结构体标签
在实际开发中,结构体标签最常用的场景就是配合 encoding/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 个地方即可。
