如何在 Go 中为同时包含导出与非导出字段的结构体实现自定义 JSON 序列化

花韻仙語 2026-01-11 00:00:00 次阅读

go 的 json 包默认仅序列化导出（大写首字母）字段，但通过实现 marshaljson 和 unmarshaljson 方法，可安全地包含非导出字段——关键在于避免递归调用，推荐使用独立的中间结构体（如 testjson）进行桥接。

在 Go 中，JSON 编解码默认仅处理导出字段（即首字母大写的字段），这是由语言的可见性规则决定的。若需在 JSON 中保留非导出字段（如 fieldA），必须手动实现 json.Marshaler 和 json.Unmarshaler 接口。但直接在 MarshalJSON 中调用 json.Marshal(t) 会导致无限递归——因为这又会触发 t.MarshalJSON() 自身，最终栈溢出。

✅ 正确做法是：引入一个纯导出字段的中间结构体（DTO），作为 JSON 数据的“镜像”，并在 MarshalJSON/UnmarshalJSON 中显式映射原始结构体与该 DTO：

type Test struct {
    fieldA string // 非导出，需手动参与 JSON
    FieldB int    // 导出，可自动参与（但统一走 DTO 更清晰可控）
    FieldC string // 导出
}

// TestJSON 是仅用于 JSON 编解码的导出结构体，字段名与 JSON key 对齐
type TestJSON struct {
    FieldA string `json:"fieldA"`
    FieldB int    `json:"fieldB"`
    FieldC string `json:"fieldC"`
}

func (t *Test) MarshalJSON() ([]byte, error) {
    return json.Marshal(TestJSON{
        FieldA: t.fieldA,
        FieldB: t.FieldB,
        FieldC: t.FieldC,
    })
}

func (t *Test) UnmarshalJSON(b []byte) error {
    var temp TestJSON
    if err := json.Unmarshal(b, &temp); err != nil {
        return err
    }
    // 显式赋值回原结构体（含非导出字段）
    t.fieldA = temp.FieldA
    t.FieldB = temp.FieldB
    t.FieldC = temp.FieldC
    return nil
}

? 关键优势：

✅ 完全避免递归：json.Marshal 操作的是 TestJSON（无自定义方法的 Plain Struct），不会触发 Test.MarshalJSON；
✅ 类型安全 & 可维护：字段映射集中、显式，新增字段只需同步更新 TestJSON 和两个方法，IDE 可提示缺失项；
✅ 兼容标准库行为：支持 omitempty、自定义 tag、嵌套结构等所有 json tag 特性；
✅ 无副作用：不修改原始结构体设计（无需将 fieldA 强行导出破坏封装）。

⚠️ 注意事项：