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}