@jintianxiayu/cache-decorator 0.1.3 → 1.0.0

package/src/core/redis-cache.ts

@@ -1,56 +1,104 @@
-import { CacheProvider } from './cache-provider';
-import Redis from 'ioredis';
-
-/**
- * Redis 缓存提供者，基于 ioredis 实现
- * 适用于分布式场景，支持跨进程共享缓存
- */
-export class RedisCacheProvider implements CacheProvider {
-    private redis: Redis;
-
-    constructor(redis?: Redis) {
-        this.redis = redis ?? new Redis();
-    }
-
-    async get<T>(key: string): Promise<T | undefined> {
-        const value = await this.redis.get(key);
-        if (value === null) return undefined;
-        try {
-            return JSON.parse(value) as T;
-        } catch {
-            return value as unknown as T;
-        }
-    }
-
-    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
-        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
-        if (ttl) {
-            await this.redis.setex(key, ttl, serialized);
-        } else {
-            await this.redis.set(key, serialized);
-        }
-    }
-
-    async delete(key: string): Promise<void> {
-        await this.redis.del(key);
-    }
-
-    async clear(): Promise<void> {
-        await this.redis.flushdb();
-    }
-
-    /**
-     * 根据模式删除匹配的缓存键
-     * @param pattern glob模式字符串（如 user:*），使用 SCAN 游标迭代避免阻塞 Redis
-     */
-    async deleteByPattern(pattern: string): Promise<void> {
-        let cursor = '0';
-        do {
-            const [nextCursor, keys] = await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
-            cursor = nextCursor;
-            if (keys.length > 0) {
-                await this.redis.del(...keys);
-            }
-        } while (cursor !== '0');
-    }
-}
+import { CacheProvider } from './cache-provider';
+import { RedisCacheClient } from './redis-cache-client';
+
+/**
+ * Redis 缓存提供者，在客户端无关的字符串命令之上维护统一缓存协议。
+ * 适用于分布式场景，支持跨进程及跨客户端共享缓存。
+ */
+export class RedisCacheProvider implements CacheProvider {
+    private readonly client: RedisCacheClient;
+
+    /**
+     * 创建复用调用方 Redis 连接的缓存提供者。
+     * @param client 已适配的最小 Redis 缓存客户端。
+     */
+    constructor(client: RedisCacheClient) {
+        this.client = client;
+    }
+
+    /**
+     * 按既有协议读取并反序列化缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 解析后的业务值；Redis miss 时返回 undefined。
+     * @throws GET 命令失败时传播客户端原始错误。
+     */
+    async get<T>(key: string): Promise<T | undefined> {
+        const value = await this.client.get(key);
+        if (value === null) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(value) as T;
+        } catch {
+            // 兼容既有协议：不是合法 JSON 的字符串按原值返回。
+            return value as unknown as T;
+        }
+    }
+
+    /**
+     * 按既有字符串或 JSON 协议写入缓存值。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @param value 需要缓存的业务值。
+     * @param ttl 可选的正整数秒级 TTL；undefined 或 0 表示永不过期。
+     * @returns 写入命令成功后完成。
+     * @throws 值不能序列化时抛 TypeError，TTL 非法时抛 RangeError，命令失败时传播原始错误。
+     */
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+        const ttlSeconds = this.normalizeTtl(ttl);
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+        if (typeof serialized !== 'string') {
+            throw new TypeError('Cache value must serialize to a string');
+        }
+        if (ttlSeconds === undefined) {
+            await this.client.set({ key, value: serialized });
+            return;
+        }
+        await this.client.set({ key, value: serialized, ttlSeconds });
+    }
+
+    /**
+     * 幂等删除一个逻辑缓存键。
+     * @param key 未经 Provider 改写的逻辑缓存键。
+     * @returns 删除命令成功后完成。
+     * @throws DEL 命令失败时传播客户端原始错误。
+     */
+    async delete(key: string): Promise<void> {
+        await this.client.deleteMany([key]);
+    }
+
+    /**
+     * 清空客户端当前选择的整个 Redis 数据库。
+     * @returns FLUSHDB 命令成功后完成。
+     * @throws 清库命令失败时传播客户端原始错误。
+     */
+    async clear(): Promise<void> {
+        await this.client.flushDatabase();
+    }
+
+    /**
+     * 使用游标扫描并按页删除匹配的逻辑缓存键，避免阻塞 Redis。
+     * @param pattern 保留 glob 语义的逻辑 pattern，例如 user:*。
+     * @returns 游标归零且所有已扫描页面删除成功后完成。
+     * @throws SCAN 或任一页 DEL 失败时传播客户端原始错误，并停止后续页面。
+     */
+    async deleteByPattern(pattern: string): Promise<void> {
+        let cursor = '0';
+        do {
+            const page = await this.client.scan({ cursor, pattern, count: 100 });
+            cursor = page.cursor;
+            if (page.keys.length > 0) {
+                await this.client.deleteMany(page.keys);
+            }
+        } while (cursor !== '0');
+    }
+
+    private normalizeTtl(ttl: number | undefined): number | undefined {
+        if (ttl === undefined || ttl === 0) {
+            return undefined;
+        }
+        if (!Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl < 1) {
+            throw new RangeError('Redis cache TTL must be a positive finite integer or zero');
+        }
+        return ttl;
+    }
+}

package/src/decorators/cache-evict.ts

@@ -1,69 +1,129 @@
-import { CacheProviderRegistry } from '../core/cache-provider-registry';
-import { KeyBuilder } from '../core/key-builder';
-import { CacheOptions, CacheKeyResolver } from './cache';
-
-/**
- * @CacheEvict 装饰器配置项
- */
-export interface CacheEvictOptions extends Pick<CacheOptions, 'key'> {
-    /**
-     * 是否清除所有条目，默认为 false
-     */
-    allEntries?: boolean;
-
-    /**
-     * 指定 CacheProvider 名称
-     */
-    providerName?: string;
-}
-
-/**
- * 解析缓存 key
- * @param cacheName 缓存名称
- * @param keyResolver key 解析器
- * @param args 方法参数数组
- * @returns 解析后的缓存 key
- */
-function resolveCacheKey(cacheName: string, keyResolver: CacheKeyResolver | undefined, args: unknown[]): string {
-    if (keyResolver === undefined || keyResolver === null) {
-        return KeyBuilder.build(cacheName, args);
-    }
-    if (typeof keyResolver === 'string') {
-        return KeyBuilder.build(cacheName, [keyResolver]);
-    }
-    try {
-        return KeyBuilder.build(cacheName, [keyResolver(...args)]);
-    } catch {
-        return KeyBuilder.build(cacheName, args);
-    }
-}
-
-/**
- * 缓存清除装饰器
- * 在方法执行后清除对应的缓存条目
- * @param cacheName 缓存名称
- * @param options 配置项
- */
-export function CacheEvict(cacheName: string, options?: CacheEvictOptions) {
-    return function (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) {
-        const originalMethod = descriptor.value;
-
-        descriptor.value = async function (...args: unknown[]) {
-            const result = await originalMethod.apply(this, args);
-
-            const providerName = options?.providerName;
-            const provider = CacheProviderRegistry.get(providerName);
-
-            if (options?.allEntries) {
-                await provider.deleteByPattern(cacheName + '*');
-            } else {
-                const cacheKey = resolveCacheKey(cacheName, options?.key, args);
-                provider.delete(cacheKey);
-            }
-
-            return result;
-        };
-    };
-}
-
-export { CacheProviderRegistry } from '../core/cache-provider-registry';
+import { cacheProviderLabel, logCacheEvent, type CacheLogContext } from '../core/cache-logger';
+import type { CacheProvider } from '../core/cache-provider';
+import { CacheProviderRegistry } from '../core/cache-provider-registry';
+import { KeyBuilder } from '../core/key-builder';
+import type { CacheKeyResolver, CacheOptions } from './cache';
+
+/**
+ * @CacheEvict 装饰器配置项
+ */
+export interface CacheEvictOptions extends Pick<CacheOptions, 'key'> {
+    /**
+     * 是否清除所有条目，默认为 false
+     */
+    allEntries?: boolean;
+
+    /**
+     * 指定 CacheProvider 名称
+     */
+    providerName?: string;
+}
+
+/**
+ * 解析缓存 key
+ * @param keyResolver key 解析器
+ * @param args 方法参数数组
+ * @param logContext 不包含业务参数和值的日志上下文
+ * @returns 解析后的缓存 key
+ */
+function resolveCacheKey(
+    keyResolver: CacheKeyResolver | undefined,
+    args: unknown[],
+    logContext: CacheLogContext
+): string {
+    if (keyResolver === undefined || keyResolver === null) {
+        return KeyBuilder.build(logContext.cacheName, args);
+    }
+    if (typeof keyResolver === 'string') {
+        return KeyBuilder.build(logContext.cacheName, [keyResolver]);
+    }
+    try {
+        return KeyBuilder.build(logContext.cacheName, [keyResolver(...args)]);
+    } catch (_error) {
+        logCacheEvent('cache.key_fallback', { ...logContext, reason: 'resolver_error' });
+        return KeyBuilder.build(logContext.cacheName, args);
+    }
+}
+
+/**
+ * 获取淘汰操作使用的 Provider，并在解析失败时记录原始注册表错误。
+ * @param providerName decorator 配置中的 Provider 名称。
+ * @param logContext 当前方法的稳定日志上下文。
+ * @returns 已注册的缓存 Provider。
+ * @throws Provider 注册表抛出的原始错误。
+ */
+function resolveCacheProvider(providerName: string | undefined, logContext: CacheLogContext): CacheProvider {
+    try {
+        return CacheProviderRegistry.get(providerName);
+    } catch (error) {
+        logCacheEvent('cache.operation_failed', { ...logContext, operation: 'provider_resolution', error });
+        throw error;
+    }
+}
+
+/**
+ * 保持 fire-and-forget 语义发起单 key 删除，只处理调用当下可观察的同步失败。
+ * @param provider 当前淘汰使用的 Provider。
+ * @param cacheKey 待删除的完整 key；不会进入日志元数据。
+ * @param logContext 当前方法的稳定日志上下文。
+ * @returns 无返回值；异步删除 Promise 不会被等待或消费。
+ * @throws Provider delete 同步抛出的原始错误。
+ */
+function dispatchCacheDelete(provider: CacheProvider, cacheKey: string, logContext: CacheLogContext): void {
+    try {
+        provider.delete(cacheKey);
+    } catch (error) {
+        logCacheEvent('cache.operation_failed', { ...logContext, operation: 'evict', error });
+        throw error;
+    }
+    logCacheEvent('cache.evict_dispatched', { ...logContext, scope: 'key' });
+}
+
+/**
+ * 缓存清除装饰器
+ * 在方法执行后清除对应的缓存条目
+ * @param cacheName 缓存名称
+ * @param options 配置项
+ */
+export function CacheEvict(
+    cacheName: string,
+    options?: CacheEvictOptions
+): (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => void {
+    return function (_target: object, propertyKey: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+        const logContext: CacheLogContext = {
+            cacheName,
+            methodName: propertyKey,
+            providerName: cacheProviderLabel(options?.providerName),
+        };
+
+        descriptor.value = async function (...args: unknown[]) {
+            let result: unknown;
+            try {
+                result = await originalMethod.apply(this, args);
+            } catch (error) {
+                logCacheEvent('cache.evict_skipped', { ...logContext, reason: 'business_error' });
+                throw error;
+            }
+
+            const provider = resolveCacheProvider(options?.providerName, logContext);
+
+            if (options?.allEntries) {
+                try {
+                    await provider.deleteByPattern(cacheName + '*');
+                } catch (error) {
+                    logCacheEvent('cache.operation_failed', { ...logContext, operation: 'evict', error });
+                    throw error;
+                }
+                logCacheEvent('cache.evict_completed', { ...logContext, scope: 'allEntries' });
+            } else {
+                const cacheKey = resolveCacheKey(options?.key, args, logContext);
+                dispatchCacheDelete(provider, cacheKey, logContext);
+            }
+
+            return result;
+        };
+    };
+}
+
+export { CacheProviderRegistry } from '../core/cache-provider-registry';