moka-cache

moka-cache 是一个基于 moka 的轻量级 K-V 缓存工具库。它对 moka::sync::Cache 做了一层简单封装，提供了：

统一的过期时间模型 Expiration
基于 serde + bincode 的泛型对象缓存
可选的缓存移除/过期回调
常用缓存操作，如 insert、get、remove、refresh

这个 crate 适合需要在 Rust 项目中快速缓存字符串、数字、字节数组或结构体数据的场景。

Features

基于 moka::sync::Cache
支持缓存任意实现了 Serialize / DeserializeOwned 的类型
支持多种 TTL：
- Never
- Millis(u64)
- Second(u64)
- Minute(u64)
- Hour(u64)
支持通过回调监听缓存项被移除的原因
提供手动刷新 TTL 的 refresh

Install

cargo add moka-cache

Quick Start

use moka::notification::RemovalCause;
use moka_cache::{Expiration, MokaCache, MokaCacheData};
use std::sync::Arc;

fn on_remove(key: Arc<String>, _value: MokaCacheData, cause: RemovalCause) {
    println!("key={key}, cause={cause:?}");
}

fn main() -> anyhow::Result<()> {
    let cache = MokaCache::new_default(Some(on_remove), 512);

    cache.insert("message", "hello moka", Expiration::Minute(5))?;

    let value = cache.get::<_, String>("message");
    assert_eq!(value, Some((Expiration::Minute(5), "hello moka".to_string())));

    Ok(())
}

Cache Struct Example

use moka_cache::{Expiration, MokaCache};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
struct AppConfig {
    path: String,
    cache_capacity: u32,
}

fn main() -> anyhow::Result<()> {
    let cache = MokaCache::new_default(None, 128);

    let config = AppConfig {
        path: "./data".to_string(),
        cache_capacity: 1024,
    };

    cache.insert("app-config", config.clone(), Expiration::Never)?;

    let value = cache.get::<_, AppConfig>("app-config");
    assert_eq!(value, Some((Expiration::Never, config)));

    Ok(())
}

API Overview

Create Cache

let cache = MokaCache::new_default(None, 512);

第一个参数：可选移除回调
第二个参数：最大容量 max_capacity

Insert Data

cache.insert("key", 123_i32, Expiration::Second(30))?;

Read Data

let value = cache.get::<_, i32>("key");

返回值类型：

Option<(Expiration, V)>

其中：

Expiration 是写入时设置的过期策略
V 是反序列化后的实际值

Remove Data

cache.remove("key");

Check Existence

let exists = cache.contains_key("key");

Get Expiration Policy

let exp = cache.get_exp("key");

Refresh TTL

refresh 会按原来的过期策略重新写入当前 key，从而延长生命周期：

cache.refresh("key")?;

如果 key 不存在，会返回错误；如果过期策略是 Expiration::Never，则不会执行刷新。

About Expiration Cleanup

当前库基于 moka::sync::Cache，并暴露了：

cache.check_exp_interval();

这个方法内部会调用 run_pending_tasks()，适合在后台线程中定期执行，以便更及时地触发过期清理和回调。例如：

use std::{thread, time::Duration};

thread::spawn({
    let cache = cache_handler.clone();
    move || loop {
        thread::sleep(Duration::from_millis(50));
        cache.check_exp_interval();
    }
});

如果你的业务依赖“过期后尽快触发移除回调”，建议显式调度这个方法。

Supported Value Types

只要类型实现了以下 trait，就可以直接缓存：

serde::Serialize
serde::de::DeserializeOwned

例如：

String
bool
i32 / u32 / u64
Vec<u8>
自定义结构体

Public Types

项目当前暴露的核心类型包括：

MokaCache
MokaCacheHandler = Arc<MokaCache>
MokaCacheData = (Expiration, Vec<u8>)
Expiration

Notes

key 类型统一使用字符串语义，接口接收 AsRef<str>
value 会以 bincode 二进制格式写入缓存
读取时如果反序列化失败，会记录错误日志并返回 None
refresh 的实现是“读取旧值后重新插入”，适合 TTL 续期场景

License

MIT

moka-cache 1.1.2