JSON 自定义解码

Go 里给结构体实现 UnmarshalJSON 后，最容易踩的坑是：方法内部又把输入交给 json.Unmarshal，目标仍然是当前类型。标准库看到这个类型还实现了 json.Unmarshaler，就会再次调用同一个方法，最终递归到栈溢出。正确做法不是放弃默认字段映射，而是先声明一个不带方法集的别名，再让标准库解码这个别名。

官方地址：https://pkg.go.dev/encoding/json

把原类型转换成只保留字段定义、没有 UnmarshalJSON 方法集的别名，再用辅助结构叠加原始字段或校验字段。这样默认解码只执行一次，自定义逻辑放在解码前后即可。

为什么直接解码原类型会递归

encoding/json 的解码规则会优先检查目标值是否实现 Unmarshaler。因此下面的写法看起来合理，实际却会不断回到 UnmarshalJSON：

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

func (u *User) UnmarshalJSON(data []byte) error {
	// 目标仍然是 *User；标准库会再次发现这个方法。
	return json.Unmarshal(data, u)
}

递归的关键不在于是否使用指针，而在于目标类型的方法集仍然包含 UnmarshalJSON。如果只想沿用标准字段匹配，应该改变解码目标的类型身份。

类型别名让默认字段解码只走一遍

下面的 userAlias 与 User 具有相同的底层字段布局，但它是一个新的定义类型，没有自动继承 User 的方法。把 JSON 解码到它，标准库就不会再次调用当前方法。

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

func (u *User) UnmarshalJSON(data []byte) error {
	// 新定义类型只保留字段，不带 User 的 UnmarshalJSON 方法集。
	type userAlias User
	var decoded userAlias

	// 先完成标准字段映射；语法错误和类型错误原样返回。
	if err := json.Unmarshal(data, &decoded); err != nil {
		return err
	}

	// 通过一次转换把默认解码结果写回真正的 User。
	*u = User(decoded)
	if u.Name == "" {
		return fmt.Errorf("name is required")
	}
	if u.Age 

这里的顺序很重要：先让标准库处理 JSON 语法和字段类型，再执行业务校验。校验失败时返回错误，调用方可以统一处理，不会得到半验证状态的对象。

辅助结构适合叠加原始字段

如果自定义逻辑需要读取原始 JSON 字段，例如把日期字符串转换成内部时间，或判断字段是否出现，可以把别名和额外字段组合在一个辅助结构中。匿名嵌入让别名继续承担普通字段解码，额外字段则单独保存。

type Event struct {
	Name string `json:"name"`
	Date string `json:"-"`
}

func (e *Event) UnmarshalJSON(data []byte) error {
	// Alias 防止递归，RawDate 保留输入中的原始日期字段。
	type alias Event
	var aux struct {
		alias
		RawDate string `json:"date"`
	}

	if err := json.Unmarshal(data, &aux); err != nil {
		return err
	}
	if aux.Name == "" || aux.RawDate == "" {
		return fmt.Errorf("name and date are required")
	}

	// 业务层确认格式后，再写入内部字段。
	*e = Event(aux.alias)
	e.Date = aux.RawDate
	return nil
}

这种写法适合“默认字段 + 少量自定义字段”的结构。若要区分字段缺失和显式 null，可以把辅助字段声明成 *json.RawMessage 或指针，再根据是否为 nil 判断输入状态。

错误边界要分开处理

还有一个边界：UnmarshalJSON 如果要在方法返回后继续保存传入字节，必须复制 data，不能长期持有它的底层切片。普通字段解码不需要自己保存原始字节时，不必额外复制。

落地时记住这份检查清单

• 方法内部的默认解码目标使用别名，不要再次传入原类型指针。
• 先处理标准库返回的语法和类型错误，再做必填字段、范围和格式校验。
• 需要区分缺失与 null 时，用指针或 json.RawMessage 保存状态。
• 自定义方法可能接收 null，是否接受要写进类型契约。

相关问题

为什么别名转换不会丢掉 JSON 标签？ 因为别名保留了字段定义和标签，改变的是类型的方法集，不是字段元数据。

什么时候应该用 json.RawMessage？ 当字段结构要根据另一个字段决定，或需要延迟第二次解码时使用；普通字段校验不必引入它。