Skip to main content

yang_base/database/
global_redis.rs

1//! 全局 Redis 访问器
2//!
3//! 提供线程安全的全局 Redis 实例访问。
4//!
5//! # 设计说明
6//!
7//! GlobalRedis 是对 yang-db::RedisClient 的封装,使用 OnceLock 实现全局单例模式。
8//! 所有 Redis 操作都通过 yang-db 库实现,确保类型安全和统一的 Redis 访问接口。
9//!
10//! # 批量参数说明
11//!
12//! 批量操作方法(如 `del`、`exists`、`lpush` 等)接受 `&[impl AsRef<str>]` 类型参数,
13//! 支持传入 `&[&str]`、`&[String]`、`&[&String]` 等多种形式,使用更灵活。
14//!
15//! # Pipeline / Transaction 说明
16//!
17//! 可通过 `GlobalRedis::transaction()` 获取 `yang_db::redis::RedisTransaction`,
18//! 支持 WATCH/MULTI/EXEC 乐观锁事务。也可通过 `GlobalRedis::client()` 直接访问
19//! `yang_db::RedisClient`,使用其 `pipeline()` 方法进行批量操作,或使用
20//! `script()` / `eval_script()` 执行 Lua 脚本。
21//!
22//! # 示例
23//!
24//! ```rust,ignore
25//! use yang_base::database::GlobalRedis;
26//! use yang_db::redis::RedisConfig;
27//!
28//! // 初始化全局 Redis
29//! GlobalRedis::init("redis://127.0.0.1:6379", RedisConfig::default()).await?;
30//!
31//! // String 操作
32//! GlobalRedis::set("key", "value", None).await?;
33//! let value = GlobalRedis::get("key").await?;
34//!
35//! // Hash 操作
36//! GlobalRedis::hset("user:1", "name", "Alice").await?;
37//! let name = GlobalRedis::hget("user:1", "name").await?;
38//!
39//! // List 操作(支持 &[&str] 或 &[String])
40//! GlobalRedis::lpush("queue", &["task1", "task2"]).await?;
41//! let task = GlobalRedis::lpop("queue").await?;
42//!
43//! // 批量操作
44//! GlobalRedis::mset(&[("k1".to_string(), "v1".to_string())]).await?;
45//! let vals = GlobalRedis::mget(&["k1", "k2"]).await?;
46//!
47//! // 事务操作
48//! let mut tx = GlobalRedis::transaction()?;
49//! tx.set("key1", "value1").incr("counter");
50//! let result: (String, i64) = tx.exec().await?;
51//! ```
52
53use crate::error::BaseError;
54use std::sync::OnceLock;
55use yang_db::redis::{RedisClient, RedisConfig, RedisTransaction};
56
57/// 全局 Redis 实例
58///
59/// 使用 OnceLock 确保线程安全的单例模式
60static GLOBAL_REDIS: OnceLock<RedisClient> = OnceLock::new();
61
62/// 全局 Redis 访问器
63///
64/// 封装 yang-db::RedisClient,提供全局静态访问接口。
65/// 所有 Redis 操作都通过 yang-db 库实现。
66pub struct GlobalRedis;
67
68impl GlobalRedis {
69    /// 初始化全局 Redis
70    ///
71    /// # 参数
72    ///
73    /// - `url`: Redis 连接字符串,格式:`redis://host:port` 或 `redis://:password@host:port`
74    /// - `config`: Redis 配置,包含连接池参数
75    ///
76    /// # 返回
77    ///
78    /// - `Ok(())`: 初始化成功
79    /// - `Err(BaseError)`: 初始化失败
80    ///
81    /// # 错误
82    ///
83    /// - `RedisConnectionFailed`: Redis 连接失败
84    /// - `RedisAlreadyInitialized`: Redis 已经初始化
85    ///
86    /// # 示例
87    ///
88    /// ```rust,ignore
89    /// use yang_base::database::GlobalRedis;
90    /// use yang_db::redis::RedisConfig;
91    ///
92    /// let config = RedisConfig::default()
93    ///     .with_max_connections(10)
94    ///     .with_connect_timeout(5)
95    ///     .with_wait_timeout(30)
96    ///     .with_idle_timeout(300)
97    ///     .with_enable_logging(true);
98    ///
99    /// GlobalRedis::init("redis://127.0.0.1:6379", config).await?;
100    /// ```
101    pub async fn init(url: &str, config: RedisConfig) -> Result<(), BaseError> {
102        // 使用 yang-db::RedisClient::connect_with_config 创建 Redis 连接
103        let client = RedisClient::connect_with_config(url, config)
104            .await
105            .map_err(BaseError::RedisConnectionFailed)?;
106
107        // 设置全局 Redis 实例
108        GLOBAL_REDIS
109            .set(client)
110            .map_err(|_| BaseError::RedisAlreadyInitialized)?;
111
112        log::info!("全局 Redis 已初始化");
113        Ok(())
114    }
115
116    /// 获取全局 Redis 实例
117    ///
118    /// # 返回
119    ///
120    /// - `Ok(&'static RedisClient)`: yang-db::RedisClient 实例的静态引用
121    /// - `Err(BaseError)`: Redis 未初始化
122    ///
123    /// # 错误
124    ///
125    /// - `RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
126    ///
127    /// # API 一致性说明 (A-M4)
128    ///
129    /// 本方法名为 `client()`,而数据库对等方法名为
130    /// [`GlobalDatabase::get()`](crate::database::GlobalDatabase::get)。
131    /// 这是历史命名不对称,未来应统一为同一种命名风格(例如都叫 `get()` 或都叫
132    /// `client()`)。
133    pub fn client() -> Result<&'static RedisClient, BaseError> {
134        GLOBAL_REDIS.get().ok_or(BaseError::RedisNotInitialized)
135    }
136
137    /// Redis 健康检查
138    ///
139    /// 委托底层 [`RedisClient::health_check`],通过 PING 命令验证连接可达性。
140    ///
141    /// # 返回
142    ///
143    /// - `Ok(true)`: Redis 连接正常
144    /// - `Ok(false)`: PING 响应异常
145    /// - `Err(BaseError)`: Redis 未初始化或无法获取连接
146    ///
147    /// # 错误
148    ///
149    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
150    /// - `BaseError::RedisOperationFailed`: 无法获取连接
151    pub async fn health_check() -> Result<bool, BaseError> {
152        Self::client()?
153            .health_check()
154            .await
155            .map_err(BaseError::RedisOperationFailed)
156    }
157
158    /// 获取 Redis 连接池状态
159    ///
160    /// 委托底层 [`RedisClient::pool_status`],返回连接池的实时统计信息。
161    ///
162    /// # 返回
163    ///
164    /// - `Ok(PoolStatus)`: 连接池状态(含 `max_size`/`size`/`available`/`waiting`)
165    /// - `Err(BaseError)`: Redis 未初始化
166    ///
167    /// # 错误
168    ///
169    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
170    pub fn pool_status() -> Result<yang_db::redis::PoolStatus, BaseError> {
171        Ok(Self::client()?.pool_status())
172    }
173
174    /// 优雅关闭全局 Redis 连接池(I3)。
175    ///
176    /// 供编排式停机([`crate::lifecycle`])调用。`OnceLock` 单例不重置,仅原地关闭
177    /// 连接池——停机后不应再使用。未初始化时为 no-op。
178    pub async fn close() {
179        if let Some(client) = GLOBAL_REDIS.get() {
180            client.close().await;
181        }
182    }
183
184    // ==================== String 操作 ====================
185
186    /// 设置字符串值
187    ///
188    /// # 参数
189    ///
190    /// - `key`: 键名
191    /// - `value`: 值
192    /// - `expire_seconds`: 过期时间(秒),None 表示不过期。秒数必须为正;
193    ///   `Some(0)` 或 `Some(负数)` 会被 Redis 拒绝并返回
194    ///   [`BaseError::RedisOperationFailed`]
195    ///
196    /// # 返回
197    ///
198    /// - `Ok(())`: 设置成功
199    /// - `Err(BaseError)`: 设置失败
200    ///
201    /// # 错误
202    ///
203    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
204    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
205    pub async fn set(
206        key: impl Into<String>,
207        value: impl Into<String>,
208        expire_seconds: Option<i64>,
209    ) -> Result<(), BaseError> {
210        let key_str = key.into();
211        let value_str = value.into();
212
213        if let Some(seconds) = expire_seconds {
214            // 使用 SETEX 设置带过期时间的值
215            Self::client()?
216                .setex(key_str, seconds, value_str)
217                .await
218                .map_err(BaseError::RedisOperationFailed)
219        } else {
220            // 使用 SET 设置不过期的值
221            Self::client()?
222                .set(key_str, value_str)
223                .await
224                .map_err(BaseError::RedisOperationFailed)
225        }
226    }
227
228    /// 仅当键不存在时设置值并指定过期时间(原子 SET NX EX)。
229    ///
230    /// 委托 [`RedisClient::set_nx_ex`],是原子性的"不存在则写入+设过期时间"操作。
231    /// 适用于分布式锁、去重、以及需要竞态保护的场景(如 Refresh Token 轮换)。
232    ///
233    /// # 参数
234    ///
235    /// - `key`: 键名
236    /// - `value`: 值
237    /// - `ttl`: 过期时间(秒),必须为正数
238    ///
239    /// # 返回
240    ///
241    /// - `Ok(true)`: 设置成功(键之前不存在,本调用是首次写入)
242    /// - `Ok(false)`: 键已存在,未设置
243    /// - `Err(BaseError)`: 操作失败
244    ///
245    /// # 错误
246    ///
247    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
248    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
249    pub async fn set_nx_ex(
250        key: impl Into<String>,
251        value: impl Into<String>,
252        ttl: i64,
253    ) -> Result<bool, BaseError> {
254        Self::client()?
255            .set_nx_ex(key, value, ttl)
256            .await
257            .map_err(BaseError::RedisOperationFailed)
258    }
259
260    /// 获取字符串值
261    ///
262    /// # 参数
263    ///
264    /// - `key`: 键名
265    ///
266    /// # 返回
267    ///
268    /// - `Ok(Some(String))`: 获取成功,返回值
269    /// - `Ok(None)`: 键不存在
270    /// - `Err(BaseError)`: 获取失败
271    ///
272    /// # 错误
273    ///
274    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
275    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
276    pub async fn get(key: impl Into<String>) -> Result<Option<String>, BaseError> {
277        Self::client()?
278            .get(key)
279            .await
280            .map_err(BaseError::RedisOperationFailed)
281    }
282
283    /// 删除键
284    ///
285    /// # 参数
286    ///
287    /// - `keys`: 键名列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
288    ///
289    /// # 返回
290    ///
291    /// - `Ok(i64)`: 删除的键数量
292    /// - `Err(BaseError)`: 删除失败
293    ///
294    /// # 错误
295    ///
296    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
297    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
298    pub async fn del(keys: &[impl AsRef<str>]) -> Result<i64, BaseError> {
299        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
300        let keys_vec: Vec<String> = keys.iter().map(|k| k.as_ref().to_string()).collect();
301        Self::client()?
302            .del(&keys_vec)
303            .await
304            .map_err(BaseError::RedisOperationFailed)
305    }
306
307    /// 检查键是否存在
308    ///
309    /// # 参数
310    ///
311    /// - `keys`: 键名列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
312    ///
313    /// # 返回
314    ///
315    /// - `Ok(i64)`: 存在的键数量
316    /// - `Err(BaseError)`: 检查失败
317    ///
318    /// # 错误
319    ///
320    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
321    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
322    pub async fn exists(keys: &[impl AsRef<str>]) -> Result<i64, BaseError> {
323        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
324        let keys_vec: Vec<String> = keys.iter().map(|k| k.as_ref().to_string()).collect();
325        Self::client()?
326            .exists(&keys_vec)
327            .await
328            .map_err(BaseError::RedisOperationFailed)
329    }
330
331    /// 设置键的过期时间
332    ///
333    /// # 参数
334    ///
335    /// - `key`: 键名
336    /// - `seconds`: 过期时间(秒)
337    ///
338    /// # 返回
339    ///
340    /// - `Ok(bool)`: true 表示设置成功,false 表示键不存在
341    /// - `Err(BaseError)`: 设置失败
342    ///
343    /// # 错误
344    ///
345    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
346    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
347    pub async fn expire(key: impl Into<String>, seconds: i64) -> Result<bool, BaseError> {
348        Self::client()?
349            .expire(key, seconds)
350            .await
351            .map_err(BaseError::RedisOperationFailed)
352    }
353
354    /// 获取键的剩余生存时间
355    ///
356    /// # 参数
357    ///
358    /// - `key`: 键名
359    ///
360    /// # 返回
361    ///
362    /// - `Ok(i64)`: 剩余秒数,-1 表示没有过期时间,-2 表示键不存在
363    /// - `Err(BaseError)`: 获取失败
364    ///
365    /// # 错误
366    ///
367    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
368    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
369    pub async fn ttl(key: impl Into<String>) -> Result<i64, BaseError> {
370        Self::client()?
371            .ttl(key)
372            .await
373            .map_err(BaseError::RedisOperationFailed)
374    }
375
376    /// 移除键的过期时间
377    ///
378    /// # 参数
379    ///
380    /// - `key`: 键名
381    ///
382    /// # 返回
383    ///
384    /// - `Ok(bool)`: true 表示成功,false 表示键不存在或没有过期时间
385    /// - `Err(BaseError)`: 操作失败
386    ///
387    /// # 错误
388    ///
389    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
390    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
391    pub async fn persist(key: impl Into<String>) -> Result<bool, BaseError> {
392        Self::client()?
393            .persist(key)
394            .await
395            .map_err(BaseError::RedisOperationFailed)
396    }
397
398    /// 查找所有匹配给定模式的键
399    ///
400    /// # 参数
401    ///
402    /// - `pattern`: 匹配模式(支持 * ? [] 等通配符)
403    ///
404    /// # 返回
405    ///
406    /// - `Ok(Vec<String>)`: 匹配的键列表
407    /// - `Err(BaseError)`: 查找失败
408    ///
409    /// # 错误
410    ///
411    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
412    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
413    pub async fn keys(pattern: impl Into<String>) -> Result<Vec<String>, BaseError> {
414        Self::client()?
415            .keys(pattern)
416            .await
417            .map_err(BaseError::RedisOperationFailed)
418    }
419
420    // ==================== Hash 操作 ====================
421
422    /// 设置 Hash 字段值
423    ///
424    /// # 参数
425    ///
426    /// - `key`: 键名
427    /// - `field`: 字段名
428    /// - `value`: 值
429    ///
430    /// # 返回
431    ///
432    /// - `Ok(bool)`: true 表示新字段,false 表示更新已有字段
433    /// - `Err(BaseError)`: 设置失败
434    ///
435    /// # 错误
436    ///
437    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
438    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
439    pub async fn hset(
440        key: impl Into<String>,
441        field: impl Into<String>,
442        value: impl Into<String>,
443    ) -> Result<bool, BaseError> {
444        Self::client()?
445            .hset(key, field, value)
446            .await
447            .map_err(BaseError::RedisOperationFailed)
448    }
449
450    /// 获取 Hash 字段值
451    ///
452    /// # 参数
453    ///
454    /// - `key`: 键名
455    /// - `field`: 字段名
456    ///
457    /// # 返回
458    ///
459    /// - `Ok(Some(String))`: 获取成功,返回值
460    /// - `Ok(None)`: 字段不存在
461    /// - `Err(BaseError)`: 获取失败
462    ///
463    /// # 错误
464    ///
465    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
466    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
467    pub async fn hget(
468        key: impl Into<String>,
469        field: impl Into<String>,
470    ) -> Result<Option<String>, BaseError> {
471        Self::client()?
472            .hget(key, field)
473            .await
474            .map_err(BaseError::RedisOperationFailed)
475    }
476
477    /// 删除 Hash 字段
478    ///
479    /// # 参数
480    ///
481    /// - `key`: 键名
482    /// - `fields`: 字段名列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
483    ///
484    /// # 返回
485    ///
486    /// - `Ok(i64)`: 删除的字段数量
487    /// - `Err(BaseError)`: 删除失败
488    ///
489    /// # 错误
490    ///
491    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
492    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
493    pub async fn hdel(
494        key: impl Into<String>,
495        fields: &[impl AsRef<str>],
496    ) -> Result<i64, BaseError> {
497        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
498        let fields_vec: Vec<String> = fields.iter().map(|f| f.as_ref().to_string()).collect();
499        Self::client()?
500            .hdel(key, &fields_vec)
501            .await
502            .map_err(BaseError::RedisOperationFailed)
503    }
504
505    /// 获取 Hash 所有字段和值
506    ///
507    /// # 参数
508    ///
509    /// - `key`: 键名
510    ///
511    /// # 返回
512    ///
513    /// - `Ok(Vec<(String, String)>)`: 所有字段和值的列表
514    /// - `Err(BaseError)`: 获取失败
515    ///
516    /// # 错误
517    ///
518    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
519    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
520    pub async fn hgetall(key: impl Into<String>) -> Result<Vec<(String, String)>, BaseError> {
521        Self::client()?
522            .hgetall(key)
523            .await
524            .map_err(BaseError::RedisOperationFailed)
525    }
526
527    /// 检查 Hash 字段是否存在
528    ///
529    /// # 参数
530    ///
531    /// - `key`: 键名
532    /// - `field`: 字段名
533    ///
534    /// # 返回
535    ///
536    /// - `Ok(bool)`: true 表示存在,false 表示不存在
537    /// - `Err(BaseError)`: 检查失败
538    ///
539    /// # 错误
540    ///
541    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
542    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
543    pub async fn hexists(
544        key: impl Into<String>,
545        field: impl Into<String>,
546    ) -> Result<bool, BaseError> {
547        Self::client()?
548            .hexists(key, field)
549            .await
550            .map_err(BaseError::RedisOperationFailed)
551    }
552
553    /// 获取 Hash 字段数量
554    ///
555    /// # 参数
556    ///
557    /// - `key`: 键名
558    ///
559    /// # 返回
560    ///
561    /// - `Ok(i64)`: 字段数量
562    /// - `Err(BaseError)`: 获取失败
563    ///
564    /// # 错误
565    ///
566    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
567    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
568    pub async fn hlen(key: impl Into<String>) -> Result<i64, BaseError> {
569        Self::client()?
570            .hlen(key)
571            .await
572            .map_err(BaseError::RedisOperationFailed)
573    }
574
575    // ==================== List 操作 ====================
576
577    /// 从列表左侧推入元素
578    ///
579    /// # 参数
580    ///
581    /// - `key`: 键名
582    /// - `values`: 值列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
583    ///
584    /// # 返回
585    ///
586    /// - `Ok(i64)`: 推入后列表长度
587    /// - `Err(BaseError)`: 推入失败
588    ///
589    /// # 错误
590    ///
591    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
592    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
593    pub async fn lpush(
594        key: impl Into<String>,
595        values: &[impl AsRef<str>],
596    ) -> Result<i64, BaseError> {
597        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
598        let values_vec: Vec<String> = values.iter().map(|v| v.as_ref().to_string()).collect();
599        Self::client()?
600            .lpush(key, &values_vec)
601            .await
602            .map_err(BaseError::RedisOperationFailed)
603    }
604
605    /// 从列表右侧推入元素
606    ///
607    /// # 参数
608    ///
609    /// - `key`: 键名
610    /// - `values`: 值列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
611    ///
612    /// # 返回
613    ///
614    /// - `Ok(i64)`: 推入后列表长度
615    /// - `Err(BaseError)`: 推入失败
616    ///
617    /// # 错误
618    ///
619    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
620    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
621    pub async fn rpush(
622        key: impl Into<String>,
623        values: &[impl AsRef<str>],
624    ) -> Result<i64, BaseError> {
625        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
626        let values_vec: Vec<String> = values.iter().map(|v| v.as_ref().to_string()).collect();
627        Self::client()?
628            .rpush(key, &values_vec)
629            .await
630            .map_err(BaseError::RedisOperationFailed)
631    }
632
633    /// 从列表左侧弹出元素
634    ///
635    /// # 参数
636    ///
637    /// - `key`: 键名
638    ///
639    /// # 返回
640    ///
641    /// - `Ok(Some(String))`: 弹出的元素
642    /// - `Ok(None)`: 列表为空
643    /// - `Err(BaseError)`: 弹出失败
644    ///
645    /// # 错误
646    ///
647    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
648    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
649    pub async fn lpop(key: impl Into<String>) -> Result<Option<String>, BaseError> {
650        Self::client()?
651            .lpop(key)
652            .await
653            .map_err(BaseError::RedisOperationFailed)
654    }
655
656    /// 从列表右侧弹出元素
657    ///
658    /// # 参数
659    ///
660    /// - `key`: 键名
661    ///
662    /// # 返回
663    ///
664    /// - `Ok(Some(String))`: 弹出的元素
665    /// - `Ok(None)`: 列表为空
666    /// - `Err(BaseError)`: 弹出失败
667    ///
668    /// # 错误
669    ///
670    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
671    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
672    pub async fn rpop(key: impl Into<String>) -> Result<Option<String>, BaseError> {
673        Self::client()?
674            .rpop(key)
675            .await
676            .map_err(BaseError::RedisOperationFailed)
677    }
678
679    /// 获取列表长度
680    ///
681    /// # 参数
682    ///
683    /// - `key`: 键名
684    ///
685    /// # 返回
686    ///
687    /// - `Ok(i64)`: 列表长度
688    /// - `Err(BaseError)`: 获取失败
689    ///
690    /// # 错误
691    ///
692    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
693    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
694    pub async fn llen(key: impl Into<String>) -> Result<i64, BaseError> {
695        Self::client()?
696            .llen(key)
697            .await
698            .map_err(BaseError::RedisOperationFailed)
699    }
700
701    /// 获取列表指定范围的元素
702    ///
703    /// # 参数
704    ///
705    /// - `key`: 键名
706    /// - `start`: 起始索引(0 表示第一个元素)
707    /// - `stop`: 结束索引(-1 表示最后一个元素)
708    ///
709    /// # 返回
710    ///
711    /// - `Ok(Vec<String>)`: 元素列表
712    /// - `Err(BaseError)`: 获取失败
713    ///
714    /// # 错误
715    ///
716    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
717    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
718    pub async fn lrange(
719        key: impl Into<String>,
720        start: i64,
721        stop: i64,
722    ) -> Result<Vec<String>, BaseError> {
723        Self::client()?
724            .lrange(key, start, stop)
725            .await
726            .map_err(BaseError::RedisOperationFailed)
727    }
728
729    // ==================== Set 操作 ====================
730
731    /// 向集合添加成员
732    ///
733    /// # 参数
734    ///
735    /// - `key`: 键名
736    /// - `members`: 成员列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
737    ///
738    /// # 返回
739    ///
740    /// - `Ok(i64)`: 添加的成员数量
741    /// - `Err(BaseError)`: 添加失败
742    ///
743    /// # 错误
744    ///
745    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
746    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
747    pub async fn sadd(
748        key: impl Into<String>,
749        members: &[impl AsRef<str>],
750    ) -> Result<i64, BaseError> {
751        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
752        let members_vec: Vec<String> = members.iter().map(|m| m.as_ref().to_string()).collect();
753        Self::client()?
754            .sadd(key, &members_vec)
755            .await
756            .map_err(BaseError::RedisOperationFailed)
757    }
758
759    /// 从集合移除成员
760    ///
761    /// # 参数
762    ///
763    /// - `key`: 键名
764    /// - `members`: 成员列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
765    ///
766    /// # 返回
767    ///
768    /// - `Ok(i64)`: 移除的成员数量
769    /// - `Err(BaseError)`: 移除失败
770    ///
771    /// # 错误
772    ///
773    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
774    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
775    pub async fn srem(
776        key: impl Into<String>,
777        members: &[impl AsRef<str>],
778    ) -> Result<i64, BaseError> {
779        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
780        let members_vec: Vec<String> = members.iter().map(|m| m.as_ref().to_string()).collect();
781        Self::client()?
782            .srem(key, &members_vec)
783            .await
784            .map_err(BaseError::RedisOperationFailed)
785    }
786
787    /// 检查成员是否在集合中
788    ///
789    /// # 参数
790    ///
791    /// - `key`: 键名
792    /// - `member`: 成员
793    ///
794    /// # 返回
795    ///
796    /// - `Ok(bool)`: true 表示存在,false 表示不存在
797    /// - `Err(BaseError)`: 检查失败
798    ///
799    /// # 错误
800    ///
801    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
802    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
803    pub async fn sismember(
804        key: impl Into<String>,
805        member: impl Into<String>,
806    ) -> Result<bool, BaseError> {
807        Self::client()?
808            .sismember(key, member)
809            .await
810            .map_err(BaseError::RedisOperationFailed)
811    }
812
813    /// 获取集合所有成员
814    ///
815    /// # 参数
816    ///
817    /// - `key`: 键名
818    ///
819    /// # 返回
820    ///
821    /// - `Ok(Vec<String>)`: 成员列表
822    /// - `Err(BaseError)`: 获取失败
823    ///
824    /// # 错误
825    ///
826    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
827    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
828    pub async fn smembers(key: impl Into<String>) -> Result<Vec<String>, BaseError> {
829        Self::client()?
830            .smembers(key)
831            .await
832            .map_err(BaseError::RedisOperationFailed)
833    }
834
835    /// 获取集合成员数量
836    ///
837    /// # 参数
838    ///
839    /// - `key`: 键名
840    ///
841    /// # 返回
842    ///
843    /// - `Ok(i64)`: 成员数量
844    /// - `Err(BaseError)`: 获取失败
845    ///
846    /// # 错误
847    ///
848    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
849    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
850    pub async fn scard(key: impl Into<String>) -> Result<i64, BaseError> {
851        Self::client()?
852            .scard(key)
853            .await
854            .map_err(BaseError::RedisOperationFailed)
855    }
856
857    // ==================== Sorted Set 操作 ====================
858
859    /// 向有序集合添加成员
860    ///
861    /// # 参数
862    ///
863    /// - `key`: 键名
864    /// - `members`: 成员和分数列表 (score, member)
865    ///
866    /// # 返回
867    ///
868    /// - `Ok(i64)`: 添加的成员数量
869    /// - `Err(BaseError)`: 添加失败
870    ///
871    /// # 错误
872    ///
873    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
874    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
875    pub async fn zadd(key: impl Into<String>, members: &[(f64, String)]) -> Result<i64, BaseError> {
876        Self::client()?
877            .zadd(key, members)
878            .await
879            .map_err(BaseError::RedisOperationFailed)
880    }
881
882    /// 从有序集合移除成员
883    ///
884    /// # 参数
885    ///
886    /// - `key`: 键名
887    /// - `members`: 成员列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
888    ///
889    /// # 返回
890    ///
891    /// - `Ok(i64)`: 移除的成员数量
892    /// - `Err(BaseError)`: 移除失败
893    ///
894    /// # 错误
895    ///
896    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
897    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
898    pub async fn zrem(
899        key: impl Into<String>,
900        members: &[impl AsRef<str>],
901    ) -> Result<i64, BaseError> {
902        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
903        let members_vec: Vec<String> = members.iter().map(|m| m.as_ref().to_string()).collect();
904        Self::client()?
905            .zrem(key, &members_vec)
906            .await
907            .map_err(BaseError::RedisOperationFailed)
908    }
909
910    /// 获取有序集合成员数量
911    ///
912    /// # 参数
913    ///
914    /// - `key`: 键名
915    ///
916    /// # 返回
917    ///
918    /// - `Ok(i64)`: 成员数量
919    /// - `Err(BaseError)`: 获取失败
920    ///
921    /// # 错误
922    ///
923    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
924    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
925    pub async fn zcard(key: impl Into<String>) -> Result<i64, BaseError> {
926        Self::client()?
927            .zcard(key)
928            .await
929            .map_err(BaseError::RedisOperationFailed)
930    }
931
932    /// 获取有序集合指定范围的成员(按分数从小到大)
933    ///
934    /// # 参数
935    ///
936    /// - `key`: 键名
937    /// - `start`: 起始索引
938    /// - `stop`: 结束索引
939    ///
940    /// # 返回
941    ///
942    /// - `Ok(Vec<String>)`: 成员列表
943    /// - `Err(BaseError)`: 获取失败
944    ///
945    /// # 错误
946    ///
947    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
948    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
949    pub async fn zrange(
950        key: impl Into<String>,
951        start: i64,
952        stop: i64,
953    ) -> Result<Vec<String>, BaseError> {
954        Self::client()?
955            .zrange(key, start, stop)
956            .await
957            .map_err(BaseError::RedisOperationFailed)
958    }
959
960    // ==================== 新增 API:String 计数器操作 ====================
961
962    /// 将键的整数值增加 1(INCR)
963    ///
964    /// # 参数
965    ///
966    /// - `key`: 键名
967    ///
968    /// # 返回
969    ///
970    /// - `Ok(i64)`: 增加后的值
971    /// - `Err(BaseError)`: 操作失败
972    ///
973    /// # 错误
974    ///
975    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
976    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败(如值不是整数)
977    pub async fn incr(key: impl Into<String>) -> Result<i64, BaseError> {
978        Self::client()?
979            .incr(key)
980            .await
981            .map_err(BaseError::RedisOperationFailed)
982    }
983
984    /// 将键的整数值减少 1(DECR)
985    ///
986    /// # 参数
987    ///
988    /// - `key`: 键名
989    ///
990    /// # 返回
991    ///
992    /// - `Ok(i64)`: 减少后的值
993    /// - `Err(BaseError)`: 操作失败
994    ///
995    /// # 错误
996    ///
997    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
998    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败(如值不是整数)
999    pub async fn decr(key: impl Into<String>) -> Result<i64, BaseError> {
1000        Self::client()?
1001            .decr(key)
1002            .await
1003            .map_err(BaseError::RedisOperationFailed)
1004    }
1005
1006    /// 将键的整数值增加指定数量(INCRBY)
1007    ///
1008    /// # 参数
1009    ///
1010    /// - `key`: 键名
1011    /// - `increment`: 增量(可为负数)
1012    ///
1013    /// # 返回
1014    ///
1015    /// - `Ok(i64)`: 增加后的值
1016    /// - `Err(BaseError)`: 操作失败
1017    ///
1018    /// # 错误
1019    ///
1020    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1021    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败(如值不是整数)
1022    pub async fn incrby(key: impl Into<String>, increment: i64) -> Result<i64, BaseError> {
1023        Self::client()?
1024            .incrby(key, increment)
1025            .await
1026            .map_err(BaseError::RedisOperationFailed)
1027    }
1028
1029    /// 将键的整数值减少指定数量(DECRBY)
1030    ///
1031    /// # 参数
1032    ///
1033    /// - `key`: 键名
1034    /// - `decrement`: 减量(可为负数)
1035    ///
1036    /// # 返回
1037    ///
1038    /// - `Ok(i64)`: 减少后的值
1039    /// - `Err(BaseError)`: 操作失败
1040    ///
1041    /// # 错误
1042    ///
1043    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1044    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败(如值不是整数)
1045    pub async fn decrby(key: impl Into<String>, decrement: i64) -> Result<i64, BaseError> {
1046        Self::client()?
1047            .decrby(key, decrement)
1048            .await
1049            .map_err(BaseError::RedisOperationFailed)
1050    }
1051
1052    /// 将键的浮点数值增加指定数量(INCRBYFLOAT)
1053    ///
1054    /// # 参数
1055    ///
1056    /// - `key`: 键名
1057    /// - `increment`: 增量(可为负数)
1058    ///
1059    /// # 返回
1060    ///
1061    /// - `Ok(f64)`: 增加后的值
1062    /// - `Err(BaseError)`: 操作失败
1063    ///
1064    /// # 错误
1065    ///
1066    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1067    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败(如值不是合法浮点数)
1068    pub async fn incrbyfloat(key: impl Into<String>, increment: f64) -> Result<f64, BaseError> {
1069        Self::client()?
1070            .incrbyfloat(key, increment)
1071            .await
1072            .map_err(BaseError::RedisOperationFailed)
1073    }
1074
1075    // ==================== 新增 API:Hash 计数器操作 ====================
1076
1077    /// 将 Hash 字段的整数值增加指定数量(HINCRBY)
1078    ///
1079    /// # 参数
1080    ///
1081    /// - `key`: 键名
1082    /// - `field`: 字段名
1083    /// - `increment`: 增量(可为负数)
1084    ///
1085    /// # 返回
1086    ///
1087    /// - `Ok(i64)`: 增加后的值
1088    /// - `Err(BaseError)`: 操作失败
1089    ///
1090    /// # 错误
1091    ///
1092    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1093    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败(如字段值不是整数)
1094    pub async fn hincrby(
1095        key: impl Into<String>,
1096        field: impl Into<String>,
1097        increment: i64,
1098    ) -> Result<i64, BaseError> {
1099        Self::client()?
1100            .hincrby(key, field, increment)
1101            .await
1102            .map_err(BaseError::RedisOperationFailed)
1103    }
1104
1105    /// 将 Hash 字段的浮点数值增加指定数量(HINCRBYFLOAT)
1106    ///
1107    /// # 参数
1108    ///
1109    /// - `key`: 键名
1110    /// - `field`: 字段名
1111    /// - `increment`: 增量(可为负数)
1112    ///
1113    /// # 返回
1114    ///
1115    /// - `Ok(f64)`: 增加后的值
1116    /// - `Err(BaseError)`: 操作失败
1117    ///
1118    /// # 错误
1119    ///
1120    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1121    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败(如字段值不是合法浮点数)
1122    pub async fn hincrbyfloat(
1123        key: impl Into<String>,
1124        field: impl Into<String>,
1125        increment: f64,
1126    ) -> Result<f64, BaseError> {
1127        Self::client()?
1128            .hincrbyfloat(key, field, increment)
1129            .await
1130            .map_err(BaseError::RedisOperationFailed)
1131    }
1132
1133    // ==================== 新增 API:批量 String 操作 ====================
1134
1135    /// 批量获取多个键的值(MGET)
1136    ///
1137    /// # 参数
1138    ///
1139    /// - `keys`: 键名列表,支持 `&[&str]`、`&[String]`、`&[&String]` 等多种形式
1140    ///
1141    /// # 返回
1142    ///
1143    /// - `Ok(Vec<Option<String>>)`: 各键对应的值,不存在的键返回 `None`
1144    /// - `Err(BaseError)`: 操作失败
1145    ///
1146    /// # 错误
1147    ///
1148    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1149    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
1150    pub async fn mget(keys: &[impl AsRef<str>]) -> Result<Vec<Option<String>>, BaseError> {
1151        // 将 &[impl AsRef<str>] 转换为 Vec<String> 以调用 yang-db
1152        let keys_vec: Vec<String> = keys.iter().map(|k| k.as_ref().to_string()).collect();
1153        Self::client()?
1154            .mget(&keys_vec)
1155            .await
1156            .map_err(BaseError::RedisOperationFailed)
1157    }
1158
1159    /// 批量设置多个键值对(MSET)
1160    ///
1161    /// # 参数
1162    ///
1163    /// - `pairs`: 键值对数组,每个元素为 `(key, value)` 元组
1164    ///
1165    /// # 返回
1166    ///
1167    /// - `Ok(())`: 设置成功
1168    /// - `Err(BaseError)`: 操作失败
1169    ///
1170    /// # 错误
1171    ///
1172    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1173    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
1174    pub async fn mset(pairs: &[(String, String)]) -> Result<(), BaseError> {
1175        Self::client()?
1176            .mset(pairs)
1177            .await
1178            .map_err(BaseError::RedisOperationFailed)
1179    }
1180
1181    // ==================== 新增 API:有序集合扩展操作 ====================
1182
1183    /// 获取有序集合指定范围的成员及其分数(ZRANGE WITHSCORES)
1184    ///
1185    /// # 参数
1186    ///
1187    /// - `key`: 键名
1188    /// - `start`: 起始索引
1189    /// - `stop`: 结束索引
1190    ///
1191    /// # 返回
1192    ///
1193    /// - `Ok(Vec<(String, f64)>)`: 成员和分数的元组列表(从低分到高分排序)
1194    /// - `Err(BaseError)`: 获取失败
1195    ///
1196    /// # 错误
1197    ///
1198    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1199    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
1200    pub async fn zrange_with_scores(
1201        key: impl Into<String>,
1202        start: i64,
1203        stop: i64,
1204    ) -> Result<Vec<(String, f64)>, BaseError> {
1205        Self::client()?
1206            .zrange_with_scores(key, start, stop)
1207            .await
1208            .map_err(BaseError::RedisOperationFailed)
1209    }
1210
1211    /// 按索引范围从高到低获取有序集合的成员(ZREVRANGE)
1212    ///
1213    /// # 参数
1214    ///
1215    /// - `key`: 键名
1216    /// - `start`: 起始索引
1217    /// - `stop`: 结束索引
1218    ///
1219    /// # 返回
1220    ///
1221    /// - `Ok(Vec<String>)`: 成员列表(从高分到低分排序)
1222    /// - `Err(BaseError)`: 获取失败
1223    ///
1224    /// # 错误
1225    ///
1226    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1227    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
1228    pub async fn zrevrange(
1229        key: impl Into<String>,
1230        start: i64,
1231        stop: i64,
1232    ) -> Result<Vec<String>, BaseError> {
1233        Self::client()?
1234            .zrevrange(key, start, stop)
1235            .await
1236            .map_err(BaseError::RedisOperationFailed)
1237    }
1238
1239    /// 将有序集合成员的分数增加指定数量(ZINCRBY)
1240    ///
1241    /// # 参数
1242    ///
1243    /// - `key`: 键名
1244    /// - `increment`: 增量(可为负数)
1245    /// - `member`: 成员
1246    ///
1247    /// # 返回
1248    ///
1249    /// - `Ok(f64)`: 增加后的分数
1250    /// - `Err(BaseError)`: 操作失败
1251    ///
1252    /// # 错误
1253    ///
1254    /// - `BaseError::RedisNotInitialized`: Redis 未初始化,需要先调用 `init` 方法
1255    /// - `BaseError::RedisOperationFailed`: Redis 命令执行失败
1256    pub async fn zincrby(
1257        key: impl Into<String>,
1258        increment: f64,
1259        member: impl Into<String>,
1260    ) -> Result<f64, BaseError> {
1261        Self::client()?
1262            .zincrby(key, increment, member)
1263            .await
1264            .map_err(BaseError::RedisOperationFailed)
1265    }
1266
1267    // ==================== Pipeline / Transaction 入口 ====================
1268
1269    /// 获取 Redis 事务对象
1270    ///
1271    /// 返回 `yang_db::redis::RedisTransaction`,支持 WATCH/MULTI/EXEC 乐观锁事务。
1272    ///
1273    /// # 返回
1274    ///
1275    /// - `Ok(RedisTransaction)`: 事务对象
1276    /// - `Err(BaseError)`: Redis 未初始化
1277    ///
1278    /// # 说明
1279    ///
1280    /// 事务支持链式调用,可在事务中执行多个命令。
1281    /// 如需使用 Pipeline 批量操作,可通过 `GlobalRedis::client()?.pipeline()` 获取。
1282    /// 如需执行 Lua 脚本,可通过 `GlobalRedis::client()?.script(code)` 创建脚本对象。
1283    ///
1284    /// # 示例
1285    ///
1286    /// ```rust,ignore
1287    /// // 基础事务
1288    /// let mut tx = GlobalRedis::transaction()?;
1289    /// tx.set("key1", "value1")
1290    ///   .set("key2", "value2")
1291    ///   .incr("counter");
1292    /// let results: (String, String, i64) = tx.exec().await?;
1293    ///
1294    /// // 乐观锁事务
1295    /// let mut tx = GlobalRedis::transaction()?;
1296    /// tx.watch(&["balance".to_string()]);
1297    /// tx.set("balance", "900");
1298    /// let result: (String,) = tx.exec().await?;
1299    ///
1300    /// // Pipeline 批量操作
1301    /// let mut pipeline = GlobalRedis::client()?.pipeline();
1302    /// pipeline.set("k1", "v1").set("k2", "v2");
1303    /// let results = pipeline.execute().await?;
1304    /// ```
1305    pub fn transaction() -> Result<RedisTransaction, BaseError> {
1306        // 通过全局客户端创建事务对象
1307        Ok(Self::client()?.transaction())
1308    }
1309}
1310
1311#[cfg(test)]
1312mod tests {
1313    use super::*;
1314
1315    #[test]
1316    fn test_redis_not_initialized() {
1317        // 测试未初始化时获取 Redis 实例
1318        let result = GlobalRedis::client();
1319        assert!(result.is_err());
1320        assert!(matches!(result, Err(BaseError::RedisNotInitialized)));
1321    }
1322
1323    #[test]
1324    fn test_transaction_not_initialized() {
1325        // 测试未初始化时获取事务对象应返回错误
1326        let result = GlobalRedis::transaction();
1327        assert!(result.is_err());
1328        assert!(matches!(result, Err(BaseError::RedisNotInitialized)));
1329    }
1330}