深入理解 Go 语言 json.Marshal：导出字段与字节切片解析

新闻中心 NEWS CENTER

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

深入理解 Go 语言 json.Marshal：导出字段与字节切片解析

2025-11-20

浏览次数：次

返回列表

深入理解 Go 语言 json.Marshal：导出字段与字节切片解析

本文将深入探讨 go 语言中 `encoding/json` 包的 `marshal` 函数在使用时常见的两个陷阱：结构体字段必须导出才能被序列化，以及 `marshal` 函数返回的是字节切片（`[]byte`）而非直接可读的字符串。通过实例代码，我们将演示如何正确地定义结构体并处理 `marshal` 的输出，从而生成预期的 json 格式数据。

Go 语言的 encoding/json 包提供了一套强大且易用的工具，用于在 Go 结构体和 JSON 数据之间进行转换。然而，初学者在使用 json.Marshal 函数时，可能会遇到一些不符合预期的行为，例如输出 [123 125] 而非完整的 JSON 字符串。这通常是由两个核心原因造成的：结构体字段的可见性规则和 Marshal 函数的返回值类型。

1. 结构体字段的导出规则

在 Go 语言中，结构体字段的可见性由其名称的首字母决定。如果字段名的首字母是大写，则该字段是“导出”的（Exported），可以在包外部访问；如果首字母是小写，则该字段是“未导出”的（Unexported），只能在当前包内部访问。

encoding/json 包在执行 Marshal 操作时，只会序列化结构体中已导出的字段。未导出的字段会被忽略，不会出现在生成的 JSON 输出中。

考虑以下示例代码：

package main

import (
    "fmt"
    "encoding/json"
)

type Zoo struct {                                                                       
    name string // 未导出字段
    animals []Animal // 未导出字段
}
type Animal struct {
    species string // 未导出字段
    says string // 未导出字段
}

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

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

    fmt.Println(string(zooJson)) // 转换为字符串打印
}

运行上述代码，你会发现输出是 {}，一个空的 JSON 对象。这是因为 Zoo 和 Animal 结构体中的所有字段（name, animals, species, says）都是以小写字母开头，它们都是未导出的。json.Marshal 无法访问这些字段，因此生成了一个空的 JSON 对象。

解决方法：导出结构体字段

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

package main

import (
    "fmt"
    "encoding/json"
)

type Zoo struct {                                                                       
    Name string // 导出字段
    Animals []Animal // 导出字段
}
type Animal struct {
    Species string // 导出字段
    Says string // 导出字段
}

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

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

    fmt.Println(string(zooJson))
}

现在，运行修改后的代码，你会得到一个包含所有数据的 JSON 字符串。

2. json.Marshal 的返回值类型

json.Marshal 函数的签名是 func Marshal(v interface{}) ([]byte, error)。这意味着它返回一个字节切片（[]byte）和一个错误。

当你直接使用 fmt.Println(zooJson) 打印一个 []byte 类型的变量时，Go 的默认行为是打印其底层字节数组的十进制表示。例如，JSON 对象 {} 的 ASCII 码是 123 和 125。因此，如果 json.Marshal 返回一个空的 JSON 对象，那么直接打印 []byte 会显示 [123 125]。

小云雀

剪映出品的AI视频和图片创作助手

1949 查看详情小云雀

解决方法：将字节切片转换为字符串

要正确地打印 json.Marshal 的结果为可读的 JSON 字符串，你需要将其显式地转换为 string 类型。

// ... (接上文修改后的结构体定义和 Marshal 调用)

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

    // 正确的做法：将 []byte 转换为 string 再打印
    fmt.Println(string(zooJson))

3. 完整示例与最佳实践

结合上述两个修正，以下是正确使用 json.Marshal 的完整代码示例：

package main

import (
    "fmt"
    "encoding/json"
)

// Zoo 结构体，字段首字母大写以确保导出
type Zoo struct {                                                                       
    Name string
    Animals []Animal
}

// Animal 结构体，字段首字母大写以确保导出
type Animal struct {
    Species string
    Says string
}

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

    // 尝试将结构体序列化为 JSON
    zooJson, err := json.Marshal(zoo)
    if err != nil {
        fmt.Printf("JSON 序列化失败: %v\n", err)
        return
    }

    // 将字节切片转换为字符串并打印
    fmt.Println("序列化后的 JSON 字符串:")
    fmt.Println(string(zooJson))

    // 为了美观和可读性，可以使用 json.MarshalIndent 进行格式化输出
    prettyJson, err := json.MarshalIndent(zoo, "", "    ")
    if err != nil {
        fmt.Printf("JSON 格式化失败: %v\n", err)
        return
    }
    fmt.Println("\n格式化后的 JSON 字符串:")
    fmt.Println(string(prettyJson))
}

输出示例：

序列化后的 JSON 字符串:
{"Name":"Magical Mystery Zoo","Animals":[{"Species":"Cow","Says":"Moo"},{"Species":"Cat","Says":"Meow"},{"Species":"Fox","Says":"???"}]}

格式化后的 JSON 字符串:
{
    "Name": "Magical Mystery Zoo",
    "Animals": [
        {
            "Species": "Cow",
            "Says": "Moo"
        },
        {
            "Species": "Cat",
            "Says": "Meow"
        },
        {
            "Species": "Fox",
            "Says": "???"
        }
    ]
}

JSON 标签（json tag）

在实际开发中，你可能希望 JSON 字段名与 Go 结构体字段名不同，或者希望某些字段在序列化时被忽略。这时可以使用结构体字段标签（json tag）。

type Animal struct {
    Species string `json:"animal_species"` // JSON 字段名为 "animal_species"
    Says string `json:"sound,omitempty"`   // JSON 字段名为 "sound"，如果为空则忽略
    InternalID string `json:"-"`           // 忽略此字段
}

通过使用 json tag，你可以更灵活地控制 JSON 序列化的行为。