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/// # use secra_cache::CacheManager;
31/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
32/// // 1. 创建 CacheManager
33/// let cache_manager = CacheManager::new_with_defaults(
34///     "redis://localhost:6379",
35/// ).await?;
36///
37/// // 或者：传入已创建的 Redis 客户端
38/// // let client = rustis::client::Client::connect("redis://localhost:6379").await?;
39/// // let cache_manager = CacheManager::new_with_client_defaults(client).await?;
40///
41/// // 2. 为插件创建 Cache 实例
42/// let plugin_cache = cache_manager.create_plugin_cache("user_plugin".to_string());
43/// # Ok(())
44/// # }
45/// ```
46///
47/// ### 插件代码
48///
49/// ```rust
50/// # use secra_cache::{Cache, PluginCache};
51/// # use serde::{Serialize, Deserialize};
52/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
53/// # let cache: PluginCache = todo!();
54/// // 1. 设置缓存
55/// #[derive(Serialize, Deserialize)]
56/// struct User { id: u64, name: String }
57///
58/// let user = User { id: 123, name: "Alice".to_string() };
59/// cache.set("user:123", &user, None).await?;
60///
61/// // 2. 获取缓存
62/// let user: Option<User> = cache.get("user:123").await?;
63///
64/// // 3. 删除缓存
65/// cache.delete("user:123").await?;
66///
67/// // 4. 清理所有缓存
68/// cache.clear().await?;
69///
70/// // 5. 按模块清理缓存
71/// cache.clear_module("user").await?; // 清理 user 模块的所有缓存
72/// # Ok(())
73/// # }
74/// ```
75///
76/// ## 详细设计文档
77///
78/// 请参考 `docs/cache/` 目录下的设计文档：
79/// - `01-架构设计.md`：整体架构和调用关系
80/// - `02-Key设计规范.md`：Key 命名规范和隔离机制
81/// - `03-核心能力设计.md`：get/set/del/exists、TTL、序列化
82/// - `04-生命周期管理.md`：插件卸载/升级时的缓存清理
83/// - `05-接口设计.md`：Cache trait、CacheManager、使用示例
84/// - `06-进阶能力.md`：批量操作、分布式锁、防穿透/雪崩
85/// - `07-反模式与约束.md`：禁止行为和强制约束
86/// - `08-实现指南.md`：实现步骤和最佳实践
87// 模块定义
88mod error;
89#[cfg(feature = "rustis")]
90mod manager;
91#[cfg(feature = "rustis")]
92mod plugin;
93mod traits;
94
95// 公开导出
96pub use config::CacheConfig;
97pub use error::CacheError;
98#[cfg(feature = "rustis")]
99pub use manager::CacheManager;
100#[cfg(feature = "rustis")]
101pub use plugin::PluginCache;
102pub use traits::Cache;
secra_cache/lib.rs

secra_cache/
lib.rs
