Go语言自定义JSON序列化实现：Marshaler接口与自定义接收器解析

许多 Go 开发者在调用 json.Marshal 时，会发现自定义的 MarshalJSON 方法没有被触发，或者序列化结果与预期相差甚远。根本原因在于：json.Marshal 只会调用那些直接实现了 json.Marshaler 或 json.Unmarshaler 接口的方法。如果方法采用指针接收器实现，但传入的是值类型，或者结构体中包含未导出或不支持类型的字段，那么序列化要么不生效，要么直接报错。

为什么 json.Marshal 不调用你的方法？

这是 Go 新手最容易踩到的陷阱之一。需要明白，Go 的 JSON 序列化仅识别两个接口——json.Marshaler 和 json.Unmarshaler，并且只有当类型直接实现这两个接口时才会生效。最常见的错误场景是：为指针类型实现了接口，但传给 json.Marshal 的却是值类型的变量，此时自定义方法完全不会被调用。

举个例子，定义了 func (t *MyType) MarshalJSON() ([]byte, error)，但传入的是 MyType{}（值而非指针），那么 MarshalJSON 不会执行。

• 首先检查接收器类型：值接收器适用于值变量，指针接收器适用于指针变量或取地址后的值
• 接着确认变量实际类型：使用 fmt.Printf("%T", v) 查看传入的是 MyType 还是 *MyType
• 当结构体字段为值类型时，嵌套嵌入也要确保接收器一致性，否则嵌套序列化会跳过自定义逻辑

如何让时间字段输出为 "2006-01-02" 而不是 RFC3339？

标准库 time.Time 的 MarshalJSON 默认生成带时区和纳秒的完整 RFC3339 格式字符串，但实际业务场景中通常只需要简洁的日期格式，例如 "2006-01-02"。由于标准库类型不可修改，不能直接改动 time.Time，因此需要包装一层自定义类型。

type Date time.Time

func (d Date) MarshalJSON() ([]byte, error) {
    return []byte(`"` + time.Time(d).Format("2006-01-02") + `"`), nil
}

// 用法：struct 中字段类型声明为 Date，不是 time.Time
type Event struct {
    When Date `json:"when"`
}

• 务必确保返回的字节包含双引号，因为 json.Marshal 不会自动添加
• 不要遗漏 time.Time(d) 类型转换，否则无法调用 Format 方法
• 若需要反序列化，则必须同时实现 UnmarshalJSON，并正确处理带引号的字符串输入

嵌套结构体里部分字段想忽略，但又不想用 json:"-"？

全局忽略使用 tag 是最便捷的方式，但有时逻辑更复杂，比如希望只在特定状态（如 Status == "draft"）下才忽略某个字段。这种情况下 tag 无法满足需求，需要通过自定义 MarshalJSON 来手动控制字段的输出与否。

func (u User) MarshalJSON() ([]byte, error) {
    type Alias User // 防止无限递归
    raw := struct {
        *Alias
        CreatedAt string `json:"created_at,omitempty"`
    }{
        Alias: (*Alias)(&u),
    }
    if u.Status != "draft" {
        raw.CreatedAt = u.CreatedAt.Format(time.RFC3339)
    }
    return json.Marshal(raw)
}

• 关键在于使用 type Alias User，以避免递归调用自身的 MarshalJSON 导致死循环
• 字段名的大小写必须与目标 JSON key 完全一致，否则对应字段不会出现在输出中
• 避免在 MarshalJSON 中直接拼接 JSON 字符串，这种方法易出错且难以维护；推荐优先使用 map 或匿名 struct 路线

为什么实现了 MarshalJSON 却仍报 json: unsupported type？

您可能会疑惑：明明实现了接口，为什么仍然报错？实际上，这个错误通常不是因为接口未实现，而是因为底层字段类型不被 json.Marshal 所支持，例如字段为 func、chan、map[interface{}]interface{}，或者是未导出的字段（小写字母开头）。

• 检查结构体中的所有字段是否可导出（首字母大写），否则即便实现了接口，内部字段也无法通过反射访问
• 确认没有嵌入不支持序列化的类型，例如 http.Handler、sync.Mutex 等，它们本身不可序列化
• 若使用 map[string]interface{} 存储动态数据，需确保值类型都在 JSON 支持范围内（string、int、float、bool、map、slice、nil）
• 对于第三方类型（如 uuid.UUID），需自行实现 MarshalJSON，或利用其自带序列化方法转换为字符串后再存储

最稳妥的方案是：在自定义 MarshalJSON 中显式列出需要序列化的字段，而不是依赖反射自动遍历。这既能避免 unsupported type 报错，又能精确控制输出内容。