kv-storage

一个基于 sled 的 Rust 异步持久化 KV 存储库，整体使用方式接近 Redis 的常见数据结构，当前支持：

Key-Value
Map / Hash
List / Queue
Counter
TTL 过期
批量操作
异步迭代扫描

项目已经提供 tokio 异步接口，并通过测试覆盖了 KV、Map、List、Counter、TTL、批量写入、遍历和模式扫描等典型场景。

特性概览

基于 sled 的嵌入式本地存储，无需独立部署数据库服务
面向 tokio 的异步 API，适合服务端项目集成
支持序列化任意实现 Serialize / DeserializeOwned 的数据
提供独立的 Map 与 List 命名空间，便于组织结构化数据
支持计数器自增、自减、设置与读取
支持键、Map、List 的 TTL 与后台过期清理
支持批量插入、批量删除、前缀遍历、通配扫描
可通过 Cargo feature 控制 ttl、len、map_len

安装

Cargo.toml

[dependencies]
kv-storage = "0.1.0"

如需按需关闭默认特性：

[dependencies]
kv-storage = { version = "0.1.0", default-features = false, features = ["ttl", "len", "map_len"] }

默认启用的特性：

ttl：支持过期时间与后台清理
len：支持数据库级 len()
map_len：支持 Map::len()

快速开始

use kv_storage::{Config, init_db, Map, List};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let cfg = Config {
        path: "./db/demo".into(),
        ..Default::default()
    };

    let db = init_db(&cfg).await?;

    db.insert("user:1", &"Alice").await?;
    let user: Option<String> = db.get("user:1").await?;
    println!("user = {:?}", user);

    let profile = db.map("profile", None).await?;
    profile.insert("name", &"Alice").await?;
    profile.insert("age", &18).await?;
    let age: Option<i32> = profile.get("age").await?;
    println!("age = {:?}", age);

    let logs = db.list("logs", None).await?;
    logs.push(&"created").await?;
    logs.push(&"updated").await?;
    let all_logs: Vec<String> = logs.all().await?;
    println!("logs = {:?}", all_logs);

    db.counter_incr("request_count", 1).await?;
    let count = db.counter_get("request_count").await?;
    println!("count = {:?}", count);

    Ok(())
}

配置说明

Config 当前包含以下主要字段：

use kv_storage::Config;

let cfg = Config {
    path: "./db/app".into(),
    ..Default::default()
};

path：sled 数据目录，必填，不能为空
cache_capacity：缓存大小，默认 1GB
cleanup_f：过期数据清理函数，默认会启动后台清理任务

注意：

path 为空时，init_db 会返回错误
默认配置会设置 flush_every_ms(Some(3000))
存储模式当前使用 sled::Mode::LowSpace

核心用法

1. Key-Value

db.insert("k1", &123).await?;
let value: Option<i32> = db.get("k1").await?;
let exists = db.contains_key("k1").await?;
db.remove("k1").await?;

支持批量操作：

db.batch_insert(vec![
    (b"k1".to_vec(), 1),
    (b"k2".to_vec(), 2),
]).await?;

db.batch_remove(vec![
    b"k1".to_vec(),
    b"k2".to_vec(),
]).await?;

2. Map / Hash

use kv_storage::Map;

let map = db.map("orders", None).await?;
map.insert("order_1", &100).await?;
map.insert("order_2", &200).await?;

let value: Option<i32> = map.get("order_1").await?;
let exists = map.contains_key("order_2").await?;
let empty = map.is_empty().await?;
map.remove("order_1").await?;
map.clear().await?;

创建时可附带过期时间（毫秒）：

let session_map = db.map("session:1", Some(30_000)).await?;

3. List / Queue

use kv_storage::List;

let list = db.list("task_queue", None).await?;
list.push(&"task-1").await?;
list.push(&"task-2").await?;

let first: Option<String> = list.pop().await?;
let all: Vec<String> = list.all().await?;
let by_index: Option<String> = list.get_index(0).await?;
let len = list.len().await?;

限制列表长度：

let removed: Option<i32> = list.push_limit(&100, 10, true).await?;

含义：

limit = 10：列表最多保留 10 项
pop_front_if_limited = true：超限时弹出最早的数据
返回值为被移除的元素

4. Counter

db.counter_incr("counter_a", 3).await?;
db.counter_decr("counter_a", 1).await?;
db.counter_set("counter_a", 100).await?;

let value = db.counter_get("counter_a").await?;

5. TTL

如果启用了 ttl 特性，可以对 KV、Map、List 设置过期时间。

db.insert("token", &"abc").await?;
db.expire("token", 5_000).await?;
let ttl = db.ttl("token").await?;

Map / List 同样支持：

let map = db.map("cache_map", None).await?;
map.expire(10_000).await?;

let list = db.list("recent_items", None).await?;
let now_ms = std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH)?
    .as_millis() as i64;
list.expire_at(now_ms + 60_000).await?;

说明：

expire(key, dur) 中的 dur 单位为毫秒
expire_at(key, at) 使用毫秒时间戳
过期后读取通常返回 None、空集合或长度 0
默认后台任务会周期性清理真正落盘的过期数据

遍历与扫描

遍历 Map

use kv_storage::Map;

let mut map = db.map("profile", None).await?;
let mut iter = map.iter::<String>().await?;

while let Some(item) = iter.next().await {
    let (key, value) = item?;
    println!("{} = {}", String::from_utf8_lossy(&key), value);
}

遍历 List

use kv_storage::List;

let mut list = db.list("logs", None).await?;
let mut iter = list.iter::<String>().await?;

while let Some(item) = iter.next().await {
    println!("{:?}", item?);
}

遍历所有 Map / List

let mut db = db.clone();
let mut map_iter = db.map_iter().await?;
while let Some(map) = map_iter.next().await {
    let map = map?;
    println!("map = {}", String::from_utf8_lossy(map.name()));
}

let mut list_iter = db.list_iter().await?;
while let Some(list) = list_iter.next().await {
    let list = list?;
    println!("list = {}", String::from_utf8_lossy(list.name()));
}

模式扫描

let mut db = db.clone();
let mut iter = db.scan("foo/*").await?;

while let Some(item) = iter.next().await {
    println!("key = {}", String::from_utf8_lossy(&item?));
}

支持的模式字符：

*：匹配任意长度字符
?：匹配单个字符
\* / \?：转义后的字面量

API 概览

`StorageDB`

insert / get / remove
batch_insert / batch_remove
contains_key
counter_incr / counter_decr / counter_get / counter_set
map / map_remove / map_iter
list / list_remove / list_iter
scan
db_size
info
expire / expire_at / ttl（需 ttl 特性）
len（需 len 特性）

`Map`

insert / get / remove
contains_key
clear / is_empty
remove_and_fetch
remove_with_prefix
batch_insert / batch_remove
iter / key_iter / prefix_iter
expire / expire_at / ttl（需 ttl 特性）
len（需 map_len 特性）

`List`

push / pushs / push_limit
pop
all / get_index
len / is_empty / clear
iter
expire / expire_at / ttl（需 ttl 特性）

适用场景

轻量级本地持久化缓存
单机服务内嵌存储
任务队列、事件列表、最近记录列表
会话数据、配置项、临时状态存储
需要 TTL 和计数器能力，但不想引入独立 Redis 服务的场景

当前实现说明

当前公开入口为 sled 后端
对外接口是异步的，但底层依赖 sled 的本地嵌入式能力
数据编码主要通过 bincode 完成
默认测试中已经验证大批量写入、TTL 清理、前缀遍历、通配扫描等能力

开发与测试

运行测试：

cargo test

格式检查与静态检查可按需执行：

cargo fmt
cargo clippy --all-features --all-targets

License

MIT

kv-storage 0.1.1