在Golang的Web开发、数据交互场景中，经常需要将结构体、map等数据类型转换为JSON格式的字符串，这个过程就是JSON序列化，最常用的实现方式是调用标准库encoding/json中的json.Marshal函数。但实际开发中，这个函数调用并不总是能成功返回结果，可能会返回对应的错误，我们需要正确捕获这些错误才能保障程序的正常运行。
json.Marshal的常见错误场景
json.Marshal在序列化过程中遇到不支持的类型或者特殊结构时就会返回错误，常见的错误场景有以下几种：
- 待序列化的数据包含json包不支持的类型，比如函数、通道、复数类型等
- 结构体或map中存在循环引用，导致序列化过程进入无限递归
- 自定义的MarshalJSON方法实现存在逻辑错误，返回了异常结果
基础的错误捕获方式
json.Marshal的函数签名是func Marshal(v any) ([]byte, error)，它会返回两个值，第一个是序列化后的字节数组，第二个是错误对象。我们只需要判断第二个返回值是否为nil，就可以知道序列化是否成功，这是最基础的捕获方式。
下面是一个简单的示例，演示如何捕获序列化不支持的类型的错误：
package main
import (
"encoding/json"
"fmt"
)
func main() {
// 定义一个包含函数的变量，函数类型不支持JSON序列化
data := map[string]any{
"name": "test",
"handler": func() {
fmt.Println("hello")
},
}
// 调用json.Marshal进行序列化
result, err := json.Marshal(data)
// 判断错误是否为空
if err != nil {
fmt.Printf("JSON序列化失败，错误信息：%vn", err)
return
}
fmt.Printf("序列化结果：%sn", result)
}
运行上面的代码，会输出错误信息，提示函数类型不支持序列化，这样我们就成功捕获到了错误。
处理循环引用导致的序列化错误
如果待序列化的数据存在循环引用，json.Marshal也会返回错误，这种情况在复杂的数据结构中比较容易出现。下面的示例演示了循环引用的场景以及错误捕获：
package main
import (
"encoding/json"
"fmt"
)
type Node struct {
Value int
Next *Node
}
func main() {
// 构造循环引用的结构
node1 := &Node{Value: 1}
node2 := &Node{Value: 2}
node1.Next = node2
node2.Next = node1
// 尝试序列化循环引用的结构
result, err := json.Marshal(node1)
if err != nil {
fmt.Printf("捕获到序列化错误：%vn", err)
return
}
fmt.Printf("序列化结果：%sn", result)
}
运行代码后会捕获到循环引用导致的错误，错误信息会提示检测到循环引用，开发者可以根据这个错误提示调整数据结构，避免循环引用的问题。
自定义MarshalJSON的错误捕获
如果结构体实现了MarshalJSON方法，json.Marshal会优先调用这个自定义方法，如果自定义方法返回错误，也需要我们捕获处理。示例如下：
package main
import (
"encoding/json"
"fmt"
)
type User struct {
Name string
Age int
}
// 自定义MarshalJSON方法，这里故意返回错误
func (u User) MarshalJSON() ([]byte, error) {
return nil, fmt.Errorf("自定义序列化逻辑错误")
}
func main() {
user := User{Name: "张三", Age: 20}
result, err := json.Marshal(user)
if err != nil {
fmt.Printf("自定义序列化方法返回错误：%vn", err)
return
}
fmt.Printf("序列化结果：%sn", result)
}
这个示例中自定义了User结构体的MarshalJSON方法，并且返回了错误，调用json.Marshal时就能捕获到这个自定义的错误，方便我们排查自定义序列化逻辑的问题。
错误处理的优化建议
在实际项目中，捕获到JSON序列化错误后，不应该只是打印错误信息，建议根据错误类型做更细致的处理：
- 如果是数据类型不支持的错误，可以在序列化前先校验数据类型，避免传入不支持的类型
- 如果是循环引用错误，可以调整数据结构，或者自定义序列化逻辑打破循环引用
- 可以将序列化错误封装成项目统一的错误类型，方便上层调用方统一处理
通过合理的错误捕获和处理，可以有效减少JSON序列化带来的程序异常，提升代码的健壮性。
Golangjson.MarshalJSON序列化错误处理修改时间：2026-07-13 20:03:22