Go 自定义 MarshalJSON 为什么递归调用自己

给结构体实现 MarshalJSON 后，如果方法内部又直接调用 json.Marshal(u)，程序会不断回到同一个方法，最后以栈溢出结束。原因不是 JSON 字段太多，而是 u 仍然满足 json.Marshaler 接口。

解决办法是定义一个与原结构体拥有相同底层结构、但没有原方法集的新类型，例如 type plain User User。在自定义方法里把当前值转换为 plain 后再编码，标准库就会走普通结构体字段编码路径。

记住一句话：自定义 MarshalJSON 里不能再次编码原类型本身；要先转换成不带 MarshalJSON 方法的新定义类型。

为什么直接 json.Marshal 会递归

encoding/json 在编码值时会识别实现了 json.Marshaler 的类型，并调用它的 MarshalJSON。因此下面的写法看起来像“复用默认编码”，实际上每一轮传进去的仍是 User：

package main

import "encoding/json"

type User struct {
	Name  string `json:"name"`
	Level int    `json:"level"`
}

// MarshalJSON 想追加一个字段，但不能再次编码 User 本身。
func (u User) MarshalJSON() ([]byte, error) {
	type output struct {
		User
		Label string `json:"label"`
	}
	// 这里的 u 仍然是 User，json.Marshal 会再次调用 MarshalJSON。
	return json.Marshal(output{User: u, Label: "member"})
}

临时结构体的匿名字段仍然保存着 User，所以编码器走到这个字段时，依旧会发现 User.MarshalJSON。递归链可以概括为：User.MarshalJSON → json.Marshal(User) → User.MarshalJSON。临时外壳并没有改变被编码字段的动态类型。

别名类型为什么能切断方法调用

这里要区分两个容易混淆的写法。type plain User 创建的是新定义类型，它和 User 具有相同的底层结构，但不会继承 User 的方法。type plain = User 则只是类型别名，两个名字仍指向同一个类型，递归不会被打断。

// plain 是新的定义类型，不带 User 的方法集。
type plain User

// same 只是别名，same 和 User 完全是同一个类型，不能用于断开递归。
// type same = User

转换成 plain(u) 后，字段、字段标签和底层布局仍可用于默认 JSON 编码；只是这个值不再实现原来的 MarshalJSON。这正好满足“复用默认字段编码，但不要再次进入自定义方法”的要求。

推荐的自定义 MarshalJSON 写法

把转换后的值放入临时结构体，再用一个普通字段承载新增内容。这样既能继续使用原字段的 JSON 标签，也不会重新触发 User.MarshalJSON：

package main

import "encoding/json"

type User struct {
	Name  string `json:"name"`
	Level int    `json:"level"`
}

// MarshalJSON 在保留默认字段的同时追加 label。
func (u User) MarshalJSON() ([]byte, error) {
	type plain User
	// 匿名字段使用 plain，避免重新命中 User.MarshalJSON。
	return json.Marshal(struct {
		plain
		Label string `json:"label"`
	}{
		plain: plain(u),
		Label: "member",
	})
}

这段代码的关键不是匿名字段本身，而是 plain 的方法集。编码器看到临时结构体里的 plain 时，会按普通结构体处理它的字段，所以最终结果可以包含 name、level 和 label。

错误返回和嵌套字段要怎么处理

MarshalJSON 的签名要求返回 ([]byte, error)，不要为了“保证能返回 JSON”而丢掉 json.Marshal 的错误。新增字段如果来自不能编码的值，错误仍然应该向上传递：

func (u User) MarshalJSON() ([]byte, error) {
	type plain User
	// json.Marshal 失败时原样返回，让调用方决定如何记录或重试。
	return json.Marshal(struct {
		plain
		Meta map[string]any `json:"meta,omitempty"`
	}{
		plain: plain(u),
		Meta: map[string]any{"source": "api"},
	})
}

还要注意一个边界：转换只改变最外层 User 的方法集。User 内部的嵌套字段如果自己实现了 MarshalJSON，编码嵌套字段时仍可能调用它。这通常是预期行为；如果嵌套类型也存在递归，应在嵌套类型自己的方法里采用同样的定义类型技巧。

几个容易再次踩中的坑

• 把 type plain = User 当成新类型。它只是别名，方法集没有变化。
• 只给外层加临时结构体，却把原始 User 作为字段放进去。递归会在编码该字段时重新出现。
• 为了绕过递归，手写每个字段的 JSON。字段一旦增删或标签变化，手写版本就容易和结构体定义漂移。
• 忽略错误返回。自定义编码只是改变字段组织方式，不应该改变调用方处理编码失败的责任边界。

相关问题

为什么指针接收者也会遇到同样问题？

只要传入的值在当前编码场景下实现了 json.Marshaler，方法内部再次编码同一个逻辑类型就可能重新进入该方法。解决思路仍是转换为没有自定义方法的新定义类型。

定义类型会不会丢掉 JSON 标签？

不会。底层结构和字段标签仍属于新类型的结构定义；丢掉的是原类型的方法集，这正是打断递归所需要的部分。

因此，给 Go 类型扩展 JSON 输出时，可以把逻辑固定成三步：原类型负责决定额外字段，定义类型负责承接默认字段编码，json.Marshal 负责最后的错误返回和字节生成。这样既保留标准库行为，也不会让自定义方法再次调用自己。