secra-memory 0.1.1

/// Cache trait 定义
use async_trait::async_trait;
use serde::de::DeserializeOwned;
use serde::Serialize;
use std::time::Duration;

use crate::CacheError;

/// 缓存接口 trait
///
/// 所有缓存实现（内存、Redis 等）都需要实现此 trait
#[async_trait]
pub trait Cache: Send + Sync {
    /// 获取缓存值
    ///
    /// # Arguments
    /// * `key` - 缓存键
    ///
    /// # Returns
    /// * `Result<Option<T>, CacheError>` - 缓存值，None 表示不存在
    async fn get<T>(&self, key: &str) -> Result<Option<T>, CacheError>
    where
        T: DeserializeOwned;

    /// 设置缓存值
    ///
    /// # Arguments
    /// * `key` - 缓存键
    /// * `value` - 缓存值
    /// * `ttl` - 过期时间（可选）
    ///
    /// # Returns
    /// * `Result<(), CacheError>` - 操作结果
    async fn set<T>(&self, key: &str, value: &T, ttl: Option<Duration>) -> Result<(), CacheError>
    where
        T: Serialize + Sync;

    /// 删除缓存值
    ///
    /// # Arguments
    /// * `key` - 缓存键
    ///
    /// # Returns
    /// * `Result<bool, CacheError>` - 是否成功删除（true 表示存在并删除，false 表示不存在）
    async fn delete(&self, key: &str) -> Result<bool, CacheError>;

    /// 检查缓存键是否存在
    ///
    /// # Arguments
    /// * `key` - 缓存键
    ///
    /// # Returns
    /// * `Result<bool, CacheError>` - 是否存在
    async fn exists(&self, key: &str) -> Result<bool, CacheError>;

    /// 设置过期时间
    ///
    /// # Arguments
    /// * `key` - 缓存键
    /// * `ttl` - 过期时间
    ///
    /// # Returns
    /// * `Result<bool, CacheError>` - 是否成功设置（true 表示存在并设置，false 表示不存在）
    async fn expire(&self, key: &str, ttl: Duration) -> Result<bool, CacheError>;

    /// 获取剩余过期时间
    ///
    /// # Arguments
    /// * `key` - 缓存键
    ///
    /// # Returns
    /// * `Result<Option<Duration>, CacheError>` - 剩余过期时间，None 表示不存在或永不过期
    async fn ttl(&self, key: &str) -> Result<Option<Duration>, CacheError>;

    /// 清空所有缓存
    ///
    /// # Returns
    /// * `Result<u64, CacheError>` - 删除的键数量
    async fn clear(&self) -> Result<u64, CacheError>;

    /// 清空指定模块的缓存
    ///
    /// # Arguments
    /// * `module` - 模块标识
    ///
    /// # Returns
    /// * `Result<u64, CacheError>` - 删除的键数量
    async fn clear_module(&self, module: &str) -> Result<u64, CacheError>;
}