feature: redis cache class 추가와 jsdocs 추가

Author: Nuung

src/modules/cache/cache.type.ts

@@ -1,30 +1,80 @@
+/**
+ * 캐시 설정 옵션입니다.
+ *
+ * @property host 캐시 서버의 호스트명 또는 IP 주소
+ * @property port 캐시 서버의 포트 번호
+ * @property [password] 캐시 서버 인증 비밀번호(선택)
+ * @property [db] 사용할 데이터베이스 인덱스(선택)
+ * @property [keyPrefix] 모든 키에 붙일 접두사(선택)
+ * @property [defaultTTL] 기본 만료 시간(초, 선택)
+ */
 export interface CacheConfig {
   host: string;
   port: number;
   password?: string;
   db?: number;
   keyPrefix?: string;
-  maxSize?: number;
   defaultTTL?: number;
-  strategy?: 'lru' | 'ttl' | 'combined';
-}
-
-export interface CacheMetadata {
-  key: string;
-  size: number;
-  createdAt: number;
-  lastAccessed: number;
-  accessCount: number;
-  ttl?: number;
-  expiresAt?: number;
 }
 
+/**
+ * 캐시 서비스 인터페이스입니다.
+ */
 export interface ICache {
+  /**
+   * 키로부터 값을 가져옵니다.
+   * @param key 값을 가져올 키
+   * @returns 값을 반환하거나 없으면 null을 반환합니다.
+   */
   get<T>(key: string): Promise<T | null>;
+
+  /**
+   * 값을 캐시에 저장합니다.
+   * @param key 저장할 키
+   * @param value 저장할 값
+   * @param ttlSeconds 값의 만료 시간(초, 선택)
+   */
   set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+
+  /**
+   * 키에 해당하는 값을 삭제합니다.
+   * @param key 삭제할 키
+   * @returns 삭제 성공 여부를 반환합니다.
+   */
   delete(key: string): Promise<boolean>;
+
+  /**
+   * 키가 존재하는지 확인합니다.
+   * @param key 확인할 키
+   * @returns 존재하면 true, 아니면 false를 반환합니다.
+   */
   exists(key: string): Promise<boolean>;
+
+  /**
+   * 캐시를 비웁니다. 패턴이 있으면 해당 키만 비웁니다.
+   * @param pattern 비울 키의 패턴(선택)
+   */
   clear(pattern?: string): Promise<void>;
+
+  /**
+   * 캐시에 저장된 항목 개수를 반환합니다.
+   * @returns 항목 개수
+   */
   size(): Promise<number>;
-}
 
+  /**
+   * 캐시 서버에 연결합니다.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * 캐시 서버와 연결을 끊습니다.
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * 캐시 서버와 연결되어 있는지 확인합니다.
+   * @returns 연결되어 있으면 true, 아니면 false
+   */
+  isConnected(): boolean;
+}

src/modules/cache/redis.cache.ts

@@ -0,0 +1,190 @@
+import { createClient, RedisClientType } from 'redis';
+
+import logger from '@/configs/logger.config';
+import { ICache, CacheConfig } from './cache.type';
+
+export class RedisCache implements ICache {
+  private client: RedisClientType;
+  private connected: boolean = false;
+  private keyPrefix: string;
+  private defaultTTL: number;
+
+  constructor(config: CacheConfig) {
+    this.keyPrefix = config.keyPrefix || 'vd2:cache:';
+    this.defaultTTL = config.defaultTTL || 300;
+
+    this.client = createClient({
+      socket: {
+        host: config.host,
+        port: config.port,
+      },
+      password: config.password,
+      database: config.db || 0,
+    });
+
+    this.setupEventHandlers();
+  }
+
+  /**
+   * Redis 클라이언트의 이벤트 핸들러를 설정합니다.
+   * 에러, 연결, 연결 해제 시 상태를 변경하고 로그를 남깁니다.
+   *
+   * @private
+   */
+  private setupEventHandlers(): void {
+    this.client.on('error', (err) => {
+      logger.error('Redis Client Error:', err);
+      this.connected = false;
+    });
+
+    this.client.on('connect', () => {
+      logger.info('Redis Client Connected');
+      this.connected = true;
+    });
+
+    this.client.on('disconnect', () => {
+      logger.warn('Redis Client Disconnected');
+      this.connected = false;
+    });
+  }
+
+  /**
+   * 주어진 키에 keyPrefix를 접두사로 붙여 전체 Redis 키를 생성합니다.
+   *
+   * @param key - 접두사가 붙을 원본 키 문자열
+   * @returns keyPrefix가 포함된 전체 Redis 키 문자열
+   */
+  private getFullKey(key: string): string {
+    return `${this.keyPrefix}${key}`;
+  }
+
+  async connect(): Promise<void> {
+    try {
+      if (!this.connected) {
+        await this.client.connect();
+        this.connected = true;
+        logger.info('Redis cache connection established');
+      }
+    } catch (error) {
+      logger.error('Failed to connect to Redis cache:', error);
+      throw error;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    try {
+      if (this.connected) {
+        await this.client.disconnect();
+        this.connected = false;
+        logger.info('Redis cache connection closed');
+      }
+    } catch (error) {
+      logger.error('Failed to disconnect from Redis cache:', error);
+      throw error;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    try {
+      if (!this.connected) {
+        logger.warn('Redis not connected, skipping cache get');
+        return null;
+      }
+
+      const value = await this.client.get(this.getFullKey(key));
+      return value ? JSON.parse(value) : null;
+    } catch (error) {
+      logger.error(`Cache GET error for key ${key}:`, error);
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    try {
+      if (!this.connected) {
+        logger.warn('Redis not connected, skipping cache set');
+        return;
+      }
+
+      const fullKey = this.getFullKey(key);
+      const serializedValue = JSON.stringify(value);
+      const ttl = ttlSeconds ?? this.defaultTTL;
+
+      if (ttl > 0) {
+        await this.client.setEx(fullKey, ttl, serializedValue);
+      } else {
+        await this.client.set(fullKey, serializedValue);
+      }
+    } catch (error) {
+      logger.error(`Cache SET error for key ${key}:`, error);
+      // 캐시 오류 시에도 애플리케이션은 계속 동작
+    }
+  }
+
+  async delete(key: string): Promise<boolean> {
+    try {
+      if (!this.connected) {
+        logger.warn('Redis not connected, skipping cache delete');
+        return false;
+      }
+
+      const result = await this.client.del(this.getFullKey(key));
+      return result > 0;
+    } catch (error) {
+      logger.error(`Cache DELETE error for key ${key}:`, error);
+      return false;
+    }
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      if (!this.connected) {
+        return false;
+      }
+
+      const result = await this.client.exists(this.getFullKey(key));
+      return result > 0;
+    } catch (error) {
+      logger.error(`Cache EXISTS error for key ${key}:`, error);
+      return false;
+    }
+  }
+
+  async clear(pattern?: string): Promise<void> {
+    try {
+      if (!this.connected) {
+        logger.warn('Redis not connected, skipping cache clear');
+        return;
+      }
+
+      const searchPattern = pattern
+        ? `${this.keyPrefix}${pattern}`
+        : `${this.keyPrefix}*`;
+
+      const keys = await this.client.keys(searchPattern);
+      if (keys.length > 0) {
+        await this.client.del(keys);
+      }
+    } catch (error) {
+      logger.error(`Cache CLEAR error for pattern ${pattern}:`, error);
+    }
+  }
+
+  async size(): Promise<number> {
+    try {
+      if (!this.connected) {
+        return 0;
+      }
+
+      const keys = await this.client.keys(`${this.keyPrefix}*`);
+      return keys.length;
+    } catch (error) {
+      logger.error('Cache SIZE error:', error);
+      return 0;
+    }
+  }
+}