oxcache 0.5.0-rc.5

中文 | English

Rust 多级缓存库：L1 内存 + L2 分布式

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

🚀 多级缓存，纳秒级热路径

#[cached] 宏一行启用，L1/L2 后端经 ChainCache 自由组链：

📋 目录

• ✨ 功能特性
• 🚀 快速开始
• 🎨 特性标志
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

✨ 功能特性

• 分布式锁（lock）：Redis TTL 锁、watchdog 自动续期、可重入获取
• RedLock（red-lock）：多节点多数派锁、INCR fencing token 单调防回退
• 跨实例失效（invalidation）：Redis Pub/Sub 广播失效事件，键空间通知第二通道
• 值级加密（encrypt）：XChaCha20-Poly1305 信封，AAD 绑定键名防换键移植
• 值完整性（integrity）：HMAC-SHA256 标签，校验失败视为 miss 并计数
• 版本化 CAS（versioning）：内存版与 Redis WATCH/MULTI/EXEC 版 compare_and_swap
• 配置驱动（config-confers）：confers 加载容量 / TTL / 熔断参数，ConfigBus watch 热更新
• 自动降级（degradation）：Active / Degraded / HalfOpen 三态状态机，探测成功自动恢复
• 审计事件流（audit）：结构化 hit / miss / set / delete / evict / expired 事件，键脱敏
• 宏高级参数：single_flight 并发 miss 去重、strict 未注册 panic、condition 谓词旁路
• 分层构建器：L1Builder / L2Builder / ChainBuilder 链式组合
• 生命周期集成（kit）：trait-kit AsyncKit 的 OxcacheModule、健康检查、三阶段关闭、后端装饰器
• 错误国际化：基于 ICU4X 的错误消息 i18n 与系统语言自动检测
• 穿透防护配置：null_cache_ttl 空值哨兵 TTL、ttl_jitter TTL 抖动系数

🚀 快速开始

📦 安装

cargo add oxcache            # 默认 minimal：L1 内存缓存
cargo add oxcache --features full   # 全量：L1 + L2 + 宏 + 压缩 + 批量 + Lua + 锁

或在 Cargo.toml 中手动添加：

[dependencies]
oxcache = "0.5.0-rc.4"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
serde = { version = "1", features = ["derive"] }

最低要求：Rust 1.97.1+（edition 2024）。默认 minimal 特性仅启用 L1 内存缓存；使用 L2（Redis / Valkey / Dragonfly / Aerospike）需本地可达的对应服务，Redis 相关测试依赖 Docker（testcontainers 自动拉起容器）。

💡 最小可运行示例

以下示例精简自 examples/src/01_basics/example_basic_operations.rs：

use oxcache::Cache;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct User {
    id: u64,
    name: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 默认 Moka L1 内存后端
    let cache: Cache<String, User> = Cache::builder().build().await?;

    // 写入
    cache
        .set(&"user:1".to_string(), &User { id: 1, name: "Alice".into() })
        .await?;

    // 读取
    if let Some(user) = cache.get(&"user:1".to_string()).await? {
        println!("命中: {}", user.name);
    }

    // 删除
    cache.delete(&"user:1".to_string()).await?;
    assert!(cache.get(&"user:1".to_string()).await?.is_none());
    Ok(())
}

函数级缓存只需一行宏（完整版见 examples/src/01_basics/example_cached_macro.rs）：

use oxcache::macros::cached;

#[cached(service = "user_cache", ttl = 600)]
async fn get_user(id: u64) -> Result<User, String> {
    Ok(User { id, name: format!("User {id}") })   // 首次执行后结果被缓存
}

🧭 核心概念

• Cache<K, V>：统一类型安全入口，Cache::builder() 配置 capacity / ttl / tti / sync_mode
• 可插拔后端：MokaMemoryBackend / DashMapMemoryBackend / RedisBackend / DragonflyBackend / AerospikeBackend 经 .backend_arc(Arc::new(backend)) 注入
• ChainCache：多后端按分数组链，自高向低读穿透，非最高分命中可异步回填更高分链接
• #[cached] 宏：函数级缓存，经 cache.register_for_macro("service") 注册后由宏生成代码查找
• 同步 API：.sync_mode(true) 开启 get_sync / set_sync / get_or_sync 同步路径

🎨 特性标志

层级预设（default = ["minimal"]，仅 L1）：

oxcache = { version = "0.5.0-rc.4", features = ["minimal"] }   # 仅 L1（默认）
oxcache = { version = "0.5.0-rc.4", features = ["core"] }      # L1 + L2 Redis
oxcache = { version = "0.5.0-rc.4", features = ["full"] }      # 全量（不含 bloom / kit 等选择加入特性）

bloom 与 kit 等选择加入特性不在 full 中，需显式启用。

📚 文档

💻 示例

examples/ 目录（workspace 成员 oxcache-examples，已设 publish = false）包含 37 个可运行示例：

# 运行单个示例（在 examples/ 目录下）
cd examples && cargo run --example example_basic_operations

# 列出所有可用示例
cd examples && ls src/*/*.rs

入门（examples/src/01_basics）

进阶（examples/src/02_advanced）

配置（examples/src/03_config）

数据库集成（examples/src/05_database）

特性展示（examples/src/06_features）

标注"需 Redis"的示例需要运行中的 Redis 6.0+ 服务；其余示例使用内存后端，可独立运行。

🔄 同步 API

入门示例 example_sync_api 即同步 API 的完整可运行版本。在 builder 上启用 sync_mode(true) 后，异步 API 之外获得完整同步镜像（无需 .await）：

use oxcache::Cache;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
struct User { id: u64, name: String }

#[tokio::main(flavor = "multi_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cache: Cache<String, User> = Cache::builder().sync_mode(true).build().await?;

    // 同步操作
    cache.set_sync(&"user:1".to_string(), &User { id: 1, name: "Alice".into() })?;
    let cached = cache.get_sync(&"user:1".to_string())?;
    assert_eq!(cached, Some(User { id: 1, name: "Alice".into() }));

    // per-entry TTL
    cache.set_with_ttl_sync(
        &"temp".to_string(),
        &User { id: 2, name: "Temp".into() },
        Some(std::time::Duration::from_secs(60)),
    )?;

    // 单飞 get_or_sync：并发调用共享一次 fallback 执行
    let value = cache.get_or_sync(&"user:42".to_string(), || {
        Ok(User { id: 42, name: "Bob".into() })
    })?;

    // sync 与 async API 在同一 Cache 上共存
    cache.set(&"async_key".to_string(), &User { id: 99, name: "Async".into() }).await?;
    let v = cache.get_sync(&"async_key".to_string())?;
    Ok(())
}

何时使用：阻塞调用点（遗留代码、FFI、同步处理器）；调用方本身是同步的，避免运行时开销。

运行时注意：

• sync_mode(true) 需 multi_thread tokio 运行时；current_thread 运行时上 Moka 的 sync_block_on 会 panic
• 未启用 sync_mode(true) 时调用任何 *_sync 方法返回 Err(OxCacheError::NotSupported)
• sync_mode(true) 不能与 backend_arc(...) 组合，同时设置时 build() 返回 Err(OxCacheError::NotSupported)

#[cached] 宏参数：完整参数表（含默认值与 cache_none）见 API 参考的缓存宏章节；与同步路径相关的参数为 sync（生成同步函数，无需 async 运行时）。

🏗️ 架构

Oxcache 采用「统一接口 + 可插拔后端」的分层设计：应用只面对 Cache<K, V> 一个类型安全入口，读写落到实现 CacheReader / CacheWriter / CacheConnector 三个 trait 的后端上（blanket impl 组合为 CacheBackend）；L1（Moka / DashMap）与 L2（Redis / Valkey / Dragonfly / Aerospike）可单独使用，也可经 ChainCache 按分数组链并按需回填，features 模块以装饰器形态叠加布隆过滤器、分布式锁、加密等能力。分层架构图、模块职责与数据流见架构文档；batch、integrations::kit、i18n、config、traits、testing 等模块按特性门控挂载。

宏执行路径

#[cached] 宏展开后：按服务名查注册表，命中即反序列化返回；未命中执行原函数并将 Ok 结果序列化回写。未注册服务默认静默穿透执行原函数，strict 模式改为 panic。完整时序图与展开代码见架构文档的数据流章节。

链式缓存读取路径

读取自最高分链接起穿透，非最高分链接命中时可异步回填（流程图见架构文档）。单链接失败仅记录警告并继续下一链接，仅当全部链接失败时读取才报错；写入并发下发到所有写入者链接，单链接写入失败被容忍。enable_race_read() 启用后改为并发查询全部链接并返回首个命中。

可靠性要点：

• 单飞去重（get_or / get_or_sync，64 分片降低锁竞争）
• ChainCache 链路容错（单链接故障不阻塞整体读写）
• 可选自动降级（degradation 特性，半开探测自动恢复）
• 健康检查（ChainCache 并发 ping，每链接 5 秒超时）
• 优雅关闭（shutdown；kit 特性映射到三阶段关闭协调）

🌸 布隆过滤器与穿透防护

bloom 特性（需显式启用，不在 full 中）提供负查询过滤。BloomFilterBackend 装饰任意后端：布隆过滤器判定「一定不存在」时直接返回 None，inner 后端完全不被触及。

flowchart TD
    A["backend.get key"] --> B{"布隆过滤器包含 key？"}
    B -->|一定不存在| C["直接返回 None<br/>inner 后端未被触及"]
    B -->|可能存在| D["查询 inner 后端"]
    D --> E["返回结果"]

use oxcache::backend::MokaMemoryBackend;
use oxcache::features::bloom_filter::{BloomFilter, BloomFilterBackend};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 独立 BloomFilter：容量 10_000，误判率 1%
    let bf = BloomFilter::new(10_000, 0.01);
    bf.insert("existing_key");
    assert!(bf.contains("existing_key"));   // 无假阴性
    assert!(!bf.contains("missing_key"));   // 可能有假阳性

    // 装饰器：包装任意 CacheBackend
    let backend = BloomFilterBackend::builder()
        .capacity(10_000)
        .false_positive_rate(0.01)
        .inner(MokaMemoryBackend::new())
        .build()?;

    backend.set("user:1", b"Alice".to_vec(), None).await?;
    assert!(backend.get("user:1").await?.is_some());
    assert!(backend.get("user:999").await?.is_none());   // BF 过滤，inner 未触及
    Ok(())
}

语义：无假阴性；set 同时更新 BF 与 inner，delete 只更新 inner（BF 不支持删除），clear 两者皆清，TTL 原样透传；inner 实现 SyncCacheBackend 时装饰器同样实现。

穿透与击穿防护组合：

⏱️ TTL 行为对照表

所有后端统一遵守 per-entry set(key, value, Some(ttl))。行为汇总：

全局与 per-entry 的关系：builder.ttl(Duration) 设置作用于每个条目的全局 TTL；set(key, value, Some(ttl)) 覆盖该条目；set(key, value, None) 沿用全局 TTL（未设置则永不过期）。

🧪 测试

测试套件按 tests/README.md 组织，场景矩阵见 docs/TEST_SCENARIOS.md。

¹ #[test] / #[tokio::test] 函数 grep 统计，截至 0.5.0-rc.4；合计 1900+（src/ 1335 + tests/ 606）。

常用命令（与 CI 一致）

# CI test 矩阵以 minimal / core / full 三档运行
cargo test --features full --workspace

# 按测试二进制运行
cargo test --features full --lib
cargo test --features full --test integration
cargo test --features full --test e2e

# 窄特性组合检查（CI feature-core / feature-minimal job）
cargo check -p oxcache --no-default-features --features core
cargo check -p oxcache --no-default-features --features minimal

# 跳过需要 Redis 的测试
cargo test --features full -- --skip redis

# 覆盖率（CI 与 pre-push 门禁：行覆盖 >= 80%）
cargo llvm-cov --features full --workspace --fail-under-lines 80

Redis 相关测试经 testcontainers 自动拉起 redis:7-alpine 容器，需要本机 Docker；集成 / E2E 禁用 test double，使用进程内真实实现与混沌式故障注入替身（口径见 docs/TEST_SCENARIOS.md）。

📊 性能

量级参考（L1/L2 吞吐与 P99 延迟，M1 Pro / 16GB RAM / macOS / Redis 7.0 基准环境；性能因硬件、网络条件和数据大小而异）见架构文档的基准测试章节。可复现实测数据（序列化体积、压缩率、热路径基准与复现命令）见性能基线。

要点速览：热路径借用键 API（get_by_str / set_by_str）实测 get -6.7%、set -12.7%；序列化格式切换（serde-bincode / postcard）下 postcard 混合负载传输体积约为 JSON 的 46%。

Criterion 基准代码位于 benches/：modern_api_benchmark、hot_path_benchmark、redis_benchmark、serialization_benchmark、dashmap_benchmark、dragonfly_benchmark，运行方式如 cargo bench --bench hot_path_benchmark。

🔒 安全

Oxcache 在库层面内建多层防御，完整安全设计、威胁模型与安全修复记录见 安全文档。

漏洞报告：请勿通过公开 Issue 报告安全漏洞。请使用 GitHub Security Advisories 私密披露通道提交（48 小时内确认，7 天内给出初步评估，报告者可在修复发布前预览验证补丁）。

安全 API（公共验证函数）：

use oxcache::{validate_lua_script, validate_redis_key, validate_scan_pattern};

validate_redis_key("user:123").expect("无效的键");
validate_lua_script("return redis.call('GET', KEYS[1])", 1).expect("无效的脚本");
validate_scan_pattern("user:*").expect("无效的模式");

🗺️ 开发路线图

🤝 参与贡献

欢迎提交 Pull Request 和 Issue！参与开发请先阅读 贡献指南。

• 工具链：rust-toolchain.toml 固定 1.97.1（edition 2024）
• 本地门禁：pre-commit / lefthook hooks 覆盖 cargo fmt --check、cargo clippy --all-targets --all-features -- -D warnings、cargo deny check、私钥与密钥扫描；pre-push 追加 cargo audit 与行覆盖 ≥ 80% 门禁
• 提交信息：conventional commits（feat / fix / refactor / docs 等，commit-msg hook 校验）
• TDD 工作流：定接口 → 写测试（red）→ 写实现（green）→ 提交 → 影响分析

📋 更新日志

完整版本历史见 CHANGELOG.md。最近要点：

• 0.5.0-rc.4（2026-09-10）：#[cached] 宏高级参数（single_flight / strict / condition）；telemetry / encrypt / integrity / serde-bincode / postcard / config-confers / degradation / audit / versioning / red-lock / invalidation 特性落地；热路径借用键 API（get -6.7%、set -12.7%）；移除空壳 cli 特性
• 0.5.0-rc.3（2026-09-08）：熔断器状态转换竞态修复；Lua 注入校验与 Redis 密码脱敏加固；CI 供应链加固（58 处第三方 Action 引用 SHA 固定）
• 0.4.3（2026-08-06）：kit 特性扩展（构建观察者、CacheBackend 关闭映射三阶段协调、后端装饰器注册）

📄 许可证

本项目基于 MIT + Commons Clause 许可证发布，商业使用需单独授权。详见 LICENSE。

🙏 致谢

Oxcache 构建在众多优秀的开源项目之上：

• Moka 与 DashMap ，L1 内存缓存后端
• redis-rs ，Redis / Valkey / Dragonfly / Sentinel / Cluster 客户端
• aerospike-client-rust ，Aerospike 后端
• Tokio 与 Serde ，异步运行时与序列化生态
• trait-kit ，AsyncKit 集成（生命周期 / 健康检查 / 关闭协调）
• testcontainers-rs 与 Criterion ，集成测试与基准测试基础设施

📞 联系与支持

• Issue 反馈：GitHub Issues（提供 Bug 报告 / 功能建议 / 问题咨询三类模板）
• 安全漏洞：请勿通过公开 Issue 报告安全漏洞，参见 安全文档 中的漏洞报告流程
• 维护者：Kirky.X

⭐ Star 历史

💝 支持本项目

如果这个项目对你有帮助，请考虑给它一个 ⭐️！

Made with love by Kirky.X