Go语言json.Marshal结构体为空：深入理解与正确实践-Golang-PHP中文网

Go语言json.Marshal结构体为空：深入理解与正确实践

DDD

发布： 2025-10-03 09:36:22

原创

299人浏览过

Go语言json.Marshal结构体为空：深入理解与正确实践

在Go语言中，使用encoding/json包将结构体序列化为JSON时，开发者常遇到json.Marshal返回空JSON对象{}的问题，即使结构体已填充数据且未报告错误。这主要源于结构体字段的可见性规则。本教程将详细解析Go语言结构体字段导出规则对JSON序列化的影响，提供具体的代码示例，并指导如何正确地将结构体数据转换为JSON格式。

1. json.Marshal的常见困惑

go语言的encoding/json包提供了一套强大的工具，用于在go值和json表示之间进行转换。json.marshal函数负责将go数据结构编码为json格式的字节切片。然而，一个常见的问题是，当尝试序列化一个看似完整的结构体时，json.marshal却返回一个空的json对象{}，同时err返回值却是nil，这让许多初学者感到困惑。

考虑以下代码示例，它展示了这种典型的问题：

package main

import (
    "encoding/json"
    "fmt"
)

type Address struct {
    street   string
    extended string
    city     string
    state    string
    zip      string
}

type Name struct {
    first  string
    middle string
    last   string
}

type Person struct {
    name    Name
    age     int
    address Address
    phone   string
}

func main() {
    myname := Name{"Alfred", "H", "Eigenface"}
    myaddr := Address{"42 Place Rd", "Unit 2i", "Placeton", "ST", "00921"}
    me := Person{myname, 24, myaddr, "000 555-0001"}

    b, err := json.Marshal(me)

    if err != nil {
        fmt.Println("序列化错误:", err)
        return
    }

    fmt.Println("序列化结果:", string(b)) // 输出: 序列化结果: {}
    fmt.Println("原始结构体:", me)       // 输出: 原始结构体: { {Alfred H Eigenface} 24 {42 Place Rd Unit 2i Placeton ST 00921} 000 555-0001}
}

登录后复制

从输出可以看出，me结构体本身包含了所有预期的数据，但json.Marshal的结果却是一个空对象{}。

2. 根本原因：结构体字段的导出规则

导致json.Marshal返回空对象的核心原因是Go语言的可见性规则，特别是对于结构体字段。在Go语言中：

导出字段 (Exported Fields)：以大写字母开头的字段名是导出的，它们可以在包外部访问。
未导出字段 (Unexported Fields)：以小写字母开头的字段名是未导出的，它们只能在定义它们的包内部访问。

encoding/json包在进行序列化时，只会处理导出的结构体字段。这意味着，如果一个结构体中的所有字段都是未导出的（即以小写字母开头），json.Marshal将无法访问这些字段的数据，因此会生成一个空的JSON对象。由于没有发生运行时错误（它只是没有找到任何可导出的字段来序列化），所以err变量会是nil。

立即学习“go语言免费学习笔记（深入）”；

3. 解决方案：导出需要序列化的字段

要解决这个问题，只需将你希望序列化到JSON中的结构体字段名称改为以大写字母开头，使其成为导出字段。

ViiTor实时翻译

AI实时多语言翻译专家！强大的语音识别、AR翻译功能。

116

查看详情

以下是修改后的结构体定义和工作示例：

package main

import (
    "encoding/json"
    "fmt"
)

// Address 结构体，字段已导出
type Address struct {
    Street   string
    Extended string
    City     string
    State    string
    Zip      string
}

// Name 结构体，字段已导出
type Name struct {
    First  string
    Middle string
    Last   string
}

// Person 结构体，字段已导出
type Person struct {
    Name    Name
    Age     int
    Address Address
    Phone   string
}

func main() {
    myname := Name{"Alfred", "H", "Eigenface"}
    myaddr := Address{"42 Place Rd", "Unit 2i", "Placeton", "ST", "00921"}
    me := Person{myname, 24, myaddr, "000 555-0001"}

    b, err := json.Marshal(me)

    if err != nil {
        fmt.Println("序列化错误:", err)
        return
    }

    fmt.Println("序列化结果:", string(b))
    // 预期输出:
    // 序列化结果: {"Name":{"First":"Alfred","Middle":"H","Last":"Eigenface"},"Age":24,"Address":{"Street":"42 Place Rd","Extended":"Unit 2i","City":"Placeton","State":"ST","Zip":"00921"},"Phone":"000 555-0001"}
}

登录后复制

通过将street改为Street，first改为First等，这些字段现在成为了导出字段，json.Marshal可以正确地访问并将其编码为JSON。

4. 进一步优化：使用JSON Tag

在实际开发中，我们可能希望JSON字段的名称与Go结构体字段的名称不同，或者希望控制某些字段在特定条件下是否被序列化。encoding/json包提供了结构体标签 (struct tags) 来实现这些高级功能。

自定义JSON字段名：使用json:"fieldName"。
忽略空值字段：使用json:"fieldName,omitempty"。如果字段的值是其类型的零值（例如，字符串为空，整数为0，切片为nil），则该字段在JSON输出中将被忽略。
完全忽略字段：使用json:"-"。

以下是一个使用JSON Tag的示例：

package main

import (
    "encoding/json"
    "fmt"
)

type AddressWithTags struct {
    Street   string `json:"street_address"`       // 自定义JSON字段名为 "street_address"
    Extended string `json:"unit,omitempty"`       // 如果为空，则忽略
    City     string `json:"city_name"`
    State    string `json:"state_code"`
    Zip      string `json:"zip_code"`
    Internal string `json:"-"`                    // 此字段将完全被忽略
}

type PersonWithTags struct {
    FullName string            `json:"full_name"`
    Age      int               `json:"age"`
    Location AddressWithTags `json:"location_info"`
    Phone    string            `json:"contact_phone,omitempty"`
}

func main() {
    myaddr := AddressWithTags{
        Street:   "42 Place Rd",
        Extended: "", // 此字段为空，将被 omitempty 忽略
        City:     "Placeton",
        State:    "ST",
        Zip:      "00921",
        Internal: "secret data", // 此字段将被 - 忽略
    }
    me := PersonWithTags{
        FullName: "Alfred H Eigenface",
        Age:      24,
        Location: myaddr,
        Phone:    "000 555-0001",
    }

    b, err := json.Marshal(me)

    if err != nil {
        fmt.Println("序列化错误:", err)
        return
    }

    fmt.Println("序列化结果 (带Tags):", string(b))
    // 预期输出:
    // 序列化结果 (带Tags): {"full_name":"Alfred H Eigenface","age":24,"location_info":{"street_address":"42 Place Rd","city_name":"Placeton","state_code":"ST","zip_code":"00921"},"contact_phone":"000 555-0001"}
}

登录后复制

5. 注意事项与总结

导出是关键：始终记住，只有以大写字母开头的结构体字段才能被encoding/json包序列化。这是Go语言反射机制的普遍规则，不仅仅适用于JSON。
err为nil不代表成功序列化：当json.Marshal返回空对象时，err为nil表示在尝试序列化所有可访问（即导出）字段的过程中没有发生错误。如果没有任何可访问字段，它就成功地序列化了“没有字段”的状态，因此不会报错。
选择合适的JSON Tag：合理使用json:"fieldName"、json:"fieldName,omitempty"和json:"-"可以极大地提高JSON序列化的灵活性和可读性。
嵌套结构体：嵌套结构体中的字段也需要遵循相同的导出规则。如果一个嵌套结构体中的字段未导出，它同样不会出现在最终的JSON中。

通过理解Go语言的可见性规则和encoding/json包的工作原理，开发者可以避免json.Marshal返回空对象的常见问题，并有效地将Go结构体数据转换为所需的JSON格式。

以上就是Go语言json.Marshal结构体为空：深入理解与正确实践的详细内容，更多请关注php中文网其它相关文章！