使用 mapslice-json 实现 Golang 中的有序 JSON 映射

在标准库中，Go 的 encoding/json 包处理 JSON 时会将对象转换为无序的 map[string]interface{}，这会导致键顺序丢失。mapslice-json 是一个能够保持 JSON 键顺序的插件库。

安装

go get github.com/romanyx/mapslice-json

基本用法

1. 有序序列化

package main

import (
	"encoding/json"
	"fmt"
	
	"github.com/romanyx/mapslice-json"
)

func main() {
	// 创建一个有序映射
	ms := mapslice.MapSlice{
		mapslice.Item{Key: "name", Value: "Alice"},
		mapslice.Item{Key: "age", Value: 30},
		mapslice.Item{Key: "skills", Value: []string{"Go", "Python"}},
	}

	// 序列化为 JSON（保持顺序）
	data, err := json.Marshal(ms)
	if err != nil {
		panic(err)
	}
	
	fmt.Println(string(data))
	// 输出: {"name":"Alice","age":30,"skills":["Go","Python"]}
}

2. 有序反序列化

func main() {
	jsonStr := `{"name":"Bob","age":25,"city":"New York"}`

	// 反序列化为有序映射
	var ms mapslice.MapSlice
	err := json.Unmarshal([]byte(jsonStr), &ms)
	if err != nil {
		panic(err)
	}

	// 遍历有序结果
	for _, item := range ms {
		fmt.Printf("%s: %v\n", item.Key, item.Value)
	}
	// 输出:
	// name: Bob
	// age: 25
	// city: New York
}

高级用法

1. 与结构体互转

type Person struct {
	Name   string
	Age    int
	Skills []string
}

func main() {
	// 结构体转有序映射
	p := Person{Name: "Charlie", Age: 35, Skills: []string{"Java", "C++"}}
	
	// 先转为普通 JSON
	data, _ := json.Marshal(p)
	
	// 再转为有序映射
	var ms mapslice.MapSlice
	json.Unmarshal(data, &ms)
	
	// 可以保持字段顺序
	fmt.Println(ms) // [{Key:Name Value:Charlie} {Key:Age Value:35} ...]
}

2. 嵌套结构处理

func main() {
	jsonStr := `{
		"user": {
			"name": "David",
			"preferences": {
				"theme": "dark",
				"notifications": true
			}
		},
		"timestamp": "2023-01-01"
	}`

	var data mapslice.MapSlice
	json.Unmarshal([]byte(jsonStr), &data)
	
	// 嵌套结构也会保持顺序
	fmt.Println(data)
}

性能考虑

mapslice-json 相比标准库会有一些性能开销，因为它需要维护顺序信息。在不需要保持顺序的场合，建议仍使用标准库。

替代方案

如果只需要在输出时保持顺序，也可以考虑使用 json.MarshalIndent 配合自定义的 MarshalJSON 方法：

type OrderedMap struct {
	keys   []string
	values map[string]interface{}
}

func (om *OrderedMap) MarshalJSON() ([]byte, error) {
	var buf bytes.Buffer
	buf.WriteByte('{')
	for i, key := range om.keys {
		if i > 0 {
			buf.WriteByte(',')
		}
		// 序列化key
		keyBytes, _ := json.Marshal(key)
		buf.Write(keyBytes)
		buf.WriteByte(':')
		// 序列化value
		valBytes, _ := json.Marshal(om.values[key])
		buf.Write(valBytes)
	}
	buf.WriteByte('}')
	return buf.Bytes(), nil
}

但 mapslice-json 提供了更完整的解决方案，特别是对于反序列化场景。

总结

mapslice-json 是处理需要保持 JSON 键顺序场景的良好选择，它提供了简单的 API 并与标准库兼容。在需要严格保持 JSON 键顺序的配置处理、API 交互等场景中特别有用。