rbadger

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 12, 2025 License: GPL-3.0 Imports: 6 Imported by: 0

README

rose-badger

这个项目是对 hypermodeinc/badger 库的封装，提供了简单易用的 API 接口，使得在项目中可以方便地使用 BadgerDB 作为底层存储。

特性

  • 简单易用的 API
  • 支持基本的键值对操作：Get、Set、Del、Exists
  • 支持带过期时间的缓存操作
  • 支持原子计数器操作
  • 支持垃圾回收
  • 线程安全

安装

go get github.com/leafney/rose-badger

依赖包：

go get github.com/dgraph-io/badger/v4

使用示例

基本操作
// 创建一个新的BadgerDB实例
db, err := NewBadgerDB("./data")
if err != nil {
    log.Fatal(err)
}
defer db.Close()

// 设置值
err = db.SetS("key", "value")
if err != nil {
    log.Fatal(err)
}

// 获取值
val, err := db.GetS("key")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("值: %s\n", val)

// 检查键是否存在
if db.Exists("key") {
    fmt.Println("键存在")
} else {
    fmt.Println("键不存在")
}

// 删除键
err = db.Del("key")
if err != nil {
    log.Fatal(err)
}
带过期时间的操作
// 设置带过期时间的值（1小时后过期）
err = db.XSetExS("key", "value", time.Hour)
if err != nil {
    log.Fatal(err)
}

// 设置带过期时间的值（3600秒后过期）
err = db.XSetExSecS("key", "value", 3600)
if err != nil {
    log.Fatal(err)
}

// 获取带过期时间的值
val, err := db.XGetS("key")
if err != nil {
    log.Fatal(err)
}
if val == "" {
    fmt.Println("键不存在或已过期")
} else {
    fmt.Printf("值: %s\n", val)
}

// 获取剩余生存时间（TTL）
ttl, err := db.XTTL("key")
if err != nil {
    log.Fatal(err)
}
switch ttl {
case -2:
    fmt.Println("键不存在")
case -1:
    fmt.Println("键未设置过期时间")
default:
    fmt.Printf("剩余生存时间: %d秒\n", ttl)
}

// 设置已存在键的过期时间
err = db.XExpire("key", time.Hour)
if err != nil {
    log.Fatal(err)
}

// 设置已存在键的过期时间（秒）
err = db.XExpireSec("key", 3600)
if err != nil {
    log.Fatal(err)
}

// 设置已存在键的过期时间点
err = db.XExpireAt("key", time.Now().Add(time.Hour))
if err != nil {
    log.Fatal(err)
}
计数器操作
// 将计数器加1
count, err := db.XIncr("counter")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", count)

// 将计数器加10
count, err = db.XIncrBy("counter", 10)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", count)

// 将计数器减1
count, err = db.XDecr("counter")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", count)

// 将计数器减5
count, err = db.XDecrBy("counter", 5)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", count)
扫描操作
// 扫描所有以"user:"为前缀的key
keys, err := db.FindKeys("user:")
if err != nil {
    log.Fatal(err)
}
for _, key := range keys {
    fmt.Printf("找到key: %s\n", key)
}

// 扫描所有以"cache:"为前缀且未过期的key
validKeys, err := db.FindXKeys("cache:")
if err != nil {
    log.Fatal(err)
}
for _, key := range validKeys {
    fmt.Printf("找到未过期的key: %s\n", key)
}
垃圾回收
// 运行垃圾回收以清理过期的值日志
err = db.RunGC(0.5) // 丢弃比例为0.5
if err != nil {
    log.Fatal(err)
}

API 参考

基本操作
  • NewBadgerDB(dbPath string) (*BadgerDB, error) - 创建一个新的 BadgerDB 实例
  • NewBadgerDBWithOptions(opts badger.Options) (*BadgerDB, error) - 创建一个带自定义选项的 BadgerDB 实例
  • Get(key string) ([]byte, error) - 获取指定键的值
  • GetS(key string) (string, error) - 获取指定键的字符串值
  • Set(key string, value []byte) error - 设置键的值
  • SetS(key string, value string) error - 设置键的字符串值
  • Exists(key string) bool - 检查键是否存在
  • Del(key string) error - 删除指定的键
  • Close() error - 关闭数据库连接
带过期时间的操作
  • XGet(key string) ([]byte, error) - 获取带过期时间的缓存数据
  • XGetS(key string) (string, error) - 获取带过期时间的字符串数据
  • XSet(key string, value []byte) error - 设置带过期时间的缓存数据
  • XSetS(key string, value string) error - 设置带过期时间的字符串数据
  • XSetEx(key string, value []byte, expires time.Duration) error - 设置带过期时间的缓存数据
  • XSetExS(key string, value string, expires time.Duration) error - 设置带过期时间的字符串数据
  • XSetExSec(key string, value []byte, seconds int64) error - 设置带过期时间的缓存数据（秒）
  • XSetExSecS(key string, value string, seconds int64) error - 设置带过期时间的字符串数据（秒）
  • XTTL(key string) (int64, error) - 返回键的剩余生存时间（秒）
  • XExpire(key string, expires time.Duration) error - 设置键的过期时间
  • XExpireSec(key string, seconds int64) error - 设置键的过期时间（秒）
  • XExpireAt(key string, tm time.Time) error - 设置键的过期时间点
计数器操作
  • XIncrBy(key string, increment int64) (int64, error) - 将键中存储的数字值增加指定的值
  • XIncr(key string) (int64, error) - 将键中存储的数字值加1
  • XDecr(key string) (int64, error) - 将键中存储的数字值减1
  • XDecrBy(key string, decrement int64) (int64, error) - 将键中存储的数字值减少指定的值
扫描操作
  • FindKeys(prefix string) ([]string, error) - 扫描所有匹配指定前缀的key列表
  • FindXKeys(prefix string) ([]string, error) - 扫描所有匹配指定前缀且未过期的key列表
其他操作
  • RunGC(discardRatio float64) error - 运行垃圾回收以清理过期的值日志

实现说明

  • 使用 badger.DB 作为底层存储
  • 使用 gob 编码和解码 CacheType 结构体来存储数据和过期时间
  • 使用互斥锁 sync.Mutex 确保并发安全
  • 过期时间的处理：在读取时检查过期时间，如果已过期则删除并返回 nil
  • 计数器操作：使用 strconv 包进行字符串和整数之间的转换

注意事项

  • 在使用完数据库后，务必调用 Close() 方法关闭数据库连接
  • 对于大量写入操作，可以考虑定期调用 RunGC() 方法进行垃圾回收
  • 对于需要频繁更新的键，可以使用计数器操作来避免读取-修改-写入的竞争条件

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BadgerDB 

type BadgerDB struct {
	// contains filtered or unexported fields
}

BadgerDB 结构体封装了 badger 的基本操作

func NewBadgerDB 

func NewBadgerDB(dbPath string) (*BadgerDB, error)

NewBadgerDB 创建一个新的 BadgerDB 实例 示例： 

db, err := NewBadgerDB("./data")
if err != nil {
    log.Fatal(err)
}
defer db.Close()

func NewBadgerDBWithOptions 

func NewBadgerDBWithOptions(opts badger.Options) (*BadgerDB, error)

NewBadgerDBWithOptions 创建一个带自定义选项的 BadgerDB 实例 示例： 

opts := badger.DefaultOptions("./data")
opts.SyncWrites = true
db, err := NewBadgerDBWithOptions(opts)
if err != nil {
    log.Fatal(err)
}
defer db.Close()

func (*BadgerDB) Close 

func (b *BadgerDB) Close() error

Close 关闭数据库连接 示例： 

defer db.Close()

func (*BadgerDB) Del 

func (b *BadgerDB) Del(key string) error

Del 删除指定的key 示例： 

err := db.Del("key")
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) Exists 

func (b *BadgerDB) Exists(key string) bool

Exists 检查key是否存在 示例： 

if db.Exists("key") {
    fmt.Println("key存在")
} else {
    fmt.Println("key不存在")
}

func (*BadgerDB) FindKeys added in v0.1.1 

func (b *BadgerDB) FindKeys(prefix string) ([]string, error)

FindKeys 扫描所有匹配指定前缀的key列表 返回所有匹配前缀的key，包括普通存储和带过期时间存储的key 示例： 

keys, err := db.FindKeys("user:")
if err != nil {
    log.Fatal(err)
}
for _, key := range keys {
    fmt.Printf("找到key: %s\n", key)
}

func (*BadgerDB) FindXKeys added in v0.1.1 

func (b *BadgerDB) FindXKeys(prefix string) ([]string, error)

FindXKeys 扫描所有匹配指定前缀且未过期的key列表 只返回带过期时间存储且未过期的key，会自动清理已过期的key 示例： 

keys, err := db.FindXKeys("cache:")
if err != nil {
    log.Fatal(err)
}
for _, key := range keys {
    fmt.Printf("找到未过期的key: %s\n", key)
}

func (*BadgerDB) Get 

func (b *BadgerDB) Get(key string) ([]byte, error)

Get 获取指定key的值 示例： 

value, err := db.Get("key")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("值: %s\n", value)

func (*BadgerDB) GetS 

func (b *BadgerDB) GetS(key string) (string, error)

GetS 获取指定key的字符串值 示例： 

value, err := db.GetS("key")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("字符串值: %s\n", value)

func (*BadgerDB) RunGC 

func (b *BadgerDB) RunGC(discardRatio float64) error

RunGC 运行垃圾回收以清理过期的值日志 返回值： - 如果垃圾回收成功或没有需要清理的数据，返回 nil - 如果发生真正的错误，返回相应的错误 示例： 

err := db.RunGC(0.5) // 丢弃比例为0.5
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) Set 

func (b *BadgerDB) Set(key string, value []byte) error

Set 设置key的值 示例： 

err := db.Set("key", []byte("value"))
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) SetS 

func (b *BadgerDB) SetS(key string, value string) error

SetS 设置key的字符串值 示例： 

err := db.SetS("key", "value")
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XDecr 

func (b *BadgerDB) XDecr(key string) (int64, error)

XDecr 将key中存储的数字值减1 该方法是并发安全的 示例： 

value, err := db.XDecr("counter")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", value)

func (*BadgerDB) XDecrBy 

func (b *BadgerDB) XDecrBy(key string, decrement int64) (int64, error)

XDecrBy 将key中存储的数字值减少指定的值 该方法是并发安全的 示例： 

value, err := db.XDecrBy("counter", 10)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", value)

func (*BadgerDB) XExpire 

func (b *BadgerDB) XExpire(key string, expires time.Duration) error

XExpire 设置key的过期时间 示例： 

err := db.XExpire("key", time.Hour)
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XExpireAt 

func (b *BadgerDB) XExpireAt(key string, tm time.Time) error

XExpireAt 设置key的过期时间点 该方法是并发安全的 示例： 

err := db.XExpireAt("key", time.Now().Add(time.Hour))
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XExpireSec 

func (b *BadgerDB) XExpireSec(key string, seconds int64) error

XExpireSec 设置key的过期时间(秒) 示例： 

err := db.XExpireSec("key", 3600)
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XGet 

func (b *BadgerDB) XGet(key string) ([]byte, error)

XGet 获取带过期时间的缓存数据 当数据过期时会自动删除并返回nil 示例： 

value, err := db.XGet("key")
if err != nil {
    log.Fatal(err)
}
if value == nil {
    fmt.Println("key不存在或已过期")
} else {
    fmt.Printf("值: %s\n", value)
}

func (*BadgerDB) XGetS 

func (b *BadgerDB) XGetS(key string) (string, error)

XGetS 获取带过期时间的字符串数据 示例： 

value, err := db.XGetS("key")
if err != nil {
    log.Fatal(err)
}
if value == "" {
    fmt.Println("key不存在或已过期")
} else {
    fmt.Printf("字符串值: %s\n", value)
}

func (*BadgerDB) XIncr 

func (b *BadgerDB) XIncr(key string) (int64, error)

XIncr 将key中存储的数字值加1 该方法是并发安全的 示例： 

value, err := db.XIncr("counter")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", value)

func (*BadgerDB) XIncrBy 

func (b *BadgerDB) XIncrBy(key string, increment int64) (int64, error)

XIncrBy 将key中存储的数字值增加指定的值 该方法是并发安全的 示例： 

value, err := db.XIncrBy("counter", 10)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("新值: %d\n", value)

func (*BadgerDB) XSet 

func (b *BadgerDB) XSet(key string, value []byte) error

XSet 设置带过期时间的缓存数据 示例： 

err := db.XSet("key", []byte("value"))
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XSetEx 

func (b *BadgerDB) XSetEx(key string, value []byte, expires time.Duration) error

XSetEx 设置带过期时间的缓存数据 （使用 time.Duration） 示例： 

err := db.XSetEx("key", []byte("value"), time.Hour)
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XSetExS 

func (b *BadgerDB) XSetExS(key string, value string, expires time.Duration) error

XSetExS 设置带过期时间的字符串数据 （使用 time.Duration） 示例： 

err := db.XSetExS("key", "value", time.Hour)
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XSetExSec 

func (b *BadgerDB) XSetExSec(key string, value []byte, seconds int64) error

XSetExSec 设置带过期时间的缓存数据（使用秒数） 示例： 

err := db.XSetExSec("key", []byte("value"), 3600)
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XSetExSecS 

func (b *BadgerDB) XSetExSecS(key string, value string, seconds int64) error

XSetExSecS 设置带过期时间的字符串数据（使用秒数） 示例： 

err := db.XSetExSecS("key", "value", 3600)
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XSetS 

func (b *BadgerDB) XSetS(key string, value string) error

XSetS 设置带过期时间的字符串数据 示例： 

err := db.XSetS("key", "value")
if err != nil {
    log.Fatal(err)
}

func (*BadgerDB) XTTL 

func (b *BadgerDB) XTTL(key string) (int64, error)

XTTL 返回key的剩余生存时间(秒) 返回值说明： 

-2: key不存在（包括已过期的情况）
-1: key存在但未设置过期时间
>=0: key的剩余生存时间(秒)

示例： 

ttl, err := db.XTTL("key")
if err != nil {
    log.Fatal(err)
}
switch ttl {
case -2:
    fmt.Println("key不存在")
case -1:
    fmt.Println("key未设置过期时间")
default:
    fmt.Printf("剩余生存时间: %d秒\n", ttl)
}

type CacheType 

type CacheType struct {
	Data   []byte
	Expire int64 // Unix timestamp 表示过期时间点
}

CacheType 定义缓存数据结构

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.