Go语言中结构体JSON Tag用法详解与示例

JSON Tag完整语法与核心选项

Go语言中，结构体字段的JSON Tag位于该字段定义的反引号（backtick）内，格式以 json:"..." 开头。其完整语法如下：

• 基本格式：json:"FieldName/-/可选1,可选2"
• 选项分隔符多个选项之间必须使用英文逗号 , 分隔。
• FieldName（键名）：指定JSON输出时的字段名称。
  • 若留空（如 json:",omitempty"），则使用结构体字段的原始名称作为键名。
  • 若指定具体名称（如 json:"user_name"），则使用该名称作为键名。
  • 若值为 -（即 json:"-"），表示编码时忽略此字段。
• omitempty（忽略空值）：当字段值为零值或空值时，不进行编码输出。
  • 零值判定：布尔型 false、数值型 0、指针 nil、接口 nil、以及空数组、空切片、空Map和空字符串。
• string（字符串化）：将非字符串类型的字段值转换为JSON字符串。
  • 适用于 int、float、bool 等基础类型。
  • 常用于解决JavaScript前端处理大整数精度丢失的问题。
  • 注意：如果字段本身是 string 类型，加上此选项会导致双重引号（如 "\"value\""）。

第1步：定义结构体并应用标签

创建一个测试结构体，混合使用各种Tag选项，以便观察不同参数的效果。

package main

import (
	"encoding/json"
	"fmt"
	"os"
)

func main() {
	type ColorGroup struct {
		Hello   bool       `json:"Hello,string"`
		world   bool       `json:"World,string"`
		ID      int        `json:"id,string"`
		Name    string     `json:"name,string"`
		Colors  []string   `json:"ColorName,omitempty"`
		Colors1 []string   `json:"ColorName1"`
		Colors2 []string   `json:"ColorName2"`
	}

	// 初始化数据
	group := ColorGroup{
		Hello:   true,
		world:   true,
		ID:      1,
		Name:    "Reds",
		Colors:  []string{"hello", "world"},
		Colors1: nil,
		Colors2: []string{},
	}

	// 执行编码
	b, err := json.Marshal(group)
	if err != nil {
		fmt.Println("error:", err)
	}
	os.Stdout.Write(b)
}

第2步：编译运行并观察结果

运行上述代码，终端输出的JSON内容如下：

{"Hello":"true","id":"1","name":"\"Reds\"","ColorName":["hello","world"],"ColorName1":null,"ColorName2":[]}

解析关键点：

• Hello 和 id：因为加了 string 选项，原本的类型变成了字符串。
• Name：字段类型为 string 且加了 string 选项，导致值被再次引用包裹（双引号）。
• ColorName：因为有数据，正常输出数组；若为空则因 omitempty 不会出现在JSON中。
• ColorName1：值为 nil 切片，根据Go标准库规则，nil 切片编码为 null。
• ColorName2：值为空切片 []，编码为 []。

特殊注意事项与边界情况

在实际工程使用中，有几个容易混淆的细节需要特别关注：

1. 横杠“-”的歧义处理

• json:"-"：表示完全忽略该字段，不生成任何JSON键值对。
• json:"-,"：这里的 - 实际上是字段名，后面跟随 omitempty 的效果（这里省略了omitempty，但逻辑上字段名为 -）。这表示生成一个名为 - 的JSON键。

2. Map类型的编码规则

• Map的键必须是字符串、整数类型或实现了 encoding.TextMarshaler 接口的类型。
• Map在编码为JSON对象时，其键会按照字母顺序（字符串）或数值大小（整数）进行排序。

3. 指针与接口的编码

• 指针：如果指针不为 nil，编码其指向的值；如果为 nil，编码为 null。
• 接口：编码接口内部持有的具体值；如果接口值为 nil，编码为 null。

官方Marshal机制简析

Go标准库 encoding/json.Marshal 遵循以下递归编码逻辑：

1. 优先检查自定义实现：如果类型实现了 json.Marshaler 接口（且不是nil指针），调用其方法；否则尝试 encoding.TextMarshaler。
2. 类型映射：
   • bool → JSON Boolean
   • float, int → JSON Number
   • string → JSON String（默认启用HTML转义，可通过Encoder配置关闭）
   • []byte → Base64字符串
   • struct → JSON Object
3. 匿名结构体处理：从Go 1.1开始，匿名结构体的可导出字段会被提升到外层结构中，但如果同层存在带 json 标签的字段，优先使用带标签的字段以避免冲突。

总结

掌握 json 标签是Go Web开发和API设计的基石。合理使用 omitempty 可以减少网络传输体积，利用 string 可以避免大数精度问题，而明确 - 的使用场景能有效清理敏感或不必要的数据。以上就是Go语言中JSON Tag用法的详细内容，更多关于Go语言结构体序列化的资料请关注本站其它相关文章！