Struct PluginCache 

pub struct PluginCache { /* private fields */ }

插件缓存实例

每个插件拥有一个独立的 PluginCache 实例，所有操作自动添加命名空间前缀

Trait Implementations

impl Cache for PluginCache

fn get<'life0, 'life1, 'async_trait, T>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<T>, CacheError>> + Send + 'async_trait>>

where T: DeserializeOwned + 'async_trait, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

获取缓存值

根据业务 Key 获取缓存中的值，自动添加命名空间前缀。 如果 Key 不存在或已过期，返回 None。

Arguments

• key - 业务 Key（不包含命名空间前缀）

Type Parameters

• T - 返回值的类型，必须实现 DeserializeOwned trait

Returns

• Ok(Some(T)) - 成功获取到缓存值
• Ok(None) - Key 不存在或已过期
• Err(CacheError) - 操作失败（如 Key 格式错误、权限不足、反序列化失败等）

Errors

• CacheError::InvalidKey - Key 格式验证失败
• CacheError::PermissionDenied - Key 不属于当前插件
• CacheError::OperationFailed - Redis 操作失败
• CacheError::DeserializationFailed - JSON 反序列化失败

Example

let value: Option<String> = cache.get("user:123").await?;
if let Some(v) = value {
    println!("缓存值: {}", v);
}

fn set<'life0, 'life1, 'life2, 'async_trait, T>( &'life0 self, key: &'life1 str, value: &'life2 T, ttl: Option<Duration>, ) -> Pin<Box<dyn Future<Output = Result<(), CacheError>> + Send + 'async_trait>>

where T: Serialize + Sync + 'async_trait, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

设置缓存值

将值存储到缓存中，自动添加命名空间前缀。 如果提供了 TTL，则设置过期时间；否则使用默认 TTL。 操作完成后会自动将 Key 添加到插件的索引中。

Arguments

• key - 业务 Key（不包含命名空间前缀）
• value - 要缓存的值，必须实现 Serialize 和 Sync trait
• ttl - 可选的过期时间，如果为 None 则使用默认 TTL

Type Parameters

• T - 值的类型，必须实现 Serialize 和 Sync trait

Returns

• Ok(()) - 成功设置缓存
• Err(CacheError) - 操作失败（如 Key 格式错误、权限不足、序列化失败等）

Errors

• CacheError::InvalidKey - Key 格式验证失败
• CacheError::PermissionDenied - Key 不属于当前插件
• CacheError::OperationFailed - Redis 操作失败
• CacheError::SerializationFailed - JSON 序列化失败

性能说明

• 索引更新是异步非阻塞的，不会影响主操作的性能
• 序列化使用 serde_json::to_string，会自动优化内存分配

Example

cache.set("user:123", &"John Doe", Some(Duration::from_secs(3600))).await?;

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, CacheError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

删除缓存值

从缓存中删除指定的 Key，如果 Key 存在则删除并返回 true， 如果 Key 不存在则返回 false。 删除成功后会自动从插件的索引中移除该 Key。

Arguments

• key - 业务 Key（不包含命名空间前缀）

Returns

• Ok(true) - Key 存在且已成功删除
• Ok(false) - Key 不存在
• Err(CacheError) - 操作失败（如 Key 格式错误、权限不足等）

Errors

• CacheError::InvalidKey - Key 格式验证失败
• CacheError::PermissionDenied - Key 不属于当前插件
• CacheError::OperationFailed - Redis 操作失败

Example

let deleted = cache.delete("user:123").await?;
if deleted {
    println!("缓存已删除");
}

fn exists<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, CacheError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

检查 Key 是否存在

检查指定的 Key 是否存在于缓存中，无论是否已过期。

Arguments

• key - 业务 Key（不包含命名空间前缀）

Returns

• Ok(true) - Key 存在
• Ok(false) - Key 不存在
• Err(CacheError) - 操作失败（如 Key 格式错误、权限不足等）

Errors

• CacheError::InvalidKey - Key 格式验证失败
• CacheError::PermissionDenied - Key 不属于当前插件
• CacheError::OperationFailed - Redis 操作失败

Note

此方法只检查 Key 是否存在，不检查是否已过期。 如果需要检查 Key 是否存在且未过期，建议使用 get 方法。

Example

if cache.exists("user:123").await? {
    println!("Key 存在");
}

fn expire<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ttl: Duration, ) -> Pin<Box<dyn Future<Output = Result<bool, CacheError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

设置 Key 的过期时间

为已存在的 Key 设置新的过期时间。如果 Key 不存在，返回 false。

Arguments

• key - 业务 Key（不包含命名空间前缀）
• ttl - 新的过期时间

Returns

• Ok(true) - Key 存在且已成功设置过期时间
• Ok(false) - Key 不存在
• Err(CacheError) - 操作失败（如 Key 格式错误、权限不足等）

Errors

• CacheError::InvalidKey - Key 格式验证失败
• CacheError::PermissionDenied - Key 不属于当前插件
• CacheError::OperationFailed - Redis 操作失败

Example

let success = cache.expire("user:123", Duration::from_secs(7200)).await?;
if success {
    println!("过期时间已更新");
}

fn ttl<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Duration>, CacheError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

获取 Key 的剩余过期时间

返回 Key 的剩余过期时间。如果 Key 不存在、已过期或永不过期，返回 None。

Arguments

• key - 业务 Key（不包含命名空间前缀）

Returns

• Ok(Some(Duration)) - Key 存在且有过期时间，返回剩余时间
• Ok(None) - Key 不存在、已过期或永不过期
• Err(CacheError) - 操作失败（如 Key 格式错误、权限不足等）

Errors

• CacheError::InvalidKey - Key 格式验证失败
• CacheError::PermissionDenied - Key 不属于当前插件
• CacheError::OperationFailed - Redis 操作失败

Redis TTL 返回值说明

• -2 - Key 不存在，返回 None
• -1 - Key 存在但永不过期，返回 None
• > 0 - Key 存在且有过期时间，返回剩余秒数

Example

if let Some(remaining) = cache.ttl("user:123").await? {
    println!("剩余时间: {:?}", remaining);
} else {
    println!("Key 不存在或永不过期");
}

fn clear<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, CacheError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

清空当前插件的所有缓存

删除当前插件的所有缓存 Key，包括所有模块的数据。 此操作会清空插件的索引并删除所有相关的缓存数据。

Returns

• Ok(u64) - 成功删除的 Key 数量
• Err(CacheError) - 操作失败

Errors

• CacheError::OperationFailed - Redis 操作失败

Warning

此操作不可逆，会删除当前插件的所有缓存数据，请谨慎使用。

Example

let deleted_count = cache.clear().await?;
println!("已删除 {} 个缓存项", deleted_count);

fn clear_module<'life0, 'life1, 'async_trait>( &'life0 self, module: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<u64, CacheError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

清空当前插件的指定模块缓存

删除当前插件中指定模块的所有缓存 Key。 模块名称通常作为 Key 的前缀部分，用于逻辑分组。

Arguments

• module - 模块名称，用于标识要清理的模块

Returns

• Ok(u64) - 成功删除的 Key 数量
• Err(CacheError) - 操作失败

Errors

• CacheError::OperationFailed - Redis 操作失败

Note

模块名称应该与 Key 的命名规范一致，通常作为 Key 的前缀使用。 例如：如果 Key 格式为 module:user:123，则模块名称为 module。

Example

let deleted_count = cache.clear_module("user").await?;
println!("已删除 {} 个用户模块缓存项", deleted_count);