secra_cache/
traits.rs

1/// Cache Trait 定义
2use async_trait::async_trait;
3use serde::Serialize;
4use serde::de::DeserializeOwned;
5use std::time::Duration;
6
7use super::error::CacheError;
8
9/// 缓存操作 Trait
10///
11/// 插件通过此 Trait 进行缓存操作，所有操作都自动添加命名空间前缀
12#[async_trait]
13pub trait Cache: Send + Sync {
14    /// 获取缓存值
15    ///
16    /// # Arguments
17    /// * `key` - 业务 Key（不包含命名空间）
18    ///
19    /// # Returns
20    /// * `Result<Option<T>, CacheError>` - 缓存值，如果不存在返回 None
21    async fn get<T>(&self, key: &str) -> Result<Option<T>, CacheError>
22    where
23        T: DeserializeOwned;
24
25    /// 设置缓存值
26    ///
27    /// # Arguments
28    /// * `key` - 业务 Key（不包含命名空间）
29    /// * `value` - 要缓存的值
30    /// * `ttl` - 过期时间（可选），None 表示使用默认 TTL
31    ///
32    /// # Returns
33    /// * `Result<(), CacheError>` - 操作结果
34    async fn set<T>(&self, key: &str, value: &T, ttl: Option<Duration>) -> Result<(), CacheError>
35    where
36        T: Serialize + Sync;
37
38    /// 删除缓存值
39    ///
40    /// # Arguments
41    /// * `key` - 业务 Key（不包含命名空间）
42    ///
43    /// # Returns
44    /// * `Result<bool, CacheError>` - 是否删除成功（Key 存在返回 true，不存在返回 false）
45    async fn delete(&self, key: &str) -> Result<bool, CacheError>;
46
47    /// 检查 Key 是否存在
48    ///
49    /// # Arguments
50    /// * `key` - 业务 Key（不包含命名空间）
51    ///
52    /// # Returns
53    /// * `Result<bool, CacheError>` - Key 是否存在
54    async fn exists(&self, key: &str) -> Result<bool, CacheError>;
55
56    /// 延长 Key 的过期时间
57    ///
58    /// # Arguments
59    /// * `key` - 业务 Key
60    /// * `ttl` - 新的过期时间
61    ///
62    /// # Returns
63    /// * `Result<bool, CacheError>` - 是否续期成功（Key 不存在返回 false）
64    async fn expire(&self, key: &str, ttl: Duration) -> Result<bool, CacheError>;
65
66    /// 获取 Key 的剩余过期时间
67    ///
68    /// # Arguments
69    /// * `key` - 业务 Key
70    ///
71    /// # Returns
72    /// * `Result<Option<Duration>, CacheError>` - 剩余时间，None 表示 Key 不存在或永不过期
73    async fn ttl(&self, key: &str) -> Result<Option<Duration>, CacheError>;
74
75    /// 清理当前插件的所有缓存
76    ///
77    /// # Returns
78    /// * `Result<u64, CacheError>` - 删除的 Key 数量
79    async fn clear(&self) -> Result<u64, CacheError>;
80
81    /// 清理当前插件的指定模块缓存
82    ///
83    /// # Arguments
84    /// * `module` - 模块标识（biz），如 `user`、`order`、`config` 等
85    ///
86    /// # Returns
87    /// * `Result<u64, CacheError>` - 删除的 Key 数量
88    ///
89    /// # Example
90    /// ```rust
91    /// # use secra_cache::{Cache, PluginCache};
92    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
93    /// # let cache: PluginCache = todo!();
94    /// // 清空 user 模块的所有缓存
95    /// cache.clear_module("user").await?;
96    ///
97    /// // 清空 order 模块的所有缓存
98    /// cache.clear_module("order").await?;
99    /// # Ok(())
100    /// # }
101    /// ```
102    async fn clear_module(&self, module: &str) -> Result<u64, CacheError>;
103}
secra_cache/traits.rs

secra_cache/
traits.rs
