引言：Go语言的JSON序列化
在Go语言中，encoding/json包是处理JSON数据与Go结构体之间转换的标准库，广泛应用于Web服务、数据存储和API通信等场景。json.Marshal函数负责将Go值（如结构体、切片、映射等）转换为JSON格式的字节切片。然而，初学者在使用该函数序列化结构体时，常会遇到一个令人困惑的问题：即使结构体中填充了数据，json.Marshal却返回一个空的JSON对象{}，且没有报告任何错误。
常见陷阱：结构体字段未导出导致空JSON
当json.Marshal函数将Go结构体序列化为空JSON对象{}时，最常见且几乎是唯一的原因是结构体中的字段未被“导出”（Exported）。在Go语言中，字段的导出性由其名称的首字母大小写决定：
- 导出字段（Exported Fields）：字段名以大写字母开头。这些字段在包外部是可见的，并且可以被encoding/json包访问和序列化。
- 未导出字段（Unexported Fields）：字段名以小写字母开头。这些字段仅在定义它们的包内部可见，对于包外部的代码（包括encoding/json包）是不可见的，因此无法被序列化到JSON中。
考虑以下示例代码，它展示了导致空JSON输出的典型场景：
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结构体，包含未导出的Name和Address字段，以及其他未导出字段
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("序列化后的JSON:", string(b)) // 输出: 序列化后的JSON: {}
fmt.Println("原始结构体内容:", me) // 输出: 原始结构体内容: {Alfred H Eigenface 24 {42 Place Rd Unit 2i Placeton ST 00921} 000 555-0001}
}在上述代码中，Address、Name和Person结构体中的所有字段（如street、first、age等）都以小写字母开头，这意味着它们是未导出的。当json.Marshal(me)被调用时，json包无法访问这些字段，因此它会创建一个空的JSON对象{}，因为它没有找到任何可序列化的导出字段。
立即学习“go语言免费学习笔记（深入）”；
解决方案：导出结构体字段
解决这个问题的关键在于遵循Go语言的可见性规则，将需要序列化到JSON中的结构体字段名首字母改为大写，使其成为导出字段。
以下是修正后的代码示例：
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结构体，包含已导出的Name和Address字段，以及其他已导出字段
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("序列化后的JSON:", string(b))
// 预期输出:
// 序列化后的JSON: {"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"}
}通过将Address、Name和Person结构体中的所有字段名首字母大写（例如，street改为Street，age改为Age），这些字段现在都已导出。json.Marshal函数能够正确访问并序列化这些字段，生成包含数据的JSON字符串。
理解json.Marshal的行为：为什么err为nil
在原始问题中，json.Marshal函数返回的err值是nil，这让很多开发者感到困惑，因为他们期望在序列化失败时能收到错误。
json.Marshal函数的设计逻辑是：它会尝试序列化所有 可访问（即已导出） 的字段。 如果一个结构体没有任何导出字段，那么json.Marshal会成功地序列化“所有可访问的字段”——由于没有可访问的字段，结果就是一个空的JSON对象{}。 从json.Marshal的角度来看，这个操作是成功的，因为它没有遇到任何阻止它完成序列化过程的语法或数据类型问题。因此，err返回nil是符合其设计预期的。它不会将“没有可序列化的字段”视为一个错误，而是将其视为一种有效的序列化结果。
进阶技巧：JSON标签（json tags）
在实际开发中，我们可能需要更精细地控制JSON序列化的行为，例如：
- 自定义JSON字段名：Go结构体字段通常使用驼峰命名法（CamelCase），但JSON字段名可能更倾向于蛇形命名法（snake_case）或小写字母开头。
- 忽略某些字段：不希望将结构体中的某些字段序列化到JSON中。
- 处理空值：当字段为空值（如nil指针、空字符串、零值）时，在JSON中省略该字段。
这些需求可以通过结构体字段的json标签（tag）来实现。
package main
import (
"encoding/json"
"fmt"
)
type Product struct {
ID string `json:"product_id"` // 自定义JSON字段名为 "product_id"
Name string `json:"productName"` // 自定义JSON字段名为 "productName"
Price float64 `json:"price,omitempty"` // 当Price为零值时，在JSON中省略该字段
Description string `json:"-"` // 完全忽略此字段，不进行序列化
InternalTag string // 未指定tag，默认使用字段名"InternalTag"
}
func main() {
p1 := Product{
ID: "P001",
Name: "Go Book",
Price: 29.99,
Description: "A book about Go programming",
InternalTag: "secret",
}
b1, err := json.Marshal(p1)
if err != nil {
fmt.Println("序列化错误:", err)
return
}
fmt.Println("带有所有字段的JSON:", string(b1))
// 预期输出: {"product_id":"P001","productName":"Go Book","price":29.99,"InternalTag":"secret"}
p2 := Product{
ID: "P002",
Name: "Empty Product",
Description: "Another book",
InternalTag: "public",
}
// Price字段为零值（0.0），因为有omitempty标签，所以不会出现在JSON中
b2, err := json.Marshal(p2)
if err != nil {
fmt.Println("序列化错误:", err)
return
}
fmt.Println("Price为零值时省略的JSON:", string(b2))
// 预期输出: {"product_id":"P002","productName":"Empty Product","InternalTag":"public"}
}在上面的示例中：
- json:"product_id"：将Go字段ID在JSON中命名为product_id。
- json:"price,omitempty"：将Go字段Price在JSON中命名为price，并且当Price为零值（例如，float64的0.0）时，该字段将不会出现在JSON输出中。
- json:"-"：表示完全忽略Go字段Description，无论其值如何，都不会将其序列化到JSON中。
总结
json.Marshal返回空JSON对象{}的根本原因在于Go结构体字段的可见性规则。为了确保结构体字段能够被正确序列化，开发者必须将这些字段的首字母大写，使其成为导出字段。同时，理解json.Marshal在没有可导出字段时返回nil错误的设计意图也至关重要。通过合理利用JSON标签，我们可以进一步精细控制序列化过程，满足更复杂的业务需求，使Go语言在处理JSON数据时更加灵活和强大。
