Go-Shelve 持久化键值存储映射对象插件库使用指南

Go-Shelve 是一个无依赖的 Go 包，提供了一个名为 Shelf 的持久化、类似 map 的对象。它可以让你直接存储和检索 Go 对象，序列化和存储由 Shelf 自动处理。

安装

在你的 Go 项目中使用这个包，可以通过 go get 安装：

go get github.com/lucmq/go-shelve

基本使用

以下示例展示了如何使用带有字符串键和值的 Shelf。Shelf 类型使用泛型，可以用任何 Go 类型作为值，任何可比较类型作为键。

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/lucmq/go-shelve/shelve"
)

func main() {
	// 注意：在实际应用中，请确保将 os.TempDir() 替换为非临时目录
	// 并提供更好的错误处理
	path := filepath.Join(os.TempDir(), "go-shelve")

	// 使用默认选项打开 shelf
	shelf, err := shelve.Open[string, string](path)
	if err != nil {
		log.Fatal(err)
	}
	defer shelf.Close()

	// 使用数据库
	shelf.Put("language", "Go")
	shelf.Put("module", "Go-Shelve")

	// 注意：保存的值将在重启后仍然可用
	value, ok, _ := shelf.Get("language")
	fmt.Println(value, ok)
	
	// 输出: Go true
}

自定义数据库和编解码器

默认情况下，Shelf 使用 Gob 格式序列化数据，并使用 sdb（“shelve-db”）存储，这是一个为该项目创建的简单键值存储。

下面的示例展示了如何自定义 Shelf 以使用 BoltDB 进行存储，同时使用 MessagePack 进行序列化：

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	bboltd "github.com/lucmq/go-shelve/driver/db/bbolt"
	"github.com/lucmq/go-shelve/driver/encoding/msgpack"
	"github.com/lucmq/go-shelve/shelve"
)

func main() {
	path := filepath.Join(os.TempDir(), "bolt-example")

	db, _ := bboltd.NewDefault(path, []byte("example-bucket"))
	codec := msgpack.NewDefault()

	// 使用自定义选项打开 shelf
	shelf, err := shelve.Open[string, string](
		path,
		shelve.WithDatabase(db),
		shelve.WithCodec(codec),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer shelf.Close()

	// 使用数据库
	shelf.Put("language", "Go")
	shelf.Put("module", "Go-Shelve")

	value, ok, _ := shelf.Get("language")
	fmt.Println(value, ok)

	// 输出: Go true
}

使用 diskv 和 JSON 的可读文件

Shelf 的一个有趣用例是使用 JSON 格式存储可透明读取的数据，每个文件都有一个语义上有意义的键名。这可以用于将配置和应用程序数据保存为人类可读的文件。

下面的示例展示了如何使用 diskv 驱动和 JSON 编解码器来保存游戏数据：

package main

import (
	"fmt"
	"os"
	"path/filepath"

	diskvd "github.com/lucmq/go-shelve/driver/db/diskv"
	"github.com/lucmq/go-shelve/shelve"
)

var StoragePath = filepath.Join(os.TempDir(), "game-test", "db")

type Player struct {
	Name  string
	Level int
	Gold  int
	Items []string
}

type Config struct {
	Difficulty string
}

// NewShelf 创建一个使用 Diskv 和 JSON 的自定义 Shelf
func NewShelf[V any](path string) (*shelve.Shelf[string, V], error) {
	path = filepath.Join(StoragePath, path)
	extension := "json" // 记录文件的扩展名

	db, err := diskvd.NewDefault(path, extension)
	if err != nil {
		return nil, err
	}

	return shelve.Open[string, V](
		path,
		shelve.WithDatabase(db),
		shelve.WithCodec(shelve.JSONCodec()),
	)
}

func main() {
	// 使用自定义选项打开 shelf
	players, _ := NewShelf[Player]("players")
	config, _ := NewShelf[Config]("config")

	defer players.Close()
	defer config.Close()

	// 创建游戏数据
	player := Player{
		Name:  "Frodo",
		Level: 14,
		Gold:  9999,
		Items: []string{"Sting", "Lembas"},
	}
	cfg := Config{
		Difficulty: "Hard",
	}

	// 保存数据。序列化和持久化将由 Shelf 自动处理
	players.Put(player.Name, player)
	config.Put("config", cfg)

	// 应用存储将包含可读的 JSON 文件
	// 包含配置和游戏状态，可以检索回 Go 类型
	value, ok, _ := players.Get("Frodo")
	fmt.Println(ok, value.Name, value.Items)

	// 输出: true Frodo [Sting Lembas]
}

贡献

欢迎对这个包的贡献！如果你发现任何问题或有改进建议，请随时提出问题或提交拉取请求。

许可证

该项目采用 MIT 许可证 - 详见 LICENSE 文件。