将 Go 语言中的 map 按自定义结构（如 JSON 数组）序列化为特定格式

本文详解如何通过实现 json.marshaler 和 json.unmarshaler 接口，将原生 map[String]string 序列化为带包装字段（如 “map”）的 json 数组格式，而非默认的键值对对象，并提供完整可运行示例与双向序列化支持。

本文详解如何通过实现 json.marshaler 和 json.unmarshaler 接口，将原生 map[string]string 序列化为带包装字段（如 “map”）的 json 数组格式，而非默认的键值对对象，并提供完整可运行示例与双向序列化支持。

在 go 中，json.Marshal 对 map[string]string 的默认行为是将其转为标准 JSON 对象（如 {“key1″:”val1″,”key2″:”val2”}），但实际业务中常需输出更结构化的格式——例如将键值对映射为数组项，并包裹在统一字段下，如：

{   "Map": [     {"Name": "key1", "Date": "val1"},     {"Name": "key2", "Date": "val2"}   ] }

这种需求无法通过结构体标签或 json.RawMessage 简单达成，必须借助自定义序列化逻辑。核心方案是为自定义类型实现 json.Marshaler 和 json.Unmarshaler 接口。

✅ 正确实现方式

首先定义承载单条映射的数据结构和封装类型：

type mapInfo struct {     Name string `json:"name"`     Date string `json:"date"` }  type CustomMap map[string]string

接着实现 MarshalJSON 方法：遍历原始 map，将每对 key:value 转为 mapInfo 实例并聚合进切片，再嵌入匿名结构体中完成外层包装：

func (cm CustomMap) MarshalJSON() ([]byte, error) {     var out struct {         Map []mapInfo `json:"map"`     }     for k, v := range cm {         out.Map = append(out.Map, mapInfo{Na me: k, Date: v})     }     return json.Marshal(out) }

? 提示：若对性能敏感（如高频大 map 序列化），可改用 bytes.Buffer 手动拼接 JSON 字符串以避免中间结构体分配，但多数场景下上述写法已足够清晰高效。

同样，为支持反序列化，必须实现 UnmarshalJSON：

func (cm CustomMap) UnmarshalJSON(b []byte) error {     var out struct {         Map []mapInfo `json:"map"`     }     if err := json.Unmarshal(b, &out); err != nil {         return err     }     // 清空原有内容（因 map 是引用类型，需显式重置）     for k := range cm {         delete(cm, k)     }     // 重建映射关系     for _, item := range out.Map {         cm[item.Name] = item.Date     }     return nil }

⚠️ 注意：CustomMap 是 map[string]string 的别名，属于引用类型；UnmarshalJSON 方法接收的是值接收者（cm CustomMap），因此内部修改不会影响调用方原始 map。必须使用指针接收者，否则反序列化无效：

func (cm *CustomMap) UnmarshalJSON(b []byte) error { // ✅ 改为指针接收者     var out struct {         Map []mapInfo `json:"map"`     }     if err := json.Unmarshal(b, &out); err != nil {         return err     }     *cm = make(CustomMap) // 重新分配底层 map     for _, item := range out.Map {         (*cm)[item.Name] = item.Date     }     return nil }

? 完整可运行示例

package main  import (     "encoding/json"     "fmt" )  type mapInfo struct {     Name string `json:"name"`     Date string `json:"date"` }  type CustomMap map[string]string  func (cm CustomMap) MarshalJSON() ([]byte, error) {     var out struct {         Map []mapInfo `json:"map"`     }     for k, v := range cm {         out.Map = append(out.Map, mapInfo{Name: k, Date: v})     }     return json.Marshal(out) }  func (cm *CustomMap) UnmarshalJSON(b []byte) error {     var out struct {         Map []mapInfo `json:"map"`     }     if err := json.Unmarshal(b, &out); err != nil {         return err     }     *cm = make(CustomMap)     for _, item := range out.Map {         (*cm)[item.Name] = item.Date     }     return nil }  func main() {     m := CustomMap{"user_id": "123", "status": "active"}     data, _ := json.Marshal(m)     fmt.Println(string(data))     // 输出: {"map":[{"name":"user_id","date":"123"},{"name":"status","date":"active"}]}      var m2 CustomMap     json.Unmarshal(data, &m2)     fmt.Printf("%+vn", m2) // map[user_id:123 status:active] }

? 总结

• Go 的 json 包不支持直接“重排” map 的序列化结构，必须通过自定义 MarshalJSON/UnmarshalJSON 实现；
• 使用值接收者仅适用于只读序列化（MarshalJSON），反序列化（UnmarshalJSON）必须使用指针接收者；
• 该模式灵活可扩展：可轻松适配更多字段（如添加 timestamp、Type）、嵌套结构或动态 key 映射；
• 若需全局生效（如所有 map 都按此规则），应封装为工具函数或中间结构体，而非侵入性修改基础类型。

此方法兼顾语义清晰性、类型安全性与 JSON 标准兼容性，是构建 REST API 响应、配置序列化等场景的推荐实践。