whale-town-end-v2/src/core/redis/redis.interface.ts

/**
 * 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>;

  /**
   * 仅当键不存在时设置值，用于 nonce、幂等键等原子占位。
   *
   * @returns 成功占位返回 true，键已存在返回 false
   */
  setIfAbsent(key: string, value: string, ttl?: number): Promise<boolean>;

  /**
   * 设置键值对并指定过期时间
   *
   * 业务逻辑：
   * 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>;
}