Golang自定义JSON序列化技巧

本文深入剖析了Go语言中自定义JSON序列化的关键陷阱与最佳实践，重点揭示了MarshalJSON方法“失效”的根本原因——接收者类型不匹配（必须用指针接收者且调用值类型需严格一致），并系统讲解了如何安全、高效地实现条件字段输出、避免非法JSON格式panic、正确处理嵌套与接口类型、兼顾字段顺序要求，同时强调在性能敏感场景下应优先使用结构体投影和标准tag而非重写MarshalJSON，并给出复用buffer、规避反射开销等实用优化策略，帮助开发者避开常见坑点，写出健壮、可维护且高性能的JSON序列化逻辑。

为什么 MarshalJSON 方法没生效？

最常见的情况是：你给结构体实现了 MarshalJSON，但序列化时字段还是原样输出，甚至 panic：json: error calling MarshalJSON for type …: …。根本原因往往是方法接收者类型不匹配——必须是指针接收者，且类型要和实际被序列化的值一致。

• 如果用 json.Marshal(myStruct)（传值），而你只实现了 (*MyStruct).MarshalJSON，Go 不会自动取地址调用，方法直接被忽略
• 如果结构体嵌套了该类型，或存在接口字段（如 interface{} 存了该结构体值），也容易触发“找不到实现”的静默失效
• 返回的 JSON 字节切片必须是合法格式，比如漏掉外层 {}、字段名没加双引号、用了单引号，都会导致 panic

怎么让某个字段有条件地输出？

标准 JSON tag（如 json:"name,omitempty"）只能做空值过滤，没法按业务逻辑决定是否出现。这时候得进 MarshalJSON 手动拼接。

• 别用 fmt.Sprintf 拼 JSON 字符串——易出错、不安全、不处理转义
• 推荐用 json.Encoder 写入 bytes.Buffer，或用 map[string]interface{} 构建中间数据再序列化
• 注意字段顺序：map 无序，若需固定顺序（如 API 规范要求），必须手动控制键的写入次序

示例：只在 IsPublic 为 true 时输出 email 字段：

func (u User) MarshalJSON() ([]byte, error) {
	buf := &bytes.Buffer{}
	enc := json.NewEncoder(buf)
	enc.SetEscapeHTML(false)

	if err := enc.Encode(map[string]interface{}{
		"id":   u.ID,
		"name": u.Name,
		"email": func() interface{} {
			if u.IsPublic {
				return u.Email
			}
			return nil // 或直接 omit，见下一条
		}(),
	}); err != nil {
		return nil, err
	}
	// 去掉换行和首尾空白（Encode 加了换行）
	b := bytes.TrimSpace(buf.Bytes())
	return b, nil
}

omitempty 和 MarshalJSON 能一起用吗？

不能。一旦结构体实现了 MarshalJSON，整个序列化流程就完全交给你，标准 tag 全部失效。想保留 omitempty 的语义，得自己实现。

• 对字段做“零值判断”要小心：指针、slice、map 的零值是 nil，但自定义类型（如 type ID string）的零值是 ""，不是 nil
• 嵌套结构体字段如果也实现了 MarshalJSON，你不能直接 json.Marshal(sub) 后拼字符串——可能含非法字符；应统一用 json.Encoder 或递归调用其 MarshalJSON
• 如果只是为了隐藏某些字段，比完整重写 MarshalJSON 更轻量的做法是：用匿名结构体 + 字段投影，例如 json.Marshal(struct{ ID int }{u.ID})

性能敏感场景下要注意什么？

每次调用 MarshalJSON 都涉及内存分配和反射（哪怕只是 map 构造），高频 API 中容易成为瓶颈。

• 避免在 MarshalJSON 里做 IO、锁、或调用其他可能阻塞的方法
• 不要反复创建 bytes.Buffer 或 json.Encoder——可复用带 sync.Pool 的 buffer
• 如果只是改字段名或忽略几个字段，优先考虑组合 tag：json:"-" 、json:"name,omitempty"，而不是上 MarshalJSON
• 注意 GC 压力：返回的 []byte 是新分配的，无法复用底层 slice，大量短生命周期 JSON 会抬高 GC 频率

真正需要动态控制输出时，逻辑越简单越好——能用条件字段赋值就别用 map 嵌套，能用 struct 投影就别碰反射。

以上就是《Golang自定义JSON序列化技巧》的详细内容，更多关于的资料请关注golang学习网公众号！