在go语言中，`json.marshal`函数在将结构体编码为json时，只会处理其导出（大写开头）的字段。如果结构体字段以小写字母开头，则会被视为私有字段，`json.marshal`将无法访问并编码它们，导致json输出中这些字段的值为空对象。本文将详细解释这一go语言的可见性规则，并提供正确的结构体定义方式，以确保`json.marshal`能够成功编码所有期望的字段。
引言：理解Go语言JSON编码的常见陷阱
Go语言标准库中的encoding/json包提供了强大而灵活的JSON序列化和反序列化能力。然而，初学者在使用json.Marshal将Go结构体转换为JSON字符串时，常常会遇到一个令人困惑的问题：为什么输出的JSON对象中，结构体字段的值总是空的，或者只出现了键名而没有对应的值？这通常不是json.Marshal的bug，而是对Go语言中一个核心概念——标识符可见性规则——理解不足所致。
问题重现：json.Marshal为何输出空对象？
考虑以下Go程序，它尝试将一个包含自定义结构体的map编码为JSON：
package main
import (
"encoding/json"
"fmt"
)
// 定义一个名为node的结构体
type node struct {
value string
expiry float64
settime float64
}
func main() {
var x = make(map[string]node)
// 初始化map并填充数据
x["hello"] = node{value: "world", expiry: 1, settime: 2}
x["foo"] = node{value: "bar", expiry: 1, settime: 2}
// 尝试将map编码为JSON
a, err := json.Marshal(x)
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println(string(a))
}运行上述代码，我们得到的输出是：
{"foo":{},"hello":{}}可以看到，"foo"和"hello"这两个键对应的结构体值都是空的JSON对象{}，而不是我们期望的{"value":"world", "expiry":1, "settime":2}等详细信息。这正是Go语言可见性规则在作祟。
立即学习“go语言免费学习笔记（深入）”；
Go语言的可见性规则：导出与非导出标识符
在Go语言中，标识符（包括变量、函数、类型、结构体字段等）的可见性是由其首字母的大小写决定的：
- 导出标识符 (Exported Identifiers)：如果标识符的首字母是大写，那么它就是导出的。这意味着该标识符在定义它的包之外也是可见和可访问的。对于结构体字段而言，导出的字段可以被encoding/json等反射机制访问并进行序列化。
- 非导出标识符 (Unexported Identifiers)：如果标识符的首字母是小写，那么它就是非导出的（或称为私有的）。这意味着该标识符只能在定义它的包内部访问。对于结构体字段，非导出字段对包外部是隐藏的，encoding/json包的Marshal方法无法通过反射机制访问这些字段，因此它们不会被编码到JSON输出中。
在上述示例代码中，node结构体的字段value、expiry和settime都是以小写字母开头的，因此它们是非导出的。当json.Marshal尝试访问这些字段进行编码时，由于它们是私有的，Marshal方法无法获取其值，最终导致JSON输出中这些字段对应的对象为空。
解决方案：正确定义可导出的结构体字段
要解决这个问题，只需遵循Go语言的可见性规则，将结构体中需要被JSON编码的字段的首字母改为大写，使其成为导出字段。
修改后的node结构体定义如下：
package main
import (
"encoding/json"
"fmt"
)
// 定义一个名为Node的结构体，字段首字母大写
type Node struct {
Value string
Expiry float64
Settime float64
}
func main() {
var x = make(map[string]Node) // 注意这里map的值类型也需要修改为Node
// 初始化map并填充数据
x["hello"] = Node{Value: "world", Expiry: 1, Settime: 2}
x["foo"] = Node{Value: "bar", Expiry: 1, Settime: 2}
// 尝试将map编码为JSON
a, err := json.Marshal(x)
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println(string(a))
}现在，运行修改后的程序，我们将得到正确的JSON输出：
{"foo":{"Value":"bar","Expiry":1,"Settime":2},"hello":{"Value":"world","Expiry":1,"Settime":2}}通过将字段名改为Value、Expiry和Settime，这些字段成为了导出字段，json.Marshal现在可以成功访问并将其值编码到JSON中。
进阶应用与注意事项
-
JSON Tag (json:"...")： 虽然将字段首字母大写使其可导出是基本要求，但有时我们希望JSON输出中的字段名与Go结构体中的字段名不同，或者需要控制字段的编码行为。这时可以使用结构体字段的json标签：
type Node struct { Value string `json:"data_value"` // JSON输出中显示为 "data_value" Expiry float64 `json:"expiration_time"` Settime float64 `json:"-"` // JSON编码时忽略此字段 HiddenField string // 未指定tag，且首字母小写，仍不会被编码 }通过json:"-"可以明确指示json.Marshal忽略某个导出字段。
json.Unmarshal 的对称性： json.Unmarshal（将JSON字符串解码为Go结构体）同样依赖于导出字段。只有导出的字段才能被Unmarshal填充数据。如果JSON字符串中包含一个与Go结构体中非导出字段同名的键，该键的值将被忽略。
命名约定： 在Go语言中，为了保持代码风格的一致性，通常建议结构体类型名也使用大驼峰命名法（如Node），而结构体实例变量则使用小驼峰命名法（如myNode）。
总结
Go语言的可见性规则是其设计哲学的重要组成部分，它通过首字母大小写来控制标识符的导出与非导出状态。在使用encoding/json包进行JSON序列化时，理解并遵循这一规则至关重要。只有将结构体中需要编码的字段定义为导出字段（即首字母大写），json.Marshal才能正确地访问并将其值包含在生成的JSON输出中。通过合理利用JSON tag，我们还能进一步精细控制JSON字段的命名和编码行为，从而构建出更加健壮和灵活的Go应用程序。
