当前位置：首页 > 文章列表 > Golang > Go教程 > Go json.Marshaler 怎样避免递归调用

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

来源：17golang原创 2026-10-18 19:37:39 0浏览收藏

给结构体增加 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 → 原类型”的回环。

Go json.Marshaler 原类型、MarshalJSON 和 json.Marshal 之间形成回环的静态关系说明图 — 图1：原类型实现 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 只属于匿名包装结构体。

Go 原类型与别名类型的方法集隔离并合并额外 JSON 字段的静态结构说明图 — 图2：别名类型保留字段结构但不携带原类型的 MarshalJSON 方法，json.Marshal 得以走默认编码；这是静态结构说明图，不是运行截图。

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

别名类型方案通常要解决两个动作：保留原有字段，再追加或覆盖一个 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。先构造一个不带原方法的中间值，再把这一步的错误返回给调用方。