Initial WhaleTown V2 backend
This commit is contained in:
294
src/core/redis/redis.interface.ts
Normal file
294
src/core/redis/redis.interface.ts
Normal file
@@ -0,0 +1,294 @@
|
||||
/**
|
||||
* Redis服务接口定义
|
||||
*
|
||||
* 功能描述：
|
||||
* - 定义统一的Redis操作接口规范
|
||||
* - 支持文件存储和真实Redis服务的无缝切换
|
||||
* - 提供完整的Redis基础操作方法
|
||||
* - 支持键值对存储、过期时间、集合操作等功能
|
||||
*
|
||||
* 职责分离：
|
||||
* - 接口定义：规范Redis服务的标准操作方法
|
||||
* - 类型约束：确保不同实现类的方法签名一致性
|
||||
* - 抽象层：为上层业务提供统一的Redis访问接口
|
||||
*
|
||||
* 最近修改：
|
||||
* - 2025-01-07: 代码规范优化 - 为所有接口方法添加完整的三级注释，包含业务逻辑和示例代码
|
||||
* - 2025-01-07: 代码规范优化 - 完善文件头注释，添加详细的功能描述和职责说明
|
||||
*
|
||||
* @author moyin
|
||||
* @version 1.0.2
|
||||
* @since 2025-01-07
|
||||
* @lastModified 2025-01-07
|
||||
*/
|
||||
export interface IRedisService {
|
||||
/**
|
||||
* 设置键值对
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键和值的有效性
|
||||
* 2. 根据TTL参数决定是否设置过期时间
|
||||
* 3. 存储键值对到Redis
|
||||
* 4. 记录操作日志
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @param value 值，支持字符串类型
|
||||
* @param ttl 可选的过期时间（秒），不设置则永不过期
|
||||
* @returns Promise<void> 操作完成的Promise
|
||||
* @throws Error 当键名为空或存储失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await redisService.set('user:123', 'userData', 3600);
|
||||
* await redisService.set('config', 'value'); // 永不过期
|
||||
* ```
|
||||
*/
|
||||
set(key: string, value: string, ttl?: number): Promise<void>;
|
||||
|
||||
/**
|
||||
* 设置键值对并指定过期时间
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键、值和TTL参数的有效性
|
||||
* 2. 设置键值对并同时设置过期时间
|
||||
* 3. 记录操作日志
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @param ttl 过期时间（秒），必须大于0
|
||||
* @param value 值，支持字符串类型
|
||||
* @returns Promise<void> 操作完成的Promise
|
||||
* @throws Error 当参数无效或存储失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await redisService.setex('session:abc', 1800, 'sessionData');
|
||||
* ```
|
||||
*/
|
||||
setex(key: string, ttl: number, value: string): Promise<void>;
|
||||
|
||||
/**
|
||||
* 获取键对应的值
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名的有效性
|
||||
* 2. 从Redis中查找对应的值
|
||||
* 3. 检查键是否存在或已过期
|
||||
* 4. 返回值或null
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @returns Promise<string | null> 键对应的值，不存在或已过期返回null
|
||||
* @throws Error 当键名为空或查询失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const value = await redisService.get('user:123');
|
||||
* if (value !== null) {
|
||||
* console.log('用户数据:', value);
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
get(key: string): Promise<string | null>;
|
||||
|
||||
/**
|
||||
* 删除指定的键
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名的有效性
|
||||
* 2. 从Redis中删除指定键
|
||||
* 3. 返回删除操作的结果
|
||||
* 4. 记录删除操作日志
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @returns Promise<boolean> 删除成功返回true，键不存在返回false
|
||||
* @throws Error 当键名为空或删除失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const deleted = await redisService.del('user:123');
|
||||
* console.log(deleted ? '删除成功' : '键不存在');
|
||||
* ```
|
||||
*/
|
||||
del(key: string): Promise<boolean>;
|
||||
|
||||
/**
|
||||
* 检查键是否存在
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名的有效性
|
||||
* 2. 查询Redis中是否存在该键
|
||||
* 3. 检查键是否已过期
|
||||
* 4. 返回存在性检查结果
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @returns Promise<boolean> 键存在返回true，不存在或已过期返回false
|
||||
* @throws Error 当键名为空或查询失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const exists = await redisService.exists('user:123');
|
||||
* if (exists) {
|
||||
* console.log('用户数据存在');
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
exists(key: string): Promise<boolean>;
|
||||
|
||||
/**
|
||||
* 设置键的过期时间
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名和TTL参数的有效性
|
||||
* 2. 为现有键设置过期时间
|
||||
* 3. 记录过期时间设置日志
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @param ttl 过期时间（秒），必须大于0
|
||||
* @returns Promise<void> 操作完成的Promise
|
||||
* @throws Error 当参数无效或设置失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await redisService.expire('user:123', 3600); // 1小时后过期
|
||||
* ```
|
||||
*/
|
||||
expire(key: string, ttl: number): Promise<void>;
|
||||
|
||||
/**
|
||||
* 获取键的剩余过期时间
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名的有效性
|
||||
* 2. 查询键的剩余过期时间
|
||||
* 3. 返回相应的时间值或状态码
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @returns Promise<number> 剩余时间（秒），-1表示永不过期，-2表示键不存在
|
||||
* @throws Error 当键名为空或查询失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const ttl = await redisService.ttl('user:123');
|
||||
* if (ttl > 0) {
|
||||
* console.log(`还有${ttl}秒过期`);
|
||||
* } else if (ttl === -1) {
|
||||
* console.log('永不过期');
|
||||
* } else {
|
||||
* console.log('键不存在');
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
ttl(key: string): Promise<number>;
|
||||
|
||||
/**
|
||||
* 键值自增操作
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名的有效性
|
||||
* 2. 获取当前值并转换为数字
|
||||
* 3. 执行自增操作（+1）
|
||||
* 4. 返回自增后的新值
|
||||
*
|
||||
* @param key 键名，不能为空
|
||||
* @returns Promise<number> 自增后的新值
|
||||
* @throws Error 当键名为空、值不是数字或操作失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const newValue = await redisService.incr('counter');
|
||||
* console.log(`计数器新值: ${newValue}`);
|
||||
* ```
|
||||
*/
|
||||
incr(key: string): Promise<number>;
|
||||
|
||||
/**
|
||||
* 向集合添加成员
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名和成员的有效性
|
||||
* 2. 获取现有集合或创建新集合
|
||||
* 3. 添加成员到集合中
|
||||
* 4. 保存更新后的集合
|
||||
*
|
||||
* @param key 集合键名，不能为空
|
||||
* @param member 要添加的成员，不能为空
|
||||
* @returns Promise<void> 操作完成的Promise
|
||||
* @throws Error 当参数无效或操作失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await redisService.sadd('users', 'user123');
|
||||
* ```
|
||||
*/
|
||||
sadd(key: string, member: string): Promise<void>;
|
||||
|
||||
/**
|
||||
* 从集合移除成员
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名和成员的有效性
|
||||
* 2. 获取现有集合
|
||||
* 3. 从集合中移除指定成员
|
||||
* 4. 保存更新后的集合或删除空集合
|
||||
*
|
||||
* @param key 集合键名，不能为空
|
||||
* @param member 要移除的成员，不能为空
|
||||
* @returns Promise<void> 操作完成的Promise
|
||||
* @throws Error 当参数无效或操作失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await redisService.srem('users', 'user123');
|
||||
* ```
|
||||
*/
|
||||
srem(key: string, member: string): Promise<void>;
|
||||
|
||||
/**
|
||||
* 获取集合的所有成员
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证键名的有效性
|
||||
* 2. 获取集合数据
|
||||
* 3. 检查集合是否存在或已过期
|
||||
* 4. 返回成员列表
|
||||
*
|
||||
* @param key 集合键名，不能为空
|
||||
* @returns Promise<string[]> 集合成员列表，集合不存在返回空数组
|
||||
* @throws Error 当键名为空或查询失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const members = await redisService.smembers('users');
|
||||
* console.log('用户列表:', members);
|
||||
* ```
|
||||
*/
|
||||
smembers(key: string): Promise<string[]>;
|
||||
|
||||
/**
|
||||
* 查找匹配模式的键
|
||||
*
|
||||
* 仅用于低频维护任务，例如在删除账号时清理关联的临时数据。
|
||||
*
|
||||
* @param pattern Redis glob 模式
|
||||
* @returns 匹配的键名列表
|
||||
*/
|
||||
keys(pattern: string): Promise<string[]>;
|
||||
|
||||
/**
|
||||
* 清空所有数据
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 清空Redis中的所有键值对
|
||||
* 2. 重置所有数据结构
|
||||
* 3. 记录清空操作日志
|
||||
*
|
||||
* @returns Promise<void> 操作完成的Promise
|
||||
* @throws Error 当清空操作失败时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* await redisService.flushall();
|
||||
* console.log('所有数据已清空');
|
||||
* ```
|
||||
*/
|
||||
flushall(): Promise<void>;
|
||||
}
|
||||
Reference in New Issue
Block a user