Go 语言 JSON 序列化指南：解决 Marshal 返回空对象的问题-Golang-PHP中文网

Go 语言 JSON 序列化指南：解决 Marshal 返回空对象的问题

碧海醫心

发布： 2025-11-20 19:21:01

原创

455人浏览过

Go 语言 JSON 序列化指南：解决 Marshal 返回空对象的问题

go 语言的 `encoding/json` 包在序列化结构体时，仅处理可导出的（首字母大写）字段。当结构体字段未导出时，`json.marshal` 会生成一个空 json 对象 `{}`，其字节表示为 `[123 125]`。本文将深入解析 go 结构体字段的可导出性规则，并提供正确的结构体定义与 json 序列化方法，确保 go 结构体能够按预期转换为 json 格式，避免常见的序列化陷阱。

1. 理解 Go 语言的字段可导出性

在 Go 语言中，结构体字段的可见性由其首字母的大小写决定：

首字母大写：表示该字段是可导出（Exported）的，可以在包外部访问。encoding/json 包的 Marshal 函数在将结构体转换为 JSON 时，只会序列化这些可导出的字段。
首字母小写：表示该字段是不可导出（Unexported）的，只能在当前包内部访问。json.Marshal 会忽略这些字段，不会将其包含在生成的 JSON 输出中。

这是 Go 语言设计哲学的一部分，旨在通过命名约定来明确字段的可见性和可访问性，从而简化代码并减少不必要的依赖。

2. json.Marshal 的工作原理与常见问题

encoding/json 包提供 Marshal 函数，用于将 Go 值编码为 JSON 格式的字节切片（[]byte）。当 Marshal 遇到一个结构体时，它会遍历结构体的所有可导出字段，并根据其类型将其转换为相应的 JSON 值。

考虑以下 Go 结构体定义：

package main

import (
    "encoding/json"
    "fmt"
)

type Zoo struct {
    name    string   // 首字母小写，不可导出
    animals []Animal // 首字母小写，不可导出
}

type Animal struct {
    species string // 首字母小写，不可导出
    says    string // 首字母小写，不可导出
}

func main() {
    zoo := Zoo{
        name: "Magical Mystery Zoo",
        animals: []Animal{
            {"Cow", "Moo"},
            {"Cat", "Meow"},
            {"Fox", "???"},
        },
    }

    zooJson, err := json.Marshal(zoo)
    if err != nil {
        fmt.Println("Error marshaling:", err)
        return
    }

    fmt.Println("原始结构体:", zoo)
    fmt.Println("JSON 字节切片:", zooJson)
    fmt.Println("JSON 字符串:", string(zooJson)) // 将字节切片转换为字符串查看
}

登录后复制

运行上述代码，你会得到类似这样的输出：

原始结构体: {Magical Mystery Zoo [{Cow Moo} {Cat Meow} {Fox ???}]}
JSON 字节切片: [123 125]
JSON 字符串: {}

登录后复制

这里的 [123 125] 就是空 JSON 对象 {} 的 ASCII 编码字节切片。123 是 { 的 ASCII 值，125 是 } 的 ASCII 值。这表明 json.Marshal 成功地将 zoo 变量序列化成了一个 JSON 对象，但由于 Zoo 和 Animal 结构体中的所有字段都是不可导出的（首字母小写），Marshal 无法访问它们，因此生成了一个没有任何字段的空 JSON 对象。

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

要解决这个问题，只需将所有需要序列化到 JSON 中的结构体字段的首字母改为大写，使其成为可导出字段。

PhotoG

PhotoG是全球首个内容营销端对端智能体

121

查看详情

package main

import (
    "encoding/json"
    "fmt"
)

type Zoo struct {
    Name    string   // 首字母大写，可导出
    Animals []Animal // 首字母大写，可导出
}

type Animal struct {
    Species string // 首字母大写，可导出
    Says    string // 首字母大写，可导出
}

func main() {
    zoo := Zoo{
        Name: "Magical Mystery Zoo",
        Animals: []Animal{
            {"Cow", "Moo"},
            {"Cat", "Meow"},
            {"Fox", "???"},
        },
    }

    // 使用 json.MarshalIndent 格式化输出，提高可读性
    zooJson, err := json.MarshalIndent(zoo, "", "    ")
    if err != nil {
        fmt.Println("Error marshaling:", err)
        return
    }

    fmt.Println("原始结构体:", zoo)
    fmt.Println("JSON 字符串:\n", string(zooJson))
}

登录后复制

现在，运行修改后的代码，你将得到预期的 JSON 输出：

原始结构体: {Magical Mystery Zoo [{Cow Moo} {Cat Meow} {Fox ???}]}
JSON 字符串:
 {
    "Name": "Magical Mystery Zoo",
    "Animals": [
        {
            "Species": "Cow",
            "Says": "Moo"
        },
        {
            "Species": "Cat",
            "Says": "Meow"
        },
        {
            "Species": "Fox",
            "Says": "???"
        }
    ]
}

登录后复制

4. 进阶用法：使用 JSON Tag 控制字段名和行为

虽然导出字段解决了序列化问题，但有时我们希望 JSON 字段名与 Go 结构体字段名不同，或者控制某些字段的序列化行为（例如，当字段为空时省略）。这时可以使用结构体字段标签（json tag）。

package main

import (
    "encoding/json"
    "fmt"
)

type Zoo struct {
    Name    string   `json:"zoo_name"`             // JSON 字段名为 "zoo_name"
    Animals []Animal `json:"animal_list,omitempty"` // JSON 字段名为 "animal_list"，如果为空则省略
}

type Animal struct {
    Species string `json:"species_type"` // JSON 字段名为 "species_type"
    Says    string `json:"sound"`        // JSON 字段名为 "sound"
}

func main() {
    zoo := Zoo{
        Name: "Magical Mystery Zoo",
        Animals: []Animal{
            {"Cow", "Moo"},
            {"Cat", "Meow"},
            {"Fox", "???"},
        },
    }

    zooJson, err := json.MarshalIndent(zoo, "", "    ")
    if err != nil {
        fmt.Println("Error marshaling:", err)
        return
    }
    fmt.Println("使用 JSON Tag 后的 JSON 字符串:\n", string(zooJson))

    // 演示 omitempty 效果
    emptyZoo := Zoo{
        Name: "Empty Zoo",
        // Animals 字段未初始化，默认为 nil，会被 omitempty 忽略
    }
    emptyZooJson, err := json.MarshalIndent(emptyZoo, "", "    ")
    if err != nil {
        fmt.Println("Error marshaling empty zoo:", err)
        return
    }
    fmt.Println("\n使用 omitempty 后的 JSON 字符串 (空 Animals 字段被省略):\n", string(emptyZooJson))
}

登录后复制

输出：

使用 JSON Tag 后的 JSON 字符串:
 {
    "zoo_name": "Magical Mystery Zoo",
    "animal_list": [
        {
            "species_type": "Cow",
            "sound": "Moo"
        },
        {
            "species_type": "Cat",
            "sound": "Meow"
        },
        {
            "species_type": "Fox",
            "sound": "???"
        }
    ]
}

使用 omitempty 后的 JSON 字符串 (空 Animals 字段被省略):
 {
    "zoo_name": "Empty Zoo"
}

登录后复制

通过 json:"key" 标签，我们可以自定义 JSON 中的字段名。omitempty 选项则可以在字段值为 Go 语言的“零值”（例如，字符串为空，整型为 0，切片或映射为 nil）时，将其从 JSON 输出中省略。

5. 注意事项与最佳实践

字段可导出性是关键：始终记住，只有首字母大写的字段才能被 json.Marshal 序列化。这是 Go 语言中处理 JSON 的基本规则。
错误处理：json.Marshal 返回一个 error 类型的值。在实际应用中，务必检查这个错误，以便在序列化失败时能够及时发现并处理问题。
美化输出：使用 json.MarshalIndent(v interface{}, prefix, indent string) 函数可以生成带有缩进的 JSON 字符串，这对于调试和提高可读性非常有帮助。
JSON Tag 的灵活性：善用 JSON Tag 可以让你更好地控制 JSON 的输出格式，使其符合外部 API 或数据存储的需求，同时保持 Go 结构体命名习惯的简洁性。
处理 []byte 结果：json.Marshal 返回的是 []byte 类型。如果需要将其作为字符串打印或传输，记得使用 string() 转换。

总结

Go 语言的 encoding/json 包在处理 JSON 序列化时，其行为严格遵循 Go 语言的字段可导出性规则。理解并正确应用“首字母大写导出，首字母小写不导出”的原则，是避免 json.Marshal 返回空对象或意外结果的关键。通过导出结构体字段并合理利用 JSON Tag，开发者可以灵活高效地将 Go 结构体数据转换为符合预期的 JSON 格式，从而在构建 Go 应用程序时，实现数据的高效交换与持久化。

以上就是Go 语言 JSON 序列化指南：解决 Marshal 返回空对象的问题的详细内容，更多请关注php中文网其它相关文章！