Golang JSON序列化：理解字段可见性与struct标签的应用

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Golang JSON序列化：理解字段可见性与struct标签的应用

2025-11-24

浏览次数：次

返回列表

Golang JSON序列化：理解字段可见性与struct标签的应用

本文深入探讨了go语言中结构体字段在json序列化时遇到的常见问题：当结构体字段以小写字母开头时，`json.marshal`为何无法正确生成json输出。文章详细解释了go语言的字段可见性规则（导出与未导出），阐明了`json.marshal`仅能访问导出字段的原理。此外，教程还提供了两种解决方案：将字段名首字母大写以导出字段，以及使用`json` struct标签来自定义json输出字段名，即使go字段名已导出，也能实现灵活的json映射。

理解Go语言的字段可见性与JSON序列化

在Go语言中，进行JSON序列化时，开发者可能会遇到一个常见且令人困惑的现象：当结构体（struct）的字段名以小写字母开头时，json.Marshal函数生成的JSON字符串会是一个空的JSON对象{}。而将字段名首字母改为大写后，序列化则能正常进行。这并非Go语言的bug，而是其核心设计理念——可见性规则（Visibility Rules）——在起作用。

问题现象示例

考虑以下Go结构体定义：

type Machine struct {
  m_ip     string
  m_type   string
  m_serial string
}

当我们尝试将其序列化为JSON时：

import (
    "encoding/json"
    "fmt"
)

func main() {
    m := &Machine{m_ip: "192.168.1.1", m_type: "Server", m_serial: "ABC123XYZ"}
    m_json, err := json.Marshal(m)
    if err != nil {
        fmt.Println("Error marshalling:", err)
        return
    }
    fmt.Println(string(m_json)) // 输出: {}
}

上述代码的输出将是{}，这表明结构体中的字段并未被正确序列化。

Go语言的可见性规则

Go语言使用首字母的大小写来决定一个标识符（变量、函数、结构体字段等）在其包内外的可见性：

导出（Exported）标识符： 如果标识符的首字母是大写，则它是一个导出标识符。这意味着它可以在当前包外部被访问和使用。
未导出（Unexported）标识符： 如果标识符的首字母是小写，则它是一个未导出标识符。这意味着它只能在当前包内部被访问和使用。

json.Marshal函数是encoding/json包的一部分。当它尝试序列化一个结构体时，它需要访问结构体中的字段。根据Go的可见性规则，json.Marshal只能“看到”并访问那些被导出的字段。对于未导出的字段（即首字母小写的字段），json.Marshal无法访问，因此在序列化时会被忽略，导致它们不会出现在最终的JSON输出中。

在上面的示例中，m_ip、m_type和m_serial都是以小写字母开头的，它们是未导出的字段，因此json.Marshal无法对其进行序列化。

解决方案一：导出结构体字段

最直接的解决方案是将结构体中需要序列化的字段首字母改为大写，使其成为导出字段。

type Machine struct {
  MachIp     string
  MachType   string
  MachSerial string
}

现在，当我们再次尝试序列化：

import (
    "encoding/json"
    "fmt"
)

func main() {
    m := &Machine{MachIp: "192.168.1.1", MachType: "Server", MachSerial: "ABC123XYZ"}
    m_json, err := json.Marshal(m)
    if err != nil {
        fmt.Println("Error marshalling:", err)
        return
    }
    fmt.Println(string(m_json))
}

输出将是：

美图云修

商业级AI影像处理工具

50 查看详情美图云修

{"MachIp":"192.168.1.1","MachType":"Server","MachSerial":"ABC123XYZ"}

这证明了将字段导出后，json.Marshal能够成功访问并序列化它们。

解决方案二：使用JSON Struct Tag（推荐）

虽然将字段首字母大写可以解决序列化问题，但在某些情况下，我们可能希望JSON输出的字段名保持小写或具有特定的命名风格（例如，snake_case）。这时，Go语言的struct tag就派上用场了。

通过在结构体字段声明后添加反引号（`）包裹的tag，我们可以为json.Marshal提供额外的指令，告诉它在序列化时如何处理该字段。对于JSON序列化，我们使用json:"field_name"的格式。

type Machine struct {
    MachIp     string `json:"m_ip"`
    MachType   string `json:"m_type"`
    MachSerial string `json:"m_serial"`
}

在这个例子中：

MachIp、MachType、MachSerial仍然是导出字段（首字母大写），因此json.Marshal可以访问它们。
json:"m_ip"这样的tag告诉json.Marshal，在生成JSON时，将MachIp字段映射为m_ip。

现在，再次运行序列化代码：

import (
    "encoding/json"
    "fmt"
)

func main() {
    m := &Machine{MachIp: "192.168.1.1", MachType: "Server", MachSerial: "ABC123XYZ"}
    m_json, err := json.Marshal(m)
    if err != nil {
        fmt.Println("Error marshalling:", err)
        return
    }
    fmt.Println(string(m_json))
}

输出将是：

{"m_ip":"192.168.1.1","m_type":"Server","m_serial":"ABC123XYZ"}

通过使用struct tag，我们既遵循了Go语言的可见性规则（字段为导出），又实现了JSON输出字段名的自定义，这在与外部API或前端进行数据交互时非常有用。

总结与注意事项

核心原则： json.Marshal只能序列化结构体中导出（首字母大写）的字段。
解决方案：
1. 将结构体字段的首字母改为大写，使其成为导出字段。
2. 使用json:"field_name" struct tag来自定义JSON输出字段名，同时保持Go结构体字段为导出状态。
最佳实践： 在Go语言中，推荐始终将需要序列化或在包外访问的结构体字段定义为导出字段（首字母大写）。如果需要自定义JSON输出的字段名，应优先使用struct tag，这提供了更大的灵活性和更好的代码可读性。
忽略字段： 如果希望某个导出字段不被序列化，可以使用json:"-" tag。
空值处理： 使用json:"field_name,omitempty" tag可以在字段值为其零值（例如，字符串为空，整数为0，切片为nil）时，不将其包含在JSON输出中。