本文将深入探讨 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]。
解决方法：将字节切片转换为字符串
要正确地打印 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 序列化的行为。
总结
在使用 Go 语言的 encoding/json 包进行结构体到 JSON 的序列化时，请牢记以下两点：
- 字段导出性： 只有结构体中首字母大写的导出字段才会被 json.Marshal 序列化。
- 返回值类型： json.Marshal 返回的是 []byte 类型，需要通过 string() 转换才能得到可读的 JSON 字符串。
理解并遵循这些规则，将帮助你避免常见的序列化陷阱，并有效地在 Go 应用程序中处理 JSON 数据。
