Go json.Marshaler 怎样避免递归调用

给结构体增加 MarshalJSON 后，最容易踩到的坑不是字段标签，而是方法内部又把原对象传给 json.Marshal。因为 encoding/json 发现这个类型实现了 Marshaler，会再次调用它的 MarshalJSON，于是调用链回到原点。解决办法很明确：在自定义方法内部声明一个与原结构体字段相同、但不拥有原方法集的别名类型，再把别名值交给 json.Marshal。

官方文档：https://pkg.go.dev/encoding/json

不要在 MarshalJSON 中直接对原类型调用 json.Marshal。用别名类型隔离方法集，再用匿名结构体合并额外字段，就能保留默认编码并避免递归。

为什么对原类型编码会回到同一个方法

json.Marshal 会递归遍历输入值；当值的类型实现了 Marshaler 时，编码器会调用它的 MarshalJSON。因此下面的写法看起来像“先按默认规则编码，再追加字段”，实际上没有离开 Order 的方法集。

package main

import "encoding/json"

type Order struct {
	ID    int    `json:"id"`
	State string `json:"state"`
}

// MarshalJSON 负责增加一个展示字段。
func (o Order) MarshalJSON() ([]byte, error) {
	// 这里仍然把原类型 Order 交给 json.Marshal，会再次调用本方法。
	return json.Marshal(struct {
		Order
		Label string `json:"label"`
	}{
		Order: o,
		Label: "待处理",
	})
}

匿名结构体里嵌入 Order 后，编码器仍然会看到一个带有 MarshalJSON 方法的 Order 值。这个方法创建新对象，新对象又包含 Order，于是形成“原类型 → MarshalJSON → json.Marshal → 原类型”的回环。

用别名类型隔离原来的方法集

在方法内部声明 type orderAlias Order，得到的是一个新的定义类型。它保留字段和字段标签的结构，但不会自动继承 Order 上声明的 MarshalJSON 方法。这样，json.Marshal(orderAlias(o)) 会走结构体的默认编码。

package main

import "encoding/json"

type Order struct {
	ID    int    `json:"id"`
	State string `json:"state"`
}

// MarshalJSON 在默认字段之外增加面向客户端的展示文本。
func (o Order) MarshalJSON() ([]byte, error) {
	// 别名类型只复用字段布局，不携带 Order 的 MarshalJSON 方法。
	type orderAlias Order

	// 匿名结构体负责合并默认字段和自定义字段。
	return json.Marshal(struct {
		orderAlias
		Label string `json:"label"`
	}{
		orderAlias: orderAlias(o),
		Label:      labelForState(o.State),
	})
}

// labelForState 把内部状态映射为稳定的展示文案。
func labelForState(state string) string {
	if state == "paid" {
		return "已支付"
	}
	return "待处理"
}

这里的关键不是“换了一个变量名”，而是定义了新的类型边界。字段仍然来自 Order，但方法查找不会沿用原类型的方法集；额外的 Label 只属于匿名包装结构体。

匿名结构体如何决定字段覆盖结果

别名类型方案通常要解决两个动作：保留原有字段，再追加或覆盖一个 JSON 字段。追加字段时直接在包装结构体中声明新字段即可；如果包装结构体声明了与嵌入字段相同的 JSON 名称，外层字段会参与字段选择，应该明确写出意图，避免读者误以为两个值都会输出。

// MarshalJSON 只覆盖客户端看到的 state 文本，不修改原对象。
func (o Order) MarshalJSON() ([]byte, error) {
	type orderAlias Order
	return json.Marshal(struct {
		orderAlias
		State string `json:"state"`
	}{
		orderAlias: orderAlias(o),
		// 外层字段表达对外契约，覆盖内部状态字段。
		State: labelForState(o.State),
	})
}

如果只是新增字段，建议使用不同的 JSON 名称；如果确实要覆盖，应在写作和代码审查中说明“外层字段是对外契约”。不要同时保留两个同名字段来赌编码器的字段选择规则。

指针接收者和错误返回要一起考虑

如果方法使用指针接收者，只有满足方法调用条件的值才会进入自定义编码；而 MarshalJSON 本身必须返回合法 JSON 字节和错误。别名类型只能解决递归，不能替你处理业务字段错误、空指针或外部编码失败。

// MarshalJSON 使用值接收者，调用方传值或传指针都能复用这份编码规则。
func (o Order) MarshalJSON() ([]byte, error) {
	type orderAlias Order
	wrapper := struct {
		orderAlias
		Label string `json:"label"`
	}{
		orderAlias: orderAlias(o),
		Label:      labelForState(o.State),
	}

	// 让底层编码错误原样返回，调用方才能区分失败原因。
	return json.Marshal(wrapper)
}

若自定义方法要调用另一个可能失败的编码步骤，不要忽略错误，也不要在方法里再次把原类型传回 json.Marshal。先构造一个不带原方法的中间值，再把这一步的错误返回给调用方。

发布前用这张清单排除递归

• 检查调用对象：MarshalJSON 内部是否还出现了原类型或原类型指针。
• 检查隔离类型：别名类型是否在方法内部定义，并且真正用于传给 json.Marshal。
• 检查包装层：额外字段是否放在匿名结构体中，字段标签是否与对外 JSON 契约一致。
• 检查错误：每一次嵌套编码都返回错误，不用空字节或静默吞错替代。
• 检查边界：值接收者、指针接收者和 nil 指针的调用方式是否符合调用方约定。

记住一句话：别名类型解决的是“方法集隔离”，匿名结构体解决的是“字段合并”。两者组合后，默认字段编码和自定义字段可以共存，递归调用也不会重新命中原来的 MarshalJSON。

相关问题

别名类型和类型别名是同一回事吗？不是。type orderAlias Order 定义新类型；type orderAlias = Order 只是别名，仍然指向原类型，不能用于隔离方法集。

为什么不直接把所有字段复制到新结构体？字段复制容易漏掉新增字段、标签和嵌套结构。别名类型可以复用字段布局，同时把方法调用边界隔离出来。

只追加一个字段还需要 MarshalJSON 吗？如果默认编码已经满足需求，不需要；只有在输出契约确实需要转换、隐藏或追加字段时，才引入自定义方法。