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中的结构体字段名称改为以大写字母开头，使其成为导出字段。
以下是修改后的结构体定义和工作示例：
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格式。
