Struct L2Cache 

pub struct L2Cache { /* private fields */ }

L2 二级缓存 — 跨 Session 共享

线程安全：内部使用 RwLock，可在多线程环境下共享。

示例

use sz_orm_core::l2_cache::{L2Cache, CacheKey};
use sz_orm_core::Value;
use std::time::Duration;

let cache = L2Cache::new();

// 缓存单行
let key = CacheKey::by_pk("users", 1);
cache.put(&key, Value::String("Alice".to_string()), None);

// 读取
assert!(cache.get(&key).is_some());

// 表级失效
cache.invalidate_table("users");
assert!(cache.get(&key).is_none());

Implementations

impl L2Cache

pub fn new() -> Self

创建 L2 缓存（默认容量 10000，无 TTL）

pub fn with_default_ttl(self, ttl: Duration) -> Self

设置默认 TTL

pub fn with_max_size(self, max_size: usize) -> Self

设置最大容量

pub fn with_invalidation_bus(self, bus: Arc<dyn InvalidationBus>) -> Self

设置缓存失效总线（用于跨实例失效通知）

pub fn put(&self, key: &CacheKey, value: Value, ttl: Option<Duration>)

存入缓存项

TTL 语义

• ttl = Some(d)：使用 d 作为过期时间
• ttl = None：使用 default_ttl（若未设置则永不过期）
• 要显式表示“永不失效“，请传 Some(Duration::MAX)

pub fn get(&self, key: &CacheKey) -> Option<Value>

读取缓存项（不存在或已过期返回 None）

命中时会更新 LRU 访问顺序（移到尾部）。

pub fn invalidate(&self, key: &CacheKey)

失效单个缓存项

pub fn invalidate_table(&self, table: &str)

失效整张表的所有缓存项

仅统计实际从缓存中删除的 key 数量，避免 evictions 偏大。 若设置了失效总线，会同时发布 InvalidateTable 消息通知其他实例。

pub fn clear(&self)

清空所有缓存

pub fn size(&self) -> usize

获取当前缓存项数量

pub fn stats(&self) -> L2CacheStats

获取统计信息

pub fn reset_stats(&self)

重置统计信息（含全局和按表分桶）

pub fn table_stats(&self, table: &str) -> Option<PerTableStats>

获取指定表的命中率统计

pub fn all_table_stats(&self) -> HashMap<String, PerTableStats>

获取所有表的命中率统计快照

pub fn contains(&self, key: &CacheKey) -> bool

检查缓存项是否存在（不更新统计与 LRU 顺序）

pub fn evict_expired(&self) -> usize

手动清理所有过期项

pub fn update_ttl(&self, key: &CacheKey, ttl: Duration) -> bool

更新缓存项的 TTL（若 key 不存在返回 false）

用于 Cache trait 的 expire 方法实现。

pub fn remaining_ttl(&self, key: &CacheKey) -> Option<Option<Duration>>

获取缓存项的剩余 TTL

返回值：

• None：key 不存在或已过期
• Some(None)：key 存在但无 TTL（永不过期）
• Some(Some(d))：key 存在且剩余 TTL 为 d

用于 Cache trait 的 ttl 方法实现。

Trait Implementations

impl Cache for L2Cache

为 L2Cache 实现 Cache trait

通过 CacheKey::by_pk("__cache__", key) 将字符串 key 映射到 L2Cache 的 CacheKey 体系， 所有通过 Cache trait 写入的缓存项归入 __cache__ 表，与业务缓存项隔离。

值以 Value::Bytes(Vec<u8>) 存储；若通过 Cache::get 读取到的 Value 非 Bytes 类型 （如直接通过 L2Cache::put 写入的其他类型），则回退为 JSON 序列化。

fn get(&self, key: &str) -> Result<Option<Vec<u8>>, CacheError>

fn set( &self, key: &str, value: Vec<u8>, ttl: Option<Duration>, ) -> Result<(), CacheError>

fn delete(&self, key: &str) -> Result<(), CacheError>

fn clear(&self) -> Result<(), CacheError>

fn exists(&self, key: &str) -> Result<bool, CacheError>

fn expire(&self, key: &str, ttl: Duration) -> Result<(), CacheError>

fn ttl(&self, key: &str) -> Result<Option<Duration>, CacheError>

impl Default for L2Cache

fn default() -> Self

Returns the “default value” for a type.