如何在Golang中处理JSON编码错误_Golang json.Marshal错误处理技巧_技术教程

json.Marshal 返回 error 通常意味着值包含无法序列化的类型，如函数、channel、map 键非基本类型或 MarshalJSON 方法 panic。

json.Marshal 返回 error 时通常意味着什么

Go 的 json.Marshal 失败，基本只有一类原因：**值包含无法序列化的类型**。它不会因为字段名大小写、空结构体或 nil 指针本身报错（nil 指针会被编码为 null），但一旦遇到不支持的类型（比如函数、channel、map 键不是基本类型、未导出字段被强制访问等），就会返回非 nil 的 error。

常见错误现象包括：

json: unsupported type: func()
json: unsupported type: map[interface {}]string
json: error calling MarshalJSON for type xxx: ...（自定义类型的 MarshalJSON 方法 panic 或返回 error）

如何安全调用 json.Marshal 并定位问题源头

不要忽略 err，也不要只打印 err.Error() 就完事。关键是要知道「哪个字段」导致失败。推荐做法是分层检

查：

对结构体字段逐个 json.Marshal 测试（尤其关注 map、interface{}、嵌套结构体）
确认所有 map 的键类型是可比较的 Go 基本类型（string、int、bool 等），map[any]string 或 map[struct{}]int 都会失败
若用了自定义类型，检查其是否实现了 MarshalJSON() ([]byte, error)，且该方法内部不 panic、不返回无效 JSON
避免在结构体中直接嵌入不可序列化字段（如 http.ResponseWriter、*sql.DB），应使用 - tag 或重命名字段

常见易踩坑场景与修复示例

下面这段代码看似正常，实则会在运行时报错：

type User struct {
	Name string
	Data map[interface{}]string // ❌ 键是 interface{}，不支持
}
u := User{Name: "Alice", Data: map[interface{}]string{"age": "30"}}
b, err := json.Marshal(u) // err != nil

修复方式很简单，统一键类型：

type User struct {
	Name string
	Data map[string]string // ✅ 改成 string 键
}

另一个典型陷阱是嵌套了未导出字段的结构体：

type Inner struct {
	id int // 小写，未导出 → json.Marshal 会跳过，但如果用 json.RawMessage 或反射强读，可能出错
}
type Outer struct {
	Inner
}

这种组合本身不会让 json.Marshal 报错，但若你手动调用 json.Marshal(Outer.Inner)，就会因 id 不可访问而触发反射异常 —— 实际上这时 panic 会先于 error 返回，所以务必用 defer/recover 包裹可疑调用。

生产环境建议的封装模式

别每次手动写 if err != nil { ... }。可以封装一个带上下文的日志化序列化函数：

func MustMarshal(v interface{}, ctx string) []byte {
	b, err := json.Marshal(v)
	if err != nil {
		log.Printf("json.Marshal failed in %s: %v, value: %+v", ctx, err, v)
		panic(err) // 或返回零值、上报 metrics，按团队规范来
	}
	return b
}

注意：ctx 字符串要具体，比如 "api.LoginResponse"，而不是笼统的 "response"。线上排查时，日志里看到失败上下文，能立刻锁定模块和数据形态。

复杂结构体 + 动态字段的场景下，json.Marshal 的错误信息往往不够直观；真正难的不是“怎么捕获 error”，而是“怎么快速反推哪个字段坏了”。多用 fmt.Printf("%#v", v) 看原始值，比猜更可靠。