secra_cache/
lib.rs

1mod config;
2/// 缓存模块
3///
4/// 使用 Redis 提供统一的缓存管理功能
5///
6/// ## 功能特性
7///
8/// - **统一治理**：所有缓存操作必须通过 CacheManager，插件不能直接访问 Redis
9/// - **强隔离**：每个插件拥有独立的命名空间，避免 Key 冲突
10/// - **生命周期管理**：插件卸载/升级时自动清理相关缓存
11/// - **极简 API**：插件侧 API 简单易用，隐藏 Redis 细节
12/// - **可扩展性**：支持未来扩展（配额、监控、限流等）
13///
14/// ## Key 格式规范
15///
16/// 所有 Redis Key 必须遵循以下格式：
17/// ```text
18/// {system}:{plugin_id}:{biz}:{key}
19/// ```
20///
21/// 示例：
22/// - `secra:user_plugin:user:123`
23/// - `secra:order_service:order:2024:001`
24///
25/// ## 使用示例
26///
27/// ### 基座系统
28///
29/// ```rust
30/// // 1. 创建 CacheManager
31/// let cache_manager = CacheManager::new_with_defaults(
32///     "redis://localhost:6379",
33/// ).await?;
34///
35/// // 2. 为插件创建 Cache 实例
36/// let plugin_cache = cache_manager.create_plugin_cache("user_plugin".to_string());
37/// ```
38///
39/// ### 插件代码
40///
41/// ```rust
42/// // 1. 设置缓存
43/// #[derive(Serialize, Deserialize)]
44/// struct User { id: u64, name: String }
45///
46/// let user = User { id: 123, name: "Alice".to_string() };
47/// cache.set("user:123", &user, None).await?;
48///
49/// // 2. 获取缓存
50/// let user: Option<User> = cache.get("user:123").await?;
51///
52/// // 3. 删除缓存
53/// cache.delete("user:123").await?;
54///
55/// // 4. 清理所有缓存
56/// cache.clear().await?;
57///
58/// // 5. 按模块清理缓存
59/// cache.clear_module("user").await?; // 清理 user 模块的所有缓存
60/// ```
61///
62/// ## 详细设计文档
63///
64/// 请参考 `docs/cache/` 目录下的设计文档：
65/// - `01-架构设计.md`：整体架构和调用关系
66/// - `02-Key设计规范.md`：Key 命名规范和隔离机制
67/// - `03-核心能力设计.md`：get/set/del/exists、TTL、序列化
68/// - `04-生命周期管理.md`：插件卸载/升级时的缓存清理
69/// - `05-接口设计.md`：Cache trait、CacheManager、使用示例
70/// - `06-进阶能力.md`：批量操作、分布式锁、防穿透/雪崩
71/// - `07-反模式与约束.md`：禁止行为和强制约束
72/// - `08-实现指南.md`：实现步骤和最佳实践
73// 模块定义
74mod error;
75mod manager;
76mod plugin;
77mod traits;
78
79// 公开导出
80pub use config::CacheConfig;
81pub use error::CacheError;
82pub use manager::CacheManager;
83pub use plugin::PluginCache;
84pub use traits::Cache;
secra_cache/lib.rs

secra_cache/
lib.rs
