JSON 是 “JavaScript Object Notation” 的缩写,它是目前前后端接口通信与程序配置文件中最常用的数据交换格式。
在 Go 语言中,我们使用标准库 encoding/json 包就能完成 Go 数据结构与 JSON 文本之间的双向转换,主要包含以下 2 个方向的操作:
- JSON 序列化(Marshal):把 Go 语言中的结构体、切片或 Map 转换成 JSON 格式的数据,其中 marshal 表示 “编组打包”。
- JSON 反序列化(Unmarshal):也常称为 “JSON 解析”,也就是把 JSON 格式的数据拆包还原成 Go 语言中的结构体、切片或 Map,其中 unmarshal 表示 “解组还原”。
你可以把序列化看作把组装好的书架拆平装进标准纸箱,方便在网络上传输或存进文件。反序列化则是收到纸箱后,重新把它组装还原成书架,两者的转换关系如下图所示。

JSON 序列化:json.Marshal()
在 Go 语言中,将数据结构转换为 JSON 主要使用 json.Marshal() 函数。如果需要生成带缩进排版的 JSON 文本,我们还可以使用 json.MarshalIndent() 函数,其中 indent 是 “缩进” 的意思。
语法:
data, err := json.Marshal(v)
data, err := json.MarshalIndent(v, prefix, indent)说明:
这两个函数都接收结构体、切片或 Map 等类型的变量 v 作为第 1 个参数,并返回转换后的 JSON 字节切片 data(类型为 []byte)和错误值 err。它们之间的区别如下:
- json.Marshal(v):生成紧凑的单行 JSON 数据,不包含多余的空格和换行,体积最小,常用于网络接口传输。
- json.MarshalIndent(v, prefix, indent):生成带缩进和换行的多行美化 JSON 数据,常用于打印调试或保存配置文件。其中
prefix是每行开头的前缀(通常传""),indent是每一层的缩进字符(通常传 4 个空格" ")。
定义结构体时,我们可以借助结构体标签控制生成的 JSON 键名,注意标签外侧使用的是反引号(`)而不是单引号。
比如标上 json:"name" 可以指定键名为小写,加上 omitempty(如 json:"email,omitempty")可以在字段为零值时省略该字段,而标为 json:"-" 则可以直接忽略密码等敏感字段。
示例 1:结构体序列化为 JSON
package main
import (
"encoding/json"
"fmt"
)
type User struct {
Name string `json:"name"`
Age int `json:"age"`
Email string `json:"email,omitempty"`
Password string `json:"-"`
Hobbies []string `json:"hobbies"`
}
func main() {
u := User{
Name: "Jack",
Age: 20,
Password: "secret",
Hobbies: []string{"编程", "阅读"},
}
// 生成紧凑的单行 JSON
b1, err := json.Marshal(u)
if err != nil {
fmt.Println("序列化失败:", err)
return
}
fmt.Println(string(b1))
// 生成带 4 空格缩进的美化 JSON
b2, err := json.MarshalIndent(u, "", " ")
if err != nil {
fmt.Println("序列化失败:", err)
return
}
fmt.Println(string(b2))
}运行结果如下。
{"name":"Jack","age":20,"hobbies":["编程","阅读"]}
{
"name": "Jack",
"age": 20,
"hobbies": [
"编程",
"阅读"
]
}分析:
在这个例子中,b1 和 b2 都是字节切片 []byte,我们在外层套上 string() 就能转换成可读的字符串打印出来。除了结构体之外,直接把切片或 Map 传给 json.Marshal(),也会自动转换成对应的 JSON 数组或 JSON 对象。
从输出结果可以看到标签的作用:Name 字段变成了小写的 "name",未赋值的 Email 字段因为带有 omitempty 被自动省略,而标了 json:"-" 的 Password 字段则被直接忽略。
使用 omitempty 时要注意,它省略的是 Go 语言的 “零值”(如空字符串 ""、数字 0、布尔值 false)。如果某个整数字段的值刚好是有效的 0(例如考试得 0 分),加上 omitempty 后也会被一并忽略,因此这类字段不要随意添加 omitempty。
此外,编写 JSON 结构体时有两个初学的小伙伴最容易踩的隐形坑:① 参与转换的结构体字段首字母必须大写;② 标签中 json: 冒号后面绝对不能多打空格。下面把正确写法和错误写法放在一起对比一下。
// 正确方式
type User struct {
Name string `json:"name"`
}
// 错误方式
type User struct {
name string `json:"name"`
Age int `json: "age"`
}为什么这两种错误这么隐蔽呢?因为它们在编译和运行时都不会报错。首字母小写的 name 属于包内私有字段,encoding/json 包没有权限读取它,序列化时会直接跳过。而 json: "age" 冒号后面多敲了一个空格,标签就会静默失效,导出的键名还是大写的 "Age"。平时写标签时一定要格外细心。
JSON 反序列化:json.Unmarshal()
当我们从网络接口或配置文件中拿到一段 JSON 数据后,可以使用 json.Unmarshal() 函数将它解析还原到对应的 Go 结构体或切片变量中。
语法:
err := json.Unmarshal(data, &v)说明:
json.Unmarshal() 接收以下 2 个参数,并返回一个 error 错误值:
- data(必选):要解析的 JSON 字节切片
[]byte。如果手头拿到的是字符串jsonStr,我们可以先通过[]byte(jsonStr)将其转为字节切片。 - &v(必选):用于接收解析结果的变量指针(如
&u)。这里必须加上取地址符(&)传入指针,否则函数无法把解析出的数据写入变量中。
示例 2:解析 JSON 到结构体
package main
import (
"encoding/json"
"fmt"
)
type User struct {
Name string `json:"name"`
Age int `json:"age"`
Hobbies []string `json:"hobbies"`
}
func main() {
// 使用反引号定义原始 JSON 字符串
jsonStr := `{"name":"Lucy","age":18,"hobbies":["音乐","旅行"]}`
// 声明用于接收数据的结构体变量
var u User
// 将 JSON 字节切片解析到指针 &u 中
err := json.Unmarshal([]byte(jsonStr), &u)
if err != nil {
fmt.Println("解析失败:", err)
return
}
fmt.Printf("姓名:%s\n", u.Name)
fmt.Printf("年龄:%d\n", u.Age)
fmt.Printf("爱好:%v\n", u.Hobbies)
}运行结果如下。
姓名:Lucy
年龄:18
爱好:[音乐 旅行]分析:
在这个例子中,json.Unmarshal() 会根据结构体标签中的键名,把 JSON 里的字段值一一填入变量 u 中。如果要解析包含多个对象的 JSON 数组 [{...}, {...}],我们只需要声明结构体切片 var users []User 并传入 &users 就可以了。
如果遇到真实接口里多层嵌套的 JSON 对象,比如用户信息里再套一个地址对象 {"city":"上海","zip":"200000"},我们只需要在 User 结构体里再嵌套一个 Address 字段即可,如下所示:
type Address struct {
City string `json:"city"`
Zip string `json:"zip"`
}
type User struct {
Name string `json:"name"`
Addr Address `json:"addr"`
}小伙伴们在调用 json.Unmarshal() 时,一定要记得给第 2 个参数加上取地址符(&)。下面这种直接传入普通变量的写法就是错误的。
// 错误方式
err := json.Unmarshal([]byte(jsonStr), u)如果直接传入普通变量 u 而不是指针 &u,运行时 json.Unmarshal() 会返回 json: Unmarshal(non-pointer main.User) 错误,提示目标不是指针,同时变量 u 里面依然全是默认的零值。
解析动态 JSON:map[string]any
有时我们事先并不知道一段 JSON 里面具体有哪些字段,或者不同记录的字段结构不固定,没法提前定义好结构体。这时我们可以声明一个类型为 map[string]any 的 Map 来接收数据。其中 any 是空接口 interface{} 的别名,可以用来保存任意类型的值。
示例 3:解析 JSON 到 Map
package main
import (
"encoding/json"
"fmt"
)
func main() {
jsonStr := `{"title":"Go 教程","chapters":20}`
// 声明键为 string、值为 any 的 Map
var m map[string]any
err := json.Unmarshal([]byte(jsonStr), &m)
if err != nil {
fmt.Println("解析失败:", err)
return
}
if title, ok := m["title"].(string); ok {
fmt.Printf("课程名称:%s\n", title)
}
if chapters, ok := m["chapters"].(float64); ok {
fmt.Printf("章节数量:%.0f\n", chapters)
}
}运行结果如下。
课程名称:Go 教程
章节数量:20分析:
声明 var m map[string]any 时虽然没有调用 make() 初始化,但因为我们传入了指针 &m,json.Unmarshal() 内部会自动分配好 Map 内存,并将键值对存入 m 中。
由于 m 的值类型是 any,只是打印查看时直接写 fmt.Println(m["title"]) 即可。如果要把取出来的值当成具体类型参与运算,我们就需要通过类型断言(如 title, ok := m["title"].(string))还原类型,带上 ok 判断还能防止字段缺失时引发程序崩溃。
提示: 由于 JSON 标准本身不区分整数和浮点数,解析到 map[string]any 时,所有数字(如上面的 20)默认都会变成 float64 类型,因此断言必须写 .(float64) 而不能写 .(int)。只要 JSON 结构固定,实际开发中我们优先推荐定义结构体来解析。
读写本地 JSON 文件
除了单个 JSON 对象 {...} 之外,日常开发中还经常需要把一组配置或记录保存成 .json 文件,也就是 JSON 数组 [{...}, {...}],它在 Go 语言中直接对应结构体切片(如 []User)。
下面我们结合 os.WriteFile() 和 os.ReadFile(),看看如何在本地将结构体切片保存为 users.json 文件,再从文件中读取并解析还原。
示例 4:读写本地 JSON 文件
package main
import (
"encoding/json"
"fmt"
"os"
)
type User struct {
Name string `json:"name"`
Age int `json:"age"`
}
func main() {
users := []User{
{Name: "Jack", Age: 20},
{Name: "Lucy", Age: 18},
}
// 1. 序列化为美化 JSON 并写入本地文件
data, err := json.MarshalIndent(users, "", " ")
if err != nil {
fmt.Println("序列化失败:", err)
return
}
if err := os.WriteFile("users.json", data, 0644); err != nil {
fmt.Println("写入文件失败:", err)
return
}
// 2. 从本地文件读取并反序列化还原
fileBytes, err := os.ReadFile("users.json")
if err != nil {
fmt.Println("读取文件失败:", err)
return
}
var loaded []User
if err := json.Unmarshal(fileBytes, &loaded); err != nil {
fmt.Println("解析失败:", err)
return
}
for _, u := range loaded {
fmt.Printf("姓名:%s, 年龄:%d\n", u.Name, u.Age)
}
}运行结果如下。
姓名:Jack, 年龄:20
姓名:Lucy, 年龄:18分析:
在这个例子中,写入时我们先调用 json.MarshalIndent() 把结构体切片 users 转成带缩进的字节切片 data,再传给 os.WriteFile("users.json", data, 0644) 存入磁盘。
读取时则先通过 os.ReadFile("users.json") 拿到字节切片 fileBytes,再传给 json.Unmarshal(fileBytes, &loaded) 还原出结构体切片。
在本地运行完这段代码后,当前工作目录下就会生成一个排版工整的 users.json 文件。
如果遇到体积特别大的 JSON 文件或网络数据流,标准库还提供了流式读写器 json.NewEncoder(file) 和 json.NewDecoder(file)。它们可以直接对着文件对象边读边解析,小伙伴们在后面学习 HTTP 开发时还会用到。
常见问题
1. 为什么 json.Marshal(u) 传普通变量就行,而 json.Unmarshal(data, &u) 必须传指针 &u 呢?
这和值传递与指针传递的规则直接相关:
- 序列化只读不改:
json.Marshal(u)只需要读取变量u里面的数据,再把生成的 JSON 字节切片通过返回值交给我们,不需要修改原变量,因此直接传值即可。 - 反序列化需要修改外部变量:
json.Unmarshal()的返回值位置已经被error占用了,必须把解析出的数据直接填进外部变量u里。Go 语言函数传参默认是值传递(复制副本),只有传入指针&u,函数内部才能真正修改外部变量u的内容。
2. 如果 JSON 文本里多了一些结构体中没定义的字段,解析时会报错吗?
不会报错。json.Unmarshal() 会按名称自动匹配已定义的字段,JSON 中多余的字段会被直接忽略,而 JSON 中缺失的字段则会保留该类型的默认零值。因此当我们只需要提取接口返回的部分数据时,在结构体里只定义自己关心的那几个字段就可以了。
