Skip to main content

wordval_cache/
lib.rs

1//! # wordval-cache
2//!
3//! Wordval 缓存抽象:本地内存缓存 + Redis 缓存。
4//!
5//! ## 后端选择
6//!
7//! 通过配置 `cache.type` 切换:
8//! - `local` — 内存缓存(默认)
9//! - `redis` — Redis 缓存(需配置 `redis.url`,也可用 `REDIS_URL` 环境变量覆盖)
10//!
11//! ## 作为插件使用
12//!
13//! ```ignore
14//! use wordval_cache::CachePlugin;
15//!
16//! let mgr = PluginManager::new()
17//!     .add(CachePlugin::new(&config.cache, &config.redis));
18//! ```
19//!
20//! ## 直接使用
21//!
22//! ```ignore
23//! use wordval_cache::{create_cache, Cache};
24//!
25//! let cache = create_cache(&config.cache, &config.redis).await?;
26//! cache.set("key", &"value").await?;
27//! let val: Option<String> = cache.get("key").await?;
28//! ```
29
30pub mod plugin;
31
32pub use plugin::CachePlugin;
33
34use async_trait::async_trait;
35use dashmap::{DashMap, Entry};
36#[cfg(feature = "redis")]
37use redis::aio::ConnectionManager;
38use serde::{de::DeserializeOwned, Serialize};
39use std::collections::HashSet;
40use std::hash::{BuildHasher, Hasher};
41use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
42use std::sync::{Arc, Weak};
43use std::time::{Duration, Instant};
44pub use wordval_core::{Error, Result};
45
46// ──── 缓存 trait ────────────────────────────────────
47
48/// 统一缓存接口(本地/Redis 实现同一 trait)
49///
50/// 注意:方法带泛型参数,本 trait 不满足 object safety,无法以
51/// `dyn Cache` 形式分发;请使用具体实现([`LocalCache`]/[`RedisCache`])
52/// 或 [`SharedCache`] 枚举。
53///
54/// # 示例
55///
56/// ```ignore
57/// let cache = SharedCache::Local(LocalCache::new(1024, 0));
58/// cache.set("key", &"value".to_string()).await?;
59/// let val: Option<String> = cache.get("key").await?;
60/// ```
61#[async_trait]
62pub trait Cache: Send + Sync {
63    /// 读取缓存值,返回 `Ok(None)` 表示 key 不存在或已过期
64    async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>>;
65
66    /// 设置缓存(永不过期,与 Redis `SET` 语义一致),值通过 serde_json 序列化
67    ///
68    /// 本地与 Redis 两个后端行为一致:写入的 key 均不带 TTL。需要过期时间
69    /// 请使用 [`Cache::set_ex`]。
70    async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()>;
71
72    /// 设置缓存(指定过期秒数),到期后自动不可见
73    ///
74    /// `ttl_secs == 0` 返回错误(对齐 Redis `SETEX` 的 invalid expire time)
75    async fn set_ex<T: Serialize + Send + Sync>(
76        &self,
77        key: &str,
78        value: &T,
79        ttl_secs: u64,
80    ) -> Result<()>;
81
82    /// 删除单个 key(不存在不报错)
83    async fn del(&self, key: &str) -> Result<()>;
84
85    /// 检查 key 是否存在且未过期
86    async fn exists(&self, key: &str) -> Result<bool>;
87
88    /// 计数器递增(key 不存在则从 0 开始),返回递增后的值。
89    ///
90    /// 对齐 Redis INCR 语义:存量值不是整数时返回错误,i64 溢出返回错误。
91    async fn incr(&self, key: &str, delta: i64) -> Result<i64>;
92
93    /// 获取匹配模式(glob:`*`/`?`)的所有 key
94    ///
95    /// 注意:本地后端只支持 `*`/`?` 通配符;Redis 后端走 `SCAN MATCH`,额外
96    /// 支持 `[...]` 字符类。跨后端可移植的公共子集是 `*`/`?`。
97    ///
98    /// ⚠️ 全键扫描:本地后端 O(全部 key) 线性遍历(与 Redis `KEYS` 同病),
99    /// 大缓存上可能造成毫秒级停顿;热路径请按精确 key 读写,
100    /// 本方法仅限运维/管理类低频场景。
101    async fn keys(&self, pattern: &str) -> Result<Vec<String>>;
102
103    /// 原子设置:仅当 key 不存在时设置,返回 true 表示设置成功,false 表示 key 已存在
104    ///
105    /// `ttl_secs == 0` 返回错误(对齐 Redis `SET ... EX` 的 invalid expire time)
106    async fn set_nx<T: Serialize + Send + Sync>(
107        &self,
108        key: &str,
109        value: &T,
110        ttl_secs: u64,
111    ) -> Result<bool>;
112
113    /// 删除匹配模式的所有 key,返回删除数
114    ///
115    /// ⚠️ 全键扫描:本地后端 O(全部 key) 线性遍历,大缓存上可能造成
116    /// 毫秒级停顿;仅限运维/管理类低频场景,热路径请按精确 key 删除。
117    async fn delete_pattern(&self, pattern: &str) -> Result<u64>;
118
119    // ──── Set 集合操作 ────────────────────────────────────
120
121    /// 向集合添加一个或多个成员,返回实际新增的数量。
122    ///
123    /// 对齐 Redis SADD 语义:key 持有非集合值时返回错误(不静默清数据)。
124    async fn sadd(&self, key: &str, members: &[String]) -> Result<u64>;
125
126    /// 从集合移除一个或多个成员,返回实际移除的数量;集合变空时删除 key(对齐 Redis)。
127    async fn srem(&self, key: &str, members: &[String]) -> Result<u64>;
128
129    /// 获取集合的所有成员;key 持有非集合值时返回错误(对齐 Redis WRONGTYPE)。
130    async fn smembers(&self, key: &str) -> Result<Vec<String>>;
131
132    /// 检查成员是否在集合中
133    async fn sismember(&self, key: &str, member: &str) -> Result<bool> {
134        Ok(self.smembers(key).await?.iter().any(|m| m == member))
135    }
136
137    // ──── TTL 操作 ────────────────────────────────────────
138
139    /// 刷新 key 的过期时间(秒);key 不存在或已过期返回 false(对齐 Redis)
140    ///
141    /// `ttl_secs == 0` 返回错误(对齐 Redis `EXPIRE` 的 invalid expire time)
142    async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool>;
143
144    /// 查询 key 剩余过期秒数(向上取整)。
145    ///
146    /// 返回 `None` 表示 key 不存在、已过期或未设置过期时间(三者不做区分,
147    /// 可先用 [`Cache::exists`] 区分是否存在)。默认实现恒返回 `None`(未覆盖
148    /// 的第三方实现不支持 TTL 查询);内置两个后端均已覆盖。
149    async fn ttl(&self, key: &str) -> Result<Option<u64>> {
150        let _ = key;
151        Ok(None)
152    }
153
154    /// 组合操作:添加集合成员并为 key 设置 TTL。
155    ///
156    /// 默认实现按顺序执行 SADD + EXPIRE(两步间进程崩溃会留下无 TTL 的
157    /// key);Redis 实现覆盖为 `pipeline` 原子发送,消除该窗口。需要
158    /// "集合成员随 TTL 自动自愈"语义(如在线状态登记)时应使用本方法。
159    /// `members` 为空时退化为仅刷新 TTL(与默认实现的两步行为一致)。
160    async fn sadd_with_ttl(&self, key: &str, members: &[String], ttl_secs: u64) -> Result<()> {
161        // 写入前校验 TTL:否则 sadd 成功后 expire 才报错,留下无 TTL 的半成品 key
162        check_ttl_secs(ttl_secs)?;
163        self.sadd(key, members).await?;
164        self.expire(key, ttl_secs).await?;
165        Ok(())
166    }
167
168    /// 获取原始字节数据(默认经 `serde_json::Value` 中转;实现可覆盖为字节直通)
169    async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
170        match self.get::<serde_json::Value>(key).await? {
171            Some(v) => Ok(Some(
172                serde_json::to_vec(&v).map_err(|e| Error::Msg(e.to_string()))?,
173            )),
174            None => Ok(None),
175        }
176    }
177
178    /// 设置原始字节数据(必须是合法 JSON;默认经 `serde_json::Value` 中转)
179    ///
180    /// 与 [`Cache::set`] 语义一致:写入的 key 永不过期
181    async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
182        let v: serde_json::Value =
183            serde_json::from_slice(value).map_err(|e| Error::Msg(e.to_string()))?;
184        self.set(key, &v).await
185    }
186
187    /// 设置原始字节数据(带 TTL;默认经 `serde_json::Value` 中转)
188    ///
189    /// `ttl_secs == 0` 返回错误(对齐 Redis `SETEX` 的 invalid expire time)
190    async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
191        let v: serde_json::Value =
192            serde_json::from_slice(value).map_err(|e| Error::Msg(e.to_string()))?;
193        self.set_ex(key, &v, ttl_secs).await
194    }
195
196    /// 缓存统计信息(内存缓存支持,Redis 返回全零)
197    fn stats(&self) -> CacheStats {
198        CacheStats::default()
199    }
200}
201
202/// 便捷函数:获取原始字节数据
203pub async fn get_raw(cache: &SharedCache, key: &str) -> Result<Option<Vec<u8>>> {
204    Cache::get_raw(cache, key).await
205}
206
207/// 便捷函数:设置原始字节数据
208pub async fn set_raw(cache: &SharedCache, key: &str, value: &[u8]) -> Result<()> {
209    Cache::set_raw(cache, key, value).await
210}
211
212/// 校验字节是合法 JSON(`IgnoredAny` 零分配解析,只做合法性检查)
213fn validate_json(value: &[u8]) -> Result<()> {
214    serde_json::from_slice::<serde::de::IgnoredAny>(value)
215        .map(|_| ())
216        .map_err(|e| Error::Msg(e.to_string()))
217}
218
219/// 类型不匹配错误(对齐 Redis WRONGTYPE 语义,杜绝静默清空数据)
220fn wrong_type_err() -> Error {
221    Error::Msg("WRONGTYPE Operation against a key holding the wrong kind of value".into())
222}
223
224/// TTL 合法性校验:0 视为无效过期时间(对齐 Redis "invalid expire time");
225/// 超过 `i64::MAX` 同样拒绝——Redis 秒级 TTL 上限即 i64,且 `as i64` 收窄
226/// 会静默变负数,而 Redis 对负 TTL 的行为是立即删除 key(静默数据丢失)
227fn check_ttl_secs(ttl_secs: u64) -> Result<()> {
228    if ttl_secs == 0 {
229        Err(Error::Msg(
230            "ERR invalid expire time: ttl_secs must be greater than 0".into(),
231        ))
232    } else if ttl_secs > i64::MAX as u64 {
233        Err(Error::Msg(
234            "ERR invalid expire time: ttl_secs is out of range".into(),
235        ))
236    } else {
237        Ok(())
238    }
239}
240
241/// 计算 `secs` 秒后的过期时刻;`Instant` 溢出(超大 TTL)视为无效过期时间,
242/// 与 Redis 对超大 expire 报 "value is out of range" 的行为对齐(而非 panic)
243fn expiry_after(secs: u64) -> Result<Instant> {
244    Instant::now()
245        .checked_add(Duration::from_secs(secs))
246        .ok_or_else(|| Error::Msg("ERR invalid expire time: ttl overflow".into()))
247}
248
249/// 脱敏 Redis URL:隐藏 userinfo 中的凭据(`redis://user:pass@host` → `redis://***@host`),
250/// 用于日志输出,避免密码/令牌泄露
251#[cfg(feature = "redis")]
252fn sanitize_redis_url(url: &str) -> String {
253    let Some(scheme_end) = url.find("://") else {
254        return url.to_string();
255    };
256    let rest_start = scheme_end + 3;
257    let rest = &url[rest_start..];
258    let authority_end = rest.find(['/', '?']).unwrap_or(rest.len());
259    let authority = &rest[..authority_end];
260    match authority.rfind('@') {
261        // userinfo 不能包含未转义的 '@',最后一个 '@' 即 userinfo 与 host 的分隔符
262        Some(at) => format!(
263            "{}***{}{}",
264            &url[..rest_start],
265            &authority[at..],
266            &rest[authority_end..]
267        ),
268        None => url.to_string(),
269    }
270}
271
272// ──── 本地缓存条目 ──────────────────────────────────
273
274struct CacheEntry {
275    /// 序列化后的缓存值字节(Arc 共享:命中克隆只是引用计数 +1,不复制数据)
276    bytes: Arc<[u8]>,
277    expires_at: Option<Instant>,
278}
279
280// ──── 本地内存缓存 ─────────────────────────────────
281
282/// 缓存统计指标
283///
284/// 统计口径:`hits`/`misses` 覆盖读路径(`get`/`smembers`/`exists`),按
285/// 数据层面是否命中计数(与后续反序列化成败无关);`incr` 等写路径不参与。
286#[derive(Debug, Clone, Default)]
287pub struct CacheStats {
288    /// 缓存命中次数
289    pub hits: u64,
290    /// 缓存未命中次数
291    pub misses: u64,
292    /// 设置缓存次数
293    pub sets: u64,
294    /// 删除缓存次数
295    pub deletes: u64,
296    /// 淘汰次数
297    pub evictions: u64,
298    /// 过期清理次数
299    pub expired_cleanups: u64,
300}
301
302#[derive(Default)]
303struct AtomicCacheStats {
304    hits: AtomicU64,
305    misses: AtomicU64,
306    sets: AtomicU64,
307    deletes: AtomicU64,
308    evictions: AtomicU64,
309    expired_cleanups: AtomicU64,
310}
311
312/// 本地缓存共享状态(`LocalCache` 的所有克隆共享同一份)
313struct Inner {
314    /// 缓存数据存储(分片并发哈希表,ahash 加速短 key 哈希)
315    data: DashMap<String, CacheEntry, ahash::RandomState>,
316    /// 条目数计数(所有写入路径精确维护),O(1) 容量判断,
317    /// 避免每次 set 都 `DashMap::len()`(需对所有分片加读锁求和)
318    size: AtomicUsize,
319    /// 最大容量(超过后淘汰最早过期的条目)
320    max_capacity: u64,
321    /// 缓存统计信息(原子计数器)
322    stats: AtomicCacheStats,
323    /// 后台清理任务的间隔秒数
324    cleanup_interval_secs: u64,
325    /// 后台清理任务是否已启动(保证幂等,只启动一次)
326    cleanup_started: AtomicBool,
327    /// `get_or_insert_with` 的进程内并发去重表(每 key 一把异步锁),
328    /// 防止缓存击穿:同一 key 的并发未命中只执行一次加载函数
329    inflight: InflightMap,
330}
331
332/// 单飞去重表类型(key → 异步互斥锁)
333type InflightMap = DashMap<String, Arc<tokio::sync::Mutex<()>>, ahash::RandomState>;
334
335/// 单飞锁的 RAII 守卫:Drop 时将该 key 从去重表移除(仅当表内仍是本锁),
336/// 防止表随 key 基数无界增长。
337///
338/// 相比函数式清理,守卫覆盖所有退出路径(`?` 提前返回、任务被取消)。
339/// 不做强计数判定:Drop 时调用方局部 `Arc` 是否已释放取决于生成器字段
340/// 丢弃顺序,计数条件不可靠;`remove_if` 的 `ptr_eq` 条件保证只移除本锁、
341/// 绝不误删同 key 已被重建的新锁条目。移除后仍在等待旧锁的调用者会依次
342/// 醒来执行双检(命中或重试回源),最坏情况仅同 key 多回源一次。
343struct InflightGuard<'a> {
344    map: &'a InflightMap,
345    key: &'a str,
346    lock: Arc<tokio::sync::Mutex<()>>,
347}
348
349impl Drop for InflightGuard<'_> {
350    fn drop(&mut self) {
351        self.map
352            .remove_if(self.key, |_, v| Arc::ptr_eq(v, &self.lock));
353    }
354}
355
356/// 单飞加载公共实现:读/写经 [`Cache`] trait 注入,`inflight` 为调用方的
357/// 去重表(本地与 Redis 后端各持一张),命中直接返回;未命中则按 key 去重——
358/// 同一 key 的并发调用只有一个执行 `load` 回源,其余等待其完成后读缓存。
359async fn single_flight<C, T, F, Fut>(
360    cache: &C,
361    inflight: &InflightMap,
362    key: &str,
363    ttl_secs: u64,
364    load: F,
365) -> Result<T>
366where
367    C: Cache,
368    T: DeserializeOwned + Serialize + Send + Sync,
369    F: FnOnce() -> Fut,
370    Fut: std::future::Future<Output = Result<T>>,
371{
372    // 快路径:命中直接返回
373    if let Some(v) = cache.get::<T>(key).await? {
374        return Ok(v);
375    }
376    // 取/建该 key 的单飞锁(Arc 使并发等待者共享同一把锁)
377    let lock = match inflight.entry(key.to_string()) {
378        Entry::Vacant(e) => {
379            let lock = Arc::new(tokio::sync::Mutex::new(()));
380            e.insert(lock.clone());
381            lock
382        }
383        Entry::Occupied(e) => e.get().clone(),
384    };
385    // RAII 守卫:任何退出路径(含 `?` 与任务取消)都会尝试清理去重表条目;
386    // 声明在 mutex guard 之前,保证退出时先释放单飞锁、后清理表条目
387    let _inflight = InflightGuard {
388        map: inflight,
389        key,
390        lock: Arc::clone(&lock),
391    };
392    let guard = lock.lock().await;
393    // 双检:等待期间持锁者可能已完成加载
394    if let Some(v) = cache.get::<T>(key).await? {
395        return Ok(v);
396    }
397    let value = load().await?;
398    if ttl_secs > 0 {
399        cache.set_ex(key, &value, ttl_secs).await?;
400    } else {
401        cache.set(key, &value).await?;
402    }
403    drop(guard); // 先唤醒等待者,随后 _inflight Drop 清理表条目
404    Ok(value)
405}
406
407#[inline]
408fn inc_size(inner: &Inner) {
409    inner.size.fetch_add(1, Ordering::Relaxed);
410}
411
412/// 计数减 n(saturating,防御性保护:即使出现意外 drift 也不会下溢回绕)
413#[inline]
414fn dec_size(inner: &Inner, n: usize) {
415    let _ = inner
416        .size
417        .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |x| {
418            Some(x.saturating_sub(n))
419        });
420}
421
422/// 仅当条目「仍」过期时才删除(条件删除,避免误删并发写入的新值),返回是否删除
423fn remove_if_expired(inner: &Inner, key: &str, now: Instant) -> bool {
424    if inner
425        .data
426        .remove_if(key, |_, v| v.expires_at.is_some_and(|t| now > t))
427        .is_some()
428    {
429        dec_size(inner, 1);
430        true
431    } else {
432        false
433    }
434}
435
436/// 容量满时的有界采样淘汰窗口:仅评估最多这么多条目并淘汰其中最早过期者。
437/// 全量过期回收由后台清理任务负责。
438const EVICT_SAMPLE: usize = 64;
439
440/// 容量满时淘汰:从缓存中采样若干条目,淘汰其中最早过期者(近似 TTL 淘汰)。
441///
442/// 永不过期(`None`)的条目视作最晚过期,最后才淘汰。淘汰采用有界采样,
443/// 单次评估上限为 `EVICT_SAMPLE` 个条目;采样窗口起点以待写入 key 的哈希
444/// 随机平移(分片内迭代近似插入序,固定头部会系统性偏向淘汰新写入的条目),
445/// 最多额外跳过 `EVICT_SAMPLE - 1` 个条目。
446fn evict_sampled(inner: &Inner, seed_key: &str) {
447    // 以「当前条目数与采样窗口的较小值」为模平移采样窗口起点,既保证小缓存
448    // 全覆盖,又保证大缓存单趟游走有界(≤ offset + EVICT_SAMPLE)
449    let total = inner.size.load(Ordering::Relaxed);
450    if total == 0 {
451        return;
452    }
453    let offset = {
454        let mut h = ahash::RandomState::new().build_hasher();
455        h.write(seed_key.as_bytes());
456        (h.finish() as usize) % total.min(EVICT_SAMPLE)
457    };
458    let mut best_key: Option<String> = None;
459    let mut best_exp: Option<Instant> = None;
460    let mut scanned = 0usize;
461
462    for entry in inner.data.iter().skip(offset) {
463        let exp = entry.expires_at;
464        // 候选更优的条件:尚无候选,或当前条目比已知最早者更早过期;
465        // 永不过期(None)永远不优于已有的带过期时间候选。
466        let better = match (best_exp, exp) {
467            (None, _) => true,
468            (Some(_), None) => false,
469            (Some(b), Some(e)) => e < b,
470        };
471        if better {
472            best_key = Some(entry.key().clone());
473            best_exp = exp;
474        }
475        scanned += 1;
476        if scanned >= EVICT_SAMPLE {
477            break;
478        }
479    }
480
481    if let Some(k) = best_key {
482        if inner.data.remove(&k).is_some() {
483            dec_size(inner, 1);
484            inner.stats.evictions.fetch_add(1, Ordering::Relaxed);
485        }
486    }
487}
488
489/// 新 key 写入前的容量预检:满员时采样淘汰(必须在不持有任何分片锁时调用,
490/// 否则会与淘汰扫描的 iter 死锁)。
491#[inline]
492fn ensure_capacity_for_insert(inner: &Inner, key: &str) {
493    if inner.max_capacity > 0
494        && inner.size.load(Ordering::Relaxed) as u64 >= inner.max_capacity
495        && !inner.data.contains_key(key)
496    {
497        evict_sampled(inner, key);
498    }
499}
500
501/// 惰性过期回收(retain 单趟完成,无中间 Vec 分配)
502fn cleanup_expired_inner(inner: &Inner) -> u64 {
503    let now = Instant::now();
504    let mut removed = 0usize;
505    inner.data.retain(|_, v| {
506        let alive = v.expires_at.map_or(true, |t| now <= t);
507        if !alive {
508            removed += 1;
509        }
510        alive
511    });
512    if removed > 0 {
513        dec_size(inner, removed);
514        inner
515            .stats
516            .expired_cleanups
517            .fetch_add(removed as u64, Ordering::Relaxed);
518    }
519    removed as u64
520}
521
522/// 本地内存缓存(DashMap 分片 + ahash + TTL + 统计 + 后台清理)
523///
524/// 存储使用序列化后的字节(`Arc<[u8]>` 共享,命中零拷贝);容量满时按
525/// 有界采样淘汰**最早过期**的条目(近似 TTL 淘汰)。
526#[derive(Clone)]
527pub struct LocalCache {
528    inner: Arc<Inner>,
529}
530
531impl std::fmt::Debug for LocalCache {
532    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
533        // 只暴露规模信息,不输出条目数据
534        f.debug_struct("LocalCache")
535            .field("len", &self.len())
536            .field("max_capacity", &self.inner.max_capacity)
537            .finish()
538    }
539}
540
541impl LocalCache {
542    /// 创建本地内存缓存
543    ///
544    /// - `max_capacity`: 超过此容量后按最早过期策略淘汰;`0` 表示不限容量
545    /// - `default_ttl_secs`: **已废弃(兼容保留,不再生效)**:`set` 已对齐
546    ///   Redis 契约为永不过期,default TTL 不再自动应用;需要过期请显式
547    ///   [`Cache::set_ex`]。传 0 即可。
548    pub fn new(max_capacity: u64, default_ttl_secs: u64) -> Self {
549        let _ = default_ttl_secs; // 兼容保留参数,不再应用(见方法文档)
550        // 预分配少量容量避免早期 rehash 抖动,上限 1024 防止大 capacity 配置空占内存
551        let prealloc = max_capacity.min(1024) as usize;
552        Self {
553            inner: Arc::new(Inner {
554                data: DashMap::with_capacity_and_hasher(prealloc, ahash::RandomState::new()),
555                size: AtomicUsize::new(0),
556                max_capacity,
557                stats: AtomicCacheStats::default(),
558                cleanup_interval_secs: 60,
559                cleanup_started: AtomicBool::new(false),
560                inflight: InflightMap::with_hasher(ahash::RandomState::new()),
561            }),
562        }
563    }
564
565    pub fn with_cleanup_interval(mut self, interval_secs: u64) -> Self {
566        // 构建期配置:仅当尚未共享(未克隆)时才允许修改
567        match Arc::get_mut(&mut self.inner) {
568            Some(inner) => inner.cleanup_interval_secs = interval_secs,
569            None => tracing::warn!(
570                "with_cleanup_interval 在实例被克隆后调用,本次配置被忽略"
571            ),
572        }
573        self
574    }
575
576    /// 获取缓存统计快照
577    pub fn stats(&self) -> CacheStats {
578        let s = &self.inner.stats;
579        CacheStats {
580            hits: s.hits.load(Ordering::Relaxed),
581            misses: s.misses.load(Ordering::Relaxed),
582            sets: s.sets.load(Ordering::Relaxed),
583            deletes: s.deletes.load(Ordering::Relaxed),
584            evictions: s.evictions.load(Ordering::Relaxed),
585            expired_cleanups: s.expired_cleanups.load(Ordering::Relaxed),
586        }
587    }
588
589    /// 获取当前缓存条目数量(O(1) 原子计数)
590    pub fn len(&self) -> usize {
591        self.inner.size.load(Ordering::Relaxed)
592    }
593
594    /// 缓存是否为空
595    pub fn is_empty(&self) -> bool {
596        self.len() == 0
597    }
598
599    /// 手动清理所有过期条目,返回清理数
600    pub fn cleanup_expired(&self) -> u64 {
601        cleanup_expired_inner(&self.inner)
602    }
603
604    /// 启动后台过期清理任务(每 `interval_secs` 秒执行一次,幂等:多次调用只启动一次)。
605    ///
606    /// 任务持有 `Weak<Inner>`:当所有 `LocalCache` 句柄被释放后,任务在下一轮
607    /// 唤醒时自动退出,不会泄漏。
608    pub fn start_background_cleanup(&self) {
609        if self.inner.cleanup_started.swap(true, Ordering::AcqRel) {
610            return;
611        }
612        let weak: Weak<Inner> = Arc::downgrade(&self.inner);
613        let interval = self.inner.cleanup_interval_secs.max(1);
614
615        tokio::spawn(async move {
616            loop {
617                tokio::time::sleep(Duration::from_secs(interval)).await;
618                let Some(inner) = weak.upgrade() else {
619                    break; // 缓存实例已全部释放,退出任务
620                };
621                let removed = cleanup_expired_inner(&inner);
622                if removed > 0 {
623                    tracing::debug!("缓存后台清理: 移除 {} 个过期条目", removed);
624                }
625            }
626        });
627    }
628
629    /// 读取未过期条目的共享字节;过期条目顺手条件删除(竞态安全)
630    #[inline]
631    fn read_live_bytes(&self, key: &str) -> Option<Arc<[u8]>> {
632        let now = Instant::now();
633        let entry = self.inner.data.get(key)?;
634        if entry.expires_at.is_some_and(|t| now > t) {
635            drop(entry);
636            remove_if_expired(&self.inner, key, now);
637            return None;
638        }
639        Some(Arc::clone(&entry.bytes))
640    }
641
642    /// 写入条目(覆盖语义),处理容量淘汰与计数
643    fn insert_bytes(&self, key: &str, bytes: Arc<[u8]>, expires_at: Option<Instant>) {
644        // 热路径(key 已存在):借用覆写,零分配且无需容量预检(size 不变)
645        if let Some(mut e) = self.inner.data.get_mut(key) {
646            *e.value_mut() = CacheEntry { bytes, expires_at };
647            self.inner.stats.sets.fetch_add(1, Ordering::Relaxed);
648            return;
649        }
650        // 新 key:满员时先淘汰(必须在不持分片锁时调用),再经 entry 插入
651        ensure_capacity_for_insert(&self.inner, key);
652        match self.inner.data.entry(key.to_string()) {
653            Entry::Vacant(e) => {
654                e.insert(CacheEntry { bytes, expires_at });
655                inc_size(&self.inner);
656            }
657            // 并发插入抢先:条目已存在,直接覆写(size 不变)
658            Entry::Occupied(mut e) => {
659                *e.get_mut() = CacheEntry { bytes, expires_at };
660            }
661        }
662        self.inner.stats.sets.fetch_add(1, Ordering::Relaxed);
663    }
664
665    /// 单飞加载(缓存击穿防护):命中直接返回;未命中则按 key 去重——
666    /// 同一 key 的并发调用只有一个执行 `load` 回源,其余等待其完成后读缓存。
667    ///
668    /// - `ttl_secs > 0`:回源结果以 [`Cache::set_ex`] 写入;`ttl_secs == 0`
669    ///   表示永不过期(以 [`Cache::set`] 写入,不走 invalid-expire 校验)
670    /// - `load` 返回 `Err` 时不写入缓存,等待中的调用将依次重试回源
671    /// - 去重范围为单个进程内的缓存实例(克隆共享同一张去重表)
672    pub async fn get_or_insert_with<T, F, Fut>(
673        &self,
674        key: &str,
675        ttl_secs: u64,
676        load: F,
677    ) -> Result<T>
678    where
679        T: DeserializeOwned + Serialize + Send + Sync,
680        F: FnOnce() -> Fut,
681        Fut: std::future::Future<Output = Result<T>>,
682    {
683        // 快路径与去重逻辑统一在 [`single_flight`](本地/Redis 共享实现)
684        single_flight(self, &self.inner.inflight, key, ttl_secs, load).await
685    }
686}
687
688#[async_trait]
689impl Cache for LocalCache {
690    async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>> {
691        let Some(bytes) = self.read_live_bytes(key) else {
692            self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
693            return Ok(None);
694        };
695        self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
696        // 已释放分片锁,在锁外反序列化
697        let val: T =
698            serde_json::from_slice(&bytes).map_err(|e| Error::Msg(e.to_string()))?;
699        Ok(Some(val))
700    }
701
702    async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()> {
703        let bytes = serde_json::to_vec(value).map_err(|e| Error::Msg(e.to_string()))?;
704        // 与 Redis SET 及 trait 契约对齐:set 写入的 key 永不过期
705        // (default_ttl 不再自动应用,需要过期请显式 set_ex)
706        self.insert_bytes(key, Arc::from(bytes), None);
707        Ok(())
708    }
709
710    async fn set_ex<T: Serialize + Send + Sync>(
711        &self,
712        key: &str,
713        value: &T,
714        ttl_secs: u64,
715    ) -> Result<()> {
716        check_ttl_secs(ttl_secs)?;
717        let bytes = serde_json::to_vec(value).map_err(|e| Error::Msg(e.to_string()))?;
718        let expires_at = Some(expiry_after(ttl_secs)?);
719        self.insert_bytes(key, Arc::from(bytes), expires_at);
720        Ok(())
721    }
722
723    async fn set_nx<T: Serialize + Send + Sync>(
724        &self,
725        key: &str,
726        value: &T,
727        ttl_secs: u64,
728    ) -> Result<bool> {
729        check_ttl_secs(ttl_secs)?;
730        let bytes = serde_json::to_vec(value).map_err(|e| Error::Msg(e.to_string()))?;
731        let now = Instant::now();
732        let entry = CacheEntry {
733            bytes: Arc::from(bytes),
734            expires_at: Some(expiry_after(ttl_secs)?),
735        };
736        // 容量预检必须在获取分片写锁之前(写锁内淘汰会 iter → 死锁)
737        ensure_capacity_for_insert(&self.inner, key);
738        // 热路径(key 已存在)先走 get_mut 借用查找,零分配;
739        // 整个「检查-写入」在分片锁内原子完成,保证 NX 语义
740        loop {
741            if let Some(mut e) = self.inner.data.get_mut(key) {
742                if e.value().expires_at.map_or(true, |exp| now <= exp) {
743                    return Ok(false);
744                }
745                *e.value_mut() = entry;
746                return Ok(true);
747            }
748            match self.inner.data.entry(key.to_string()) {
749                Entry::Vacant(e) => {
750                    e.insert(entry);
751                    inc_size(&self.inner);
752                    return Ok(true);
753                }
754                // 并发插入抢先:回到 get_mut 路径按 NX 语义判定
755                Entry::Occupied(_) => continue,
756            }
757        }
758    }
759
760    async fn del(&self, key: &str) -> Result<()> {
761        if self.inner.data.remove(key).is_some() {
762            dec_size(&self.inner, 1);
763            self.inner.stats.deletes.fetch_add(1, Ordering::Relaxed);
764        }
765        Ok(())
766    }
767
768    async fn exists(&self, key: &str) -> Result<bool> {
769        let now = Instant::now();
770        let found = match self.inner.data.get(key) {
771            Some(entry) => {
772                if entry.expires_at.is_some_and(|exp| now > exp) {
773                    // 已过期:条件删除并视为不存在
774                    drop(entry);
775                    remove_if_expired(&self.inner, key, now);
776                    false
777                } else {
778                    true
779                }
780            }
781            None => false,
782        };
783        if found {
784            self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
785        } else {
786            self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
787        }
788        Ok(found)
789    }
790
791    async fn incr(&self, key: &str, delta: i64) -> Result<i64> {
792        let now = Instant::now();
793        ensure_capacity_for_insert(&self.inner, key);
794        // 热路径(key 已存在)先走 get_mut 借用查找,零分配;
795        // 仅 key 缺失时才经 entry 分配 owned key(期间被并发插入则重试借用路径)
796        loop {
797            if let Some(mut e) = self.inner.data.get_mut(key) {
798                // 已过期条目必须视作不存在:从 0 重新计数并清除过期时间,
799                // 否则会读到旧值累加(过期脏读),与 Redis INCR 语义不符。
800                let expired = e.value().expires_at.is_some_and(|t| now > t);
801                let current: i64 = if expired {
802                    0
803                } else {
804                    // incr 写出的值是十进制整数文本(合法 JSON),直接零开销解析;
805                    // 其他类型(字符串/对象等)对齐 Redis 报错而不是静默当 0。
806                    std::str::from_utf8(&e.value().bytes)
807                        .ok()
808                        .and_then(|s| s.parse::<i64>().ok())
809                        .ok_or_else(|| {
810                            Error::Msg("value is not an integer or out of range".into())
811                        })?
812                };
813                let nv = current
814                    .checked_add(delta)
815                    .ok_or_else(|| Error::Msg("increment or decrement would overflow".into()))?;
816                let ent = e.value_mut();
817                // i64 的十进制表示本身是合法 JSON,跳过 serde_json 开销
818                ent.bytes = Arc::from(nv.to_string().into_bytes());
819                if expired {
820                    ent.expires_at = None;
821                }
822                // 未过期:保留原过期时间,计数期间不重置 TTL
823                return Ok(nv);
824            }
825            match self.inner.data.entry(key.to_string()) {
826                Entry::Vacant(e) => {
827                    e.insert(CacheEntry {
828                        bytes: Arc::from(delta.to_string().into_bytes()),
829                        expires_at: None,
830                    });
831                    inc_size(&self.inner);
832                    return Ok(delta);
833                }
834                // 并发插入抢先:回到 get_mut 路径按「已存在」累加
835                Entry::Occupied(_) => continue,
836            }
837        }
838    }
839
840    async fn keys(&self, pattern: &str) -> Result<Vec<String>> {
841        let now = Instant::now();
842        Ok(self
843            .inner
844            .data
845            .iter()
846            .filter(|e| e.expires_at.map_or(true, |t| now <= t))
847            .filter(|e| match_pattern(e.key(), pattern))
848            .map(|e| e.key().clone())
849            .collect())
850    }
851
852    async fn delete_pattern(&self, pattern: &str) -> Result<u64> {
853        // retain 单趟完成匹配+删除:无中间 Vec 分配、无二次哈希查找
854        let mut removed = 0usize;
855        self.inner.data.retain(|k, _| {
856            if match_pattern(k, pattern) {
857                removed += 1;
858                false
859            } else {
860                true
861            }
862        });
863        if removed > 0 {
864            dec_size(&self.inner, removed);
865            self.inner
866                .stats
867                .deletes
868                .fetch_add(removed as u64, Ordering::Relaxed);
869        }
870        Ok(removed as u64)
871    }
872
873    async fn sadd(&self, key: &str, members: &[String]) -> Result<u64> {
874        if members.is_empty() {
875            return Ok(0);
876        }
877        let now = Instant::now();
878        ensure_capacity_for_insert(&self.inner, key);
879        let mut added = 0u64;
880        // 热路径(key 已存在)先走 get_mut 借用查找,零分配;
881        // 整个「读-改-写」在分片锁内原子完成,无竞态窗口
882        loop {
883            if let Some(mut e) = self.inner.data.get_mut(key) {
884                let expired = e.value().expires_at.is_some_and(|t| now > t);
885                let mut arr: Vec<String> = if expired {
886                    Vec::new()
887                } else {
888                    serde_json::from_slice(&e.value().bytes).map_err(|_| wrong_type_err())?
889                };
890                // HashSet 判重:O(n+m),替代 Vec::contains 的 O(n·m)
891                let mut seen: HashSet<&str> = arr.iter().map(String::as_str).collect();
892                let mut new_members: Vec<String> = Vec::new();
893                for m in members {
894                    if seen.insert(m.as_str()) {
895                        new_members.push(m.clone());
896                        added += 1;
897                    }
898                }
899                drop(seen);
900                arr.extend(new_members);
901                let ent = e.value_mut();
902                ent.bytes = Arc::from(
903                    serde_json::to_vec(&arr).map_err(|err| Error::Msg(err.to_string()))?,
904                );
905                if expired {
906                    ent.expires_at = None; // 过期重建:无 TTL
907                }
908                // 未过期:保留原 TTL,sadd 不抹掉过期时间
909                return Ok(added);
910            }
911            match self.inner.data.entry(key.to_string()) {
912                Entry::Vacant(e) => {
913                    // 输入成员去重(Set 语义:["a","a"] 只计一次)
914                    let mut seen: HashSet<&str> = HashSet::with_capacity(members.len());
915                    let mut arr: Vec<String> = Vec::with_capacity(members.len());
916                    for m in members {
917                        if seen.insert(m.as_str()) {
918                            arr.push(m.clone());
919                            added += 1;
920                        }
921                    }
922                    e.insert(CacheEntry {
923                        bytes: Arc::from(
924                            serde_json::to_vec(&arr).map_err(|err| Error::Msg(err.to_string()))?,
925                        ),
926                        expires_at: None,
927                    });
928                    inc_size(&self.inner);
929                    return Ok(added);
930                }
931                // 并发插入抢先:回到 get_mut 路径并入已有集合
932                Entry::Occupied(_) => continue,
933            }
934        }
935    }
936
937    async fn srem(&self, key: &str, members: &[String]) -> Result<u64> {
938        if members.is_empty() {
939            return Ok(0);
940        }
941        let now = Instant::now();
942        let removed = match self.inner.data.entry(key.to_string()) {
943            Entry::Occupied(mut e) => {
944                if e.get().expires_at.is_some_and(|t| now > t) {
945                    // 过期即不存在:锁内直接移除,无竞态
946                    e.remove();
947                    dec_size(&self.inner, 1);
948                    return Ok(0);
949                }
950                let mut arr: Vec<String> =
951                    serde_json::from_slice(&e.get().bytes).map_err(|_| wrong_type_err())?;
952                let before = arr.len();
953                let targets: HashSet<&str> = members.iter().map(String::as_str).collect();
954                arr.retain(|v| !targets.contains(v.as_str()));
955                let removed = (before - arr.len()) as u64;
956                if removed > 0 {
957                    if arr.is_empty() {
958                        // Redis 语义:集合为空时删除 key
959                        e.remove();
960                        dec_size(&self.inner, 1);
961                    } else {
962                        e.get_mut().bytes = Arc::from(
963                            serde_json::to_vec(&arr).map_err(|err| Error::Msg(err.to_string()))?,
964                        );
965                    }
966                }
967                removed
968            }
969            Entry::Vacant(_) => 0,
970        };
971        Ok(removed)
972    }
973
974    async fn smembers(&self, key: &str) -> Result<Vec<String>> {
975        match self.read_live_bytes(key) {
976            Some(bytes) => {
977                self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
978                serde_json::from_slice(&bytes).map_err(|_| wrong_type_err())
979            }
980            None => {
981                self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
982                Ok(vec![])
983            }
984        }
985    }
986
987    async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool> {
988        check_ttl_secs(ttl_secs)?;
989        let now = Instant::now();
990        match self.inner.data.get_mut(key) {
991            Some(mut entry) => {
992                if entry.expires_at.is_some_and(|t| now > t) {
993                    // 已过期 = 不存在:清理并对齐 Redis 返回 false(不给过期 key 续命)
994                    drop(entry);
995                    remove_if_expired(&self.inner, key, now);
996                    Ok(false)
997                } else {
998                    entry.expires_at = Some(expiry_after(ttl_secs)?);
999                    Ok(true)
1000                }
1001            }
1002            None => Ok(false),
1003        }
1004    }
1005
1006    /// 查询 key 剩余过期秒数(向上取整,对齐 Redis TTL 的舍入方式)
1007    async fn ttl(&self, key: &str) -> Result<Option<u64>> {
1008        let now = Instant::now();
1009        match self.inner.data.get(key) {
1010            Some(entry) => {
1011                if entry.expires_at.is_some_and(|t| now > t) {
1012                    drop(entry);
1013                    remove_if_expired(&self.inner, key, now);
1014                    Ok(None)
1015                } else {
1016                    Ok(entry.expires_at.map(|t| {
1017                        let rem = t.saturating_duration_since(now);
1018                        rem.as_secs() + u64::from(rem.subsec_nanos() > 0)
1019                    }))
1020                }
1021            }
1022            None => Ok(None),
1023        }
1024    }
1025
1026    async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
1027        // 字节直通:跳过 Value 中转(统计口径与 get 保持一致)
1028        match self.read_live_bytes(key) {
1029            Some(bytes) => {
1030                self.inner.stats.hits.fetch_add(1, Ordering::Relaxed);
1031                Ok(Some(bytes.to_vec()))
1032            }
1033            None => {
1034                self.inner.stats.misses.fetch_add(1, Ordering::Relaxed);
1035                Ok(None)
1036            }
1037        }
1038    }
1039
1040    async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
1041        validate_json(value)?;
1042        self.insert_bytes(key, Arc::from(value), None);
1043        Ok(())
1044    }
1045
1046    async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
1047        check_ttl_secs(ttl_secs)?;
1048        validate_json(value)?;
1049        let expires_at = Some(expiry_after(ttl_secs)?);
1050        self.insert_bytes(key, Arc::from(value), expires_at);
1051        Ok(())
1052    }
1053}
1054
1055// ──── Redis 缓存 ────────────────────────────────────
1056
1057/// Redis 缓存实现
1058#[cfg(feature = "redis")]
1059#[derive(Clone)]
1060pub struct RedisCache {
1061    /// Redis 连接管理器
1062    conn: ConnectionManager,
1063    /// `get_or_insert_with` 的进程内并发去重表(Arc 共享,克隆间去重状态一致)
1064    inflight: Arc<InflightMap>,
1065}
1066
1067impl std::fmt::Debug for RedisCache {
1068    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1069        // 不输出连接信息(URL 可能含凭据)
1070        f.debug_struct("RedisCache").finish_non_exhaustive()
1071    }
1072}
1073
1074#[cfg(feature = "redis")]
1075impl RedisCache {
1076    /// 创建 Redis 缓存(需传入已建立的连接管理器)
1077    pub fn new(conn: ConnectionManager) -> Self {
1078        Self {
1079            conn,
1080            inflight: Arc::new(InflightMap::with_hasher(ahash::RandomState::new())),
1081        }
1082    }
1083
1084    /// 从 URL 创建连接
1085    pub async fn connect(url: &str) -> Result<Self> {
1086        let client = redis::Client::open(url)
1087            .map_err(|e| Error::Config(format!("Redis URL 无效: {}", e)))?;
1088        let conn = ConnectionManager::new(client)
1089            .await
1090            .map_err(|e| Error::Config(format!("Redis 连接失败: {}", e)))?;
1091        Ok(Self {
1092            conn,
1093            inflight: Arc::new(InflightMap::with_hasher(ahash::RandomState::new())),
1094        })
1095    }
1096
1097    /// 单飞加载(进程内去重):语义见 [`LocalCache::get_or_insert_with`]。
1098    ///
1099    /// 注意:去重范围为当前进程,跨进程/跨实例的击穿防护需结合分布式锁
1100    /// 或 `set_nx` 自行实现。
1101    pub async fn get_or_insert_with<T, F, Fut>(
1102        &self,
1103        key: &str,
1104        ttl_secs: u64,
1105        load: F,
1106    ) -> Result<T>
1107    where
1108        T: DeserializeOwned + Serialize + Send + Sync,
1109        F: FnOnce() -> Fut,
1110        Fut: std::future::Future<Output = Result<T>>,
1111    {
1112        // 去重逻辑统一在 [`single_flight`](本地/Redis 共享实现)
1113        single_flight(self, &self.inflight, key, ttl_secs, load).await
1114    }
1115
1116    fn map_err(e: redis::RedisError) -> Error {
1117        Error::Msg(e.to_string())
1118    }
1119}
1120
1121/// SCAN 每次迭代的 COUNT hint:1000 减少往返次数
1122#[cfg(feature = "redis")]
1123const SCAN_COUNT: u32 = 1000;
1124
1125#[cfg(feature = "redis")]
1126#[async_trait]
1127impl Cache for RedisCache {
1128    async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>> {
1129        // 字节直通:跳过 String 中转(省一次 UTF-8 校验与整值分配)
1130        let result: Option<Vec<u8>> = redis::cmd("GET")
1131            .arg(key)
1132            .query_async(&mut self.conn.clone())
1133            .await
1134            .map_err(Self::map_err)?;
1135
1136        match result {
1137            Some(bytes) => {
1138                let val: T =
1139                    serde_json::from_slice(&bytes).map_err(|e| Error::Msg(e.to_string()))?;
1140                Ok(Some(val))
1141            }
1142            None => Ok(None),
1143        }
1144    }
1145
1146    async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()> {
1147        let json = serde_json::to_string(value).map_err(|e| Error::Msg(e.to_string()))?;
1148        redis::cmd("SET")
1149            .arg(key)
1150            .arg(&json)
1151            .query_async::<()>(&mut self.conn.clone())
1152            .await
1153            .map_err(Self::map_err)
1154    }
1155
1156    async fn set_ex<T: Serialize + Send + Sync>(
1157        &self,
1158        key: &str,
1159        value: &T,
1160        ttl_secs: u64,
1161    ) -> Result<()> {
1162        check_ttl_secs(ttl_secs)?;
1163        let json = serde_json::to_string(value).map_err(|e| Error::Msg(e.to_string()))?;
1164        redis::cmd("SETEX")
1165            .arg(key)
1166            .arg(ttl_secs)
1167            .arg(&json)
1168            .query_async::<()>(&mut self.conn.clone())
1169            .await
1170            .map_err(Self::map_err)
1171    }
1172
1173    async fn set_nx<T: Serialize + Send + Sync>(
1174        &self,
1175        key: &str,
1176        value: &T,
1177        ttl_secs: u64,
1178    ) -> Result<bool> {
1179        check_ttl_secs(ttl_secs)?;
1180        let json = serde_json::to_string(value).map_err(|e| Error::Msg(e.to_string()))?;
1181        // SET key value NX EX ttl → returns OK if set, nil if already exists
1182        let result: Option<String> = redis::cmd("SET")
1183            .arg(key)
1184            .arg(&json)
1185            .arg("NX")
1186            .arg("EX")
1187            .arg(ttl_secs)
1188            .query_async(&mut self.conn.clone())
1189            .await
1190            .map_err(Self::map_err)?;
1191        Ok(result.is_some())
1192    }
1193
1194    async fn del(&self, key: &str) -> Result<()> {
1195        redis::cmd("DEL")
1196            .arg(key)
1197            .query_async::<()>(&mut self.conn.clone())
1198            .await
1199            .map_err(Self::map_err)
1200    }
1201
1202    async fn exists(&self, key: &str) -> Result<bool> {
1203        redis::cmd("EXISTS")
1204            .arg(key)
1205            .query_async::<i32>(&mut self.conn.clone())
1206            .await
1207            .map_err(Self::map_err)
1208            .map(|v| v > 0)
1209    }
1210
1211    async fn incr(&self, key: &str, delta: i64) -> Result<i64> {
1212        let result: i64 = if delta == 1 {
1213            redis::cmd("INCR")
1214                .arg(key)
1215                .query_async(&mut self.conn.clone())
1216                .await
1217                .map_err(Self::map_err)?
1218        } else {
1219            redis::cmd("INCRBY")
1220                .arg(key)
1221                .arg(delta)
1222                .query_async(&mut self.conn.clone())
1223                .await
1224                .map_err(Self::map_err)?
1225        };
1226        Ok(result)
1227    }
1228
1229    async fn keys(&self, pattern: &str) -> Result<Vec<String>> {
1230        // 用 SCAN 游标迭代匹配的键;SCAN 可能返回重复 key(官方文档行为),去重
1231        let mut cursor: u64 = 0;
1232        let mut out: Vec<String> = Vec::new();
1233        let mut seen: HashSet<String> = HashSet::new();
1234        loop {
1235            let (next, keys): (u64, Vec<String>) = redis::cmd("SCAN")
1236                .arg(cursor)
1237                .arg("MATCH")
1238                .arg(pattern)
1239                .arg("COUNT")
1240                .arg(SCAN_COUNT)
1241                .query_async(&mut self.conn.clone())
1242                .await
1243                .map_err(Self::map_err)?;
1244            for k in keys {
1245                // contains 先行:重复 key(SCAN 文档行为)免 clone
1246                if !seen.contains(&k) {
1247                    seen.insert(k.clone());
1248                    out.push(k);
1249                }
1250            }
1251            cursor = next;
1252            if cursor == 0 {
1253                break;
1254            }
1255        }
1256        Ok(out)
1257    }
1258
1259    async fn delete_pattern(&self, pattern: &str) -> Result<u64> {
1260        // 用 SCAN 游标迭代匹配的键并删除;
1261        // UNLINK 异步释放内存,避免大 value 的 DEL 阻塞 Redis 主线程
1262        let mut cursor: u64 = 0;
1263        let mut total: u64 = 0;
1264        loop {
1265            let (next, keys): (u64, Vec<String>) = redis::cmd("SCAN")
1266                .arg(cursor)
1267                .arg("MATCH")
1268                .arg(pattern)
1269                .arg("COUNT")
1270                .arg(SCAN_COUNT)
1271                .query_async(&mut self.conn.clone())
1272                .await
1273                .map_err(Self::map_err)?;
1274            if !keys.is_empty() {
1275                let mut cmd = redis::cmd("UNLINK");
1276                for k in &keys {
1277                    cmd.arg(k);
1278                }
1279                total += cmd
1280                    .query_async::<u64>(&mut self.conn.clone())
1281                    .await
1282                    .map_err(Self::map_err)?;
1283            }
1284            cursor = next;
1285            if cursor == 0 {
1286                break;
1287            }
1288        }
1289        Ok(total)
1290    }
1291
1292    async fn sadd(&self, key: &str, members: &[String]) -> Result<u64> {
1293        if members.is_empty() {
1294            // 对齐本地后端:空成员不报错(Redis 服务端对零参数 SADD 会报错)
1295            return Ok(0);
1296        }
1297        let mut cmd = redis::cmd("SADD");
1298        cmd.arg(key);
1299        for m in members {
1300            cmd.arg(m);
1301        }
1302        cmd.query_async::<u64>(&mut self.conn.clone())
1303            .await
1304            .map_err(Self::map_err)
1305    }
1306
1307    async fn srem(&self, key: &str, members: &[String]) -> Result<u64> {
1308        if members.is_empty() {
1309            // 对齐本地后端:空成员不报错
1310            return Ok(0);
1311        }
1312        let mut cmd = redis::cmd("SREM");
1313        cmd.arg(key);
1314        for m in members {
1315            cmd.arg(m);
1316        }
1317        cmd.query_async::<u64>(&mut self.conn.clone())
1318            .await
1319            .map_err(Self::map_err)
1320    }
1321
1322    async fn smembers(&self, key: &str) -> Result<Vec<String>> {
1323        redis::cmd("SMEMBERS")
1324            .arg(key)
1325            .query_async::<Vec<String>>(&mut self.conn.clone())
1326            .await
1327            .map_err(Self::map_err)
1328    }
1329
1330    async fn sismember(&self, key: &str, member: &str) -> Result<bool> {
1331        // 原生 SISMEMBER:O(1),避免 SMEMBERS 拉回全量集合再本地判断
1332        redis::cmd("SISMEMBER")
1333            .arg(key)
1334            .arg(member)
1335            .query_async::<i32>(&mut self.conn.clone())
1336            .await
1337            .map(|v| v > 0)
1338            .map_err(Self::map_err)
1339    }
1340
1341    async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool> {
1342        check_ttl_secs(ttl_secs)?;
1343        redis::cmd("EXPIRE")
1344            .arg(key)
1345            .arg(ttl_secs)
1346            .query_async::<i32>(&mut self.conn.clone())
1347            .await
1348            .map(|v| v > 0)
1349            .map_err(Self::map_err)
1350    }
1351
1352    async fn ttl(&self, key: &str) -> Result<Option<u64>> {
1353        // Redis TTL:-2 = key 不存在,-1 = 未设置过期时间,>0 = 剩余秒数(向上取整)
1354        let v: i64 = redis::cmd("TTL")
1355            .arg(key)
1356            .query_async(&mut self.conn.clone())
1357            .await
1358            .map_err(Self::map_err)?;
1359        Ok((v > 0).then_some(v as u64))
1360    }
1361
1362    async fn sadd_with_ttl(&self, key: &str, members: &[String], ttl_secs: u64) -> Result<()> {
1363        check_ttl_secs(ttl_secs)?;
1364        // 与默认实现语义一致:空成员退化为仅刷新 TTL(SADD 不接受零参数)
1365        if members.is_empty() {
1366            return self.expire(key, ttl_secs).await.map(|_| ());
1367        }
1368        // pipeline 原子发送:SADD 与 EXPIRE 在同一连接上连续执行,消除
1369        // 默认实现"两步之间崩溃留下无 TTL key"的窗口。
1370        redis::pipe()
1371            .atomic()
1372            .sadd(key, members)
1373            .expire(key, ttl_secs as i64)
1374            .query_async::<()>(&mut self.conn.clone())
1375            .await
1376            .map_err(Self::map_err)
1377    }
1378
1379    async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
1380        // 字节直通:跳过 String/Value 中转
1381        redis::cmd("GET")
1382            .arg(key)
1383            .query_async::<Option<Vec<u8>>>(&mut self.conn.clone())
1384            .await
1385            .map_err(Self::map_err)
1386    }
1387
1388    async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
1389        validate_json(value)?;
1390        redis::cmd("SET")
1391            .arg(key)
1392            .arg(value)
1393            .query_async::<()>(&mut self.conn.clone())
1394            .await
1395            .map_err(Self::map_err)
1396    }
1397
1398    async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
1399        check_ttl_secs(ttl_secs)?;
1400        validate_json(value)?;
1401        redis::cmd("SETEX")
1402            .arg(key)
1403            .arg(ttl_secs)
1404            .arg(value)
1405            .query_async::<()>(&mut self.conn.clone())
1406            .await
1407            .map_err(Self::map_err)
1408    }
1409}
1410
1411// ──── 模式匹配 ──────────────────────────────────────
1412
1413fn match_pattern(key: &str, pattern: &str) -> bool {
1414    // 快速路径:无通配符 → 精确比较
1415    if !pattern.contains(&['*', '?'][..]) {
1416        return key == pattern;
1417    }
1418    // 快速路径:仅尾部一个 `*` → 纯前缀匹配(最常见形态,如 `user:*`)
1419    if let Some(prefix) = pattern.strip_suffix('*') {
1420        if !prefix.contains(&['*', '?'][..]) {
1421            return key.starts_with(prefix);
1422        }
1423    }
1424    match_glob(key.as_bytes(), pattern.as_bytes())
1425}
1426
1427/// 迭代式 glob 匹配(`*` 任意长、`?` 单字符)。
1428///
1429/// 采用双指针 + 单一回溯点算法,最坏复杂度 O(n·m)。
1430fn match_glob(key: &[u8], pat: &[u8]) -> bool {
1431    let (mut ki, mut pi) = (0usize, 0usize);
1432    // 最近一次 `*` 的位置及其匹配到 key 的回溯起点
1433    let mut star_pi: Option<usize> = None;
1434    let mut star_ki = 0usize;
1435
1436    while ki < key.len() {
1437        if pi < pat.len() && (pat[pi] == b'?' || pat[pi] == key[ki]) {
1438            ki += 1;
1439            pi += 1;
1440        } else if pi < pat.len() && pat[pi] == b'*' {
1441            // 记录回溯点,`*` 先尝试匹配空串
1442            star_pi = Some(pi);
1443            star_ki = ki;
1444            pi += 1;
1445        } else if let Some(sp) = star_pi {
1446            // 失配:让上一个 `*` 多吞掉一个字符后重试
1447            pi = sp + 1;
1448            star_ki += 1;
1449            ki = star_ki;
1450        } else {
1451            return false;
1452        }
1453    }
1454
1455    // key 耗尽后,模式剩余部分必须全是 `*`
1456    while pi < pat.len() && pat[pi] == b'*' {
1457        pi += 1;
1458    }
1459    pi == pat.len()
1460}
1461
1462// ──── 共享缓存 ────────────────────────────────
1463
1464/// 共享缓存:枚举包装所有缓存实现,供插件与路由层统一使用
1465#[derive(Clone, Debug)]
1466pub enum SharedCache {
1467    Local(LocalCache),
1468    /// Redis 缓存后端(需启用 `redis` feature,默认启用)
1469    #[cfg(feature = "redis")]
1470    Redis(RedisCache),
1471}
1472
1473impl SharedCache {
1474    /// 单飞加载:语义见 [`LocalCache::get_or_insert_with`];
1475    /// Redis 后端的去重范围为当前进程(见 [`RedisCache::get_or_insert_with`])。
1476    pub async fn get_or_insert_with<T, F, Fut>(
1477        &self,
1478        key: &str,
1479        ttl_secs: u64,
1480        load: F,
1481    ) -> Result<T>
1482    where
1483        T: DeserializeOwned + Serialize + Send + Sync,
1484        F: FnOnce() -> Fut,
1485        Fut: std::future::Future<Output = Result<T>>,
1486    {
1487        match self {
1488            SharedCache::Local(c) => c.get_or_insert_with(key, ttl_secs, load).await,
1489            #[cfg(feature = "redis")]
1490            SharedCache::Redis(c) => {
1491                c.get_or_insert_with(key, ttl_secs, load).await
1492            }
1493        }
1494    }
1495}
1496
1497#[async_trait]
1498impl Cache for SharedCache {
1499    async fn get<T: DeserializeOwned + Send>(&self, key: &str) -> Result<Option<T>> {
1500        match self {
1501            SharedCache::Local(c) => c.get(key).await,
1502            #[cfg(feature = "redis")]
1503            SharedCache::Redis(c) => c.get(key).await,
1504        }
1505    }
1506
1507    async fn set<T: Serialize + Send + Sync>(&self, key: &str, value: &T) -> Result<()> {
1508        match self {
1509            SharedCache::Local(c) => c.set(key, value).await,
1510            #[cfg(feature = "redis")]
1511            SharedCache::Redis(c) => c.set(key, value).await,
1512        }
1513    }
1514
1515    async fn set_ex<T: Serialize + Send + Sync>(
1516        &self,
1517        key: &str,
1518        value: &T,
1519        ttl_secs: u64,
1520    ) -> Result<()> {
1521        match self {
1522            SharedCache::Local(c) => c.set_ex(key, value, ttl_secs).await,
1523            #[cfg(feature = "redis")]
1524            SharedCache::Redis(c) => c.set_ex(key, value, ttl_secs).await,
1525        }
1526    }
1527
1528    async fn del(&self, key: &str) -> Result<()> {
1529        match self {
1530            SharedCache::Local(c) => c.del(key).await,
1531            #[cfg(feature = "redis")]
1532            SharedCache::Redis(c) => c.del(key).await,
1533        }
1534    }
1535
1536    async fn exists(&self, key: &str) -> Result<bool> {
1537        match self {
1538            SharedCache::Local(c) => c.exists(key).await,
1539            #[cfg(feature = "redis")]
1540            SharedCache::Redis(c) => c.exists(key).await,
1541        }
1542    }
1543
1544    async fn incr(&self, key: &str, delta: i64) -> Result<i64> {
1545        match self {
1546            SharedCache::Local(c) => c.incr(key, delta).await,
1547            #[cfg(feature = "redis")]
1548            SharedCache::Redis(c) => c.incr(key, delta).await,
1549        }
1550    }
1551
1552    async fn keys(&self, pattern: &str) -> Result<Vec<String>> {
1553        match self {
1554            SharedCache::Local(c) => c.keys(pattern).await,
1555            #[cfg(feature = "redis")]
1556            SharedCache::Redis(c) => c.keys(pattern).await,
1557        }
1558    }
1559
1560    async fn set_nx<T: Serialize + Send + Sync>(
1561        &self,
1562        key: &str,
1563        value: &T,
1564        ttl_secs: u64,
1565    ) -> Result<bool> {
1566        match self {
1567            SharedCache::Local(c) => c.set_nx(key, value, ttl_secs).await,
1568            #[cfg(feature = "redis")]
1569            SharedCache::Redis(c) => c.set_nx(key, value, ttl_secs).await,
1570        }
1571    }
1572    async fn delete_pattern(&self, pattern: &str) -> Result<u64> {
1573        match self {
1574            SharedCache::Local(c) => c.delete_pattern(pattern).await,
1575            #[cfg(feature = "redis")]
1576            SharedCache::Redis(c) => c.delete_pattern(pattern).await,
1577        }
1578    }
1579
1580    async fn sadd(&self, key: &str, members: &[String]) -> Result<u64> {
1581        match self {
1582            SharedCache::Local(c) => c.sadd(key, members).await,
1583            #[cfg(feature = "redis")]
1584            SharedCache::Redis(c) => c.sadd(key, members).await,
1585        }
1586    }
1587
1588    async fn srem(&self, key: &str, members: &[String]) -> Result<u64> {
1589        match self {
1590            SharedCache::Local(c) => c.srem(key, members).await,
1591            #[cfg(feature = "redis")]
1592            SharedCache::Redis(c) => c.srem(key, members).await,
1593        }
1594    }
1595
1596    async fn smembers(&self, key: &str) -> Result<Vec<String>> {
1597        match self {
1598            SharedCache::Local(c) => c.smembers(key).await,
1599            #[cfg(feature = "redis")]
1600            SharedCache::Redis(c) => c.smembers(key).await,
1601        }
1602    }
1603
1604    async fn sismember(&self, key: &str, member: &str) -> Result<bool> {
1605        match self {
1606            SharedCache::Local(c) => c.sismember(key, member).await,
1607            #[cfg(feature = "redis")]
1608            SharedCache::Redis(c) => c.sismember(key, member).await,
1609        }
1610    }
1611
1612    async fn expire(&self, key: &str, ttl_secs: u64) -> Result<bool> {
1613        match self {
1614            SharedCache::Local(c) => c.expire(key, ttl_secs).await,
1615            #[cfg(feature = "redis")]
1616            SharedCache::Redis(c) => c.expire(key, ttl_secs).await,
1617        }
1618    }
1619
1620    async fn ttl(&self, key: &str) -> Result<Option<u64>> {
1621        match self {
1622            SharedCache::Local(c) => c.ttl(key).await,
1623            #[cfg(feature = "redis")]
1624            SharedCache::Redis(c) => c.ttl(key).await,
1625        }
1626    }
1627
1628    async fn sadd_with_ttl(&self, key: &str, members: &[String], ttl_secs: u64) -> Result<()> {
1629        match self {
1630            SharedCache::Local(c) => c.sadd_with_ttl(key, members, ttl_secs).await,
1631            #[cfg(feature = "redis")]
1632            SharedCache::Redis(c) => c.sadd_with_ttl(key, members, ttl_secs).await,
1633        }
1634    }
1635
1636    // 覆盖 raw 三方法:转发到各后端的字节直通实现,避免走 trait 默认的
1637    // serde_json::Value 中转(双重解析/序列化,且丢失原始字节格式)
1638    async fn get_raw(&self, key: &str) -> Result<Option<Vec<u8>>> {
1639        match self {
1640            SharedCache::Local(c) => c.get_raw(key).await,
1641            #[cfg(feature = "redis")]
1642            SharedCache::Redis(c) => c.get_raw(key).await,
1643        }
1644    }
1645
1646    async fn set_raw(&self, key: &str, value: &[u8]) -> Result<()> {
1647        match self {
1648            SharedCache::Local(c) => c.set_raw(key, value).await,
1649            #[cfg(feature = "redis")]
1650            SharedCache::Redis(c) => c.set_raw(key, value).await,
1651        }
1652    }
1653
1654    async fn set_raw_ex(&self, key: &str, value: &[u8], ttl_secs: u64) -> Result<()> {
1655        match self {
1656            SharedCache::Local(c) => c.set_raw_ex(key, value, ttl_secs).await,
1657            #[cfg(feature = "redis")]
1658            SharedCache::Redis(c) => c.set_raw_ex(key, value, ttl_secs).await,
1659        }
1660    }
1661
1662    fn stats(&self) -> CacheStats {
1663        match self {
1664            SharedCache::Local(c) => c.stats(),
1665            #[cfg(feature = "redis")]
1666            SharedCache::Redis(_) => CacheStats::default(),
1667        }
1668    }
1669}
1670
1671// ──── 延迟删除(延迟双删)───────────────────────────────
1672
1673/// 延迟删除单个 key(延迟双删的第二次删除)。
1674///
1675/// 在 `delay` 后于后台任务中删除 `key`,删除失败仅记录 warn 日志,
1676/// 不阻塞也不影响调用方。典型用法:更新数据库后先同步 [`Cache::del`]
1677/// 立即删除缓存,再调用本函数安排一次延迟删除,以清除「第一次删除前
1678/// 已读到旧数据、删除后才写回缓存」的并发读线程产生的脏缓存窗口。
1679pub fn delete_after(cache: SharedCache, key: String, delay: Duration) -> tokio::task::JoinHandle<()> {
1680    tokio::spawn(async move {
1681        tokio::time::sleep(delay).await;
1682        if let Err(e) = cache.del(&key).await {
1683            tracing::warn!(key = %key, error = %e, "延迟双删第二次删除失败");
1684        }
1685    })
1686}
1687
1688/// 延迟按模式删除(延迟双删的第二次删除,批量 key 场景)。
1689///
1690/// 语义同 [`delete_after`],延迟后删除匹配 `pattern` 的所有 key。
1691pub fn delete_pattern_after(
1692    cache: SharedCache,
1693    pattern: String,
1694    delay: Duration,
1695) -> tokio::task::JoinHandle<()> {
1696    tokio::spawn(async move {
1697        tokio::time::sleep(delay).await;
1698        if let Err(e) = cache.delete_pattern(&pattern).await {
1699            tracing::warn!(pattern = %pattern, error = %e, "延迟双删(模式)第二次删除失败");
1700        }
1701    })
1702}
1703
1704// ──── 工厂函数 ──────────────────────────────────────
1705
1706/// 从配置创建共享缓存实例
1707///
1708/// Redis 连接优先使用 `REDIS_URL` 环境变量。
1709/// 本地缓存会自动启动后台过期清理任务(随实例释放自动停止)。
1710/// `cache.type` 为未知值时返回配置错误(不静默回退本地缓存,避免配置 typo 难以排查)。
1711pub async fn create_cache(
1712    cache_config: &wordval_config::CacheConfig,
1713    redis_config: &wordval_config::RedisConfig,
1714) -> Result<SharedCache> {
1715    match cache_config.r#type.as_str() {
1716        "redis" => {
1717            #[cfg(not(feature = "redis"))]
1718            {
1719                let _ = redis_config;
1720                Err(Error::Config(
1721                    "cache.type=redis 需要启用 wordval-cache 的 \"redis\" feature(默认启用)"
1722                        .into(),
1723                ))
1724            }
1725            #[cfg(feature = "redis")]
1726            {
1727                let redis_url = std::env::var("REDIS_URL")
1728                    .ok()
1729                    .filter(|s| !s.is_empty())
1730                    .unwrap_or_else(|| redis_config.url.clone());
1731                tracing::info!(
1732                    "使用 Redis 缓存 url={}",
1733                    sanitize_redis_url(&redis_url)
1734                );
1735                Ok(SharedCache::Redis(RedisCache::connect(&redis_url).await?))
1736            }
1737        }
1738        "local" => {
1739            tracing::info!("使用本地缓存 capacity={}", cache_config.max_capacity);
1740            let cache = LocalCache::new(cache_config.max_capacity, cache_config.default_ttl);
1741            // 惰性过期之外叠加主动回收,及时释放过期条目占用的内存
1742            cache.start_background_cleanup();
1743            Ok(SharedCache::Local(cache))
1744        }
1745        other => Err(Error::Config(format!(
1746            "cache.type 无效: \"{other}\"(支持 \"local\" / \"redis\")"
1747        ))),
1748    }
1749}
1750
1751#[cfg(test)]
1752mod tests {
1753    use super::*;
1754
1755    #[tokio::test]
1756    async fn test_local_cache_get_set() {
1757        let c = LocalCache::new(100, 0);
1758        c.set("key1", &"value1".to_string()).await.unwrap();
1759        let val: Option<String> = c.get("key1").await.unwrap();
1760        assert_eq!(val, Some("value1".to_string()));
1761        c.del("key1").await.unwrap();
1762        let val: Option<String> = c.get("key1").await.unwrap();
1763        assert_eq!(val, None);
1764    }
1765
1766    #[tokio::test]
1767    async fn test_set_ex_expiration() {
1768        let c = LocalCache::new(100, 0);
1769        c.set_ex("temp", &"expire".to_string(), 1).await.unwrap();
1770        let val: Option<String> = c.get("temp").await.unwrap();
1771        assert_eq!(val, Some("expire".to_string()));
1772        tokio::time::sleep(Duration::from_secs(2)).await;
1773        let val: Option<String> = c.get("temp").await.unwrap();
1774        assert_eq!(val, None);
1775    }
1776
1777    #[tokio::test]
1778    async fn test_incr() {
1779        let c = LocalCache::new(100, 0);
1780        assert_eq!(c.incr("counter", 1).await.unwrap(), 1);
1781        assert_eq!(c.incr("counter", 5).await.unwrap(), 6);
1782        assert_eq!(c.incr("counter", -2).await.unwrap(), 4);
1783    }
1784
1785    #[tokio::test]
1786    async fn test_keys_pattern() {
1787        let c = LocalCache::new(100, 0);
1788        c.set("user:1", &"alice").await.unwrap();
1789        c.set("user:2", &"bob").await.unwrap();
1790        c.set("order:1", &"o1").await.unwrap();
1791        let keys = c.keys("user:*").await.unwrap();
1792        assert_eq!(keys.len(), 2);
1793        assert!(keys.contains(&"user:1".to_string()));
1794        assert!(keys.contains(&"user:2".to_string()));
1795    }
1796
1797    // ──── 回归测试:单飞守卫在任务取消后清理去重表 ──────
1798    // 旧实现(函数式清理)在调用方于回源中被取消时条目滞留表内,
1799    // RAII 守卫应在取消路径同步清理
1800
1801    #[tokio::test]
1802    async fn test_inflight_guard_cleans_after_cancel() {
1803        let c = LocalCache::new(100, 0);
1804        let handle = tokio::spawn({
1805            let c = c.clone();
1806            async move {
1807                // 长耗时回源:让任务停在 load().await 上等待被取消
1808                let _ = c
1809                    .get_or_insert_with::<String, _, _>("cancel", 60, || async {
1810                        tokio::time::sleep(Duration::from_secs(30)).await;
1811                        Ok("v".to_string())
1812                    })
1813                    .await;
1814            }
1815        });
1816        // 等待任务进入回源等待(条目已入表)
1817        tokio::time::sleep(Duration::from_millis(100)).await;
1818        assert_eq!(
1819            c.inner.inflight.len(),
1820            1,
1821            "回源期间去重表应持有条目"
1822        );
1823        handle.abort();
1824        // 取消后 RAII 守卫应移除条目(轮询等待 Drop 生效)
1825        for _ in 0..50 {
1826            if c.inner.inflight.is_empty() {
1827                break;
1828            }
1829            tokio::time::sleep(Duration::from_millis(20)).await;
1830        }
1831        assert!(
1832            c.inner.inflight.is_empty(),
1833            "取消后去重表条目应被守卫清理,实际剩余 {}",
1834            c.inner.inflight.len()
1835        );
1836        // 自愈后仍可正常使用
1837        let v: String = c
1838            .get_or_insert_with("cancel", 60, || async { Ok("ok".to_string()) })
1839            .await
1840            .unwrap();
1841        assert_eq!(v, "ok");
1842    }
1843
1844    // ──── 回归测试:Debug 实现不泄露数据 ──────────────────
1845
1846    #[tokio::test]
1847    async fn test_debug_impl() {
1848        let c = LocalCache::new(100, 0);
1849        c.set("secret_key", &"secret_value".to_string()).await.unwrap();
1850        let s = format!("{c:?}");
1851        assert!(s.contains("LocalCache"), "Debug 应含类型名: {s}");
1852        assert!(
1853            !s.contains("secret"),
1854            "Debug 不应输出条目数据: {s}"
1855        );
1856        let shared = SharedCache::Local(c);
1857        assert!(format!("{shared:?}").starts_with("Local("));
1858    }
1859
1860    #[tokio::test]
1861    async fn test_delete_pattern() {
1862        let c = LocalCache::new(100, 0);
1863        c.set("session:a", &"s1").await.unwrap();
1864        c.set("session:b", &"s2").await.unwrap();
1865        c.set("user:1", &"alice").await.unwrap();
1866        let deleted = c.delete_pattern("session:*").await.unwrap();
1867        assert_eq!(deleted, 2);
1868        assert!(!c.exists("session:a").await.unwrap());
1869        assert!(!c.exists("session:b").await.unwrap());
1870        assert!(c.exists("user:1").await.unwrap());
1871    }
1872}