@jintianxiayu/cache-decorator 0.1.3 → 1.0.1

package/src/decorators/cache-evict.ts

@@ -1,6 +1,8 @@
+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 { CacheOptions, CacheKeyResolver } from './cache';
+import type { CacheKeyResolver, CacheOptions } from './cache';
 
 /**
  * @CacheEvict 装饰器配置项
@@ -19,46 +21,104 @@ export interface CacheEvictOptions extends Pick<CacheOptions, 'key'> {
 
 /**
  * 解析缓存 key
- * @param cacheName 缓存名称
  * @param keyResolver key 解析器
  * @param args 方法参数数组
+ * @param logContext 不包含业务参数和值的日志上下文
  * @returns 解析后的缓存 key
  */
-function resolveCacheKey(cacheName: string, keyResolver: CacheKeyResolver | undefined, args: unknown[]): string {
+function resolveCacheKey(
+    keyResolver: CacheKeyResolver | undefined,
+    args: unknown[],
+    logContext: CacheLogContext
+): string {
     if (keyResolver === undefined || keyResolver === null) {
-        return KeyBuilder.build(cacheName, args);
+        return KeyBuilder.build(logContext.cacheName, args);
     }
     if (typeof keyResolver === 'string') {
-        return KeyBuilder.build(cacheName, [keyResolver]);
+        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 KeyBuilder.build(cacheName, [keyResolver(...args)]);
-    } catch {
-        return KeyBuilder.build(cacheName, args);
+        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) {
-    return function (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) {
+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[]) {
-            const result = await originalMethod.apply(this, args);
+            let result: unknown;
+            try {
+                result = await originalMethod.apply(this, args);
+            } catch (error) {
+                logCacheEvent('cache.evict_skipped', { ...logContext, reason: 'business_error' });
+                throw error;
+            }
 
-            const providerName = options?.providerName;
-            const provider = CacheProviderRegistry.get(providerName);
+            const provider = resolveCacheProvider(options?.providerName, logContext);
 
             if (options?.allEntries) {
-                await provider.deleteByPattern(cacheName + '*');
+                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(cacheName, options?.key, args);
-                provider.delete(cacheKey);
+                const cacheKey = resolveCacheKey(options?.key, args, logContext);
+                dispatchCacheDelete(provider, cacheKey, logContext);
             }
 
             return result;

package/src/decorators/cache.ts

@@ -1,4 +1,15 @@
 import 'reflect-metadata';
+import {
+    decodeCacheError,
+    encodeCacheError,
+    isCurrentCacheErrorPayload,
+    normalizeCacheErrorPolicy,
+    type CacheErrorCodec,
+    type CacheErrorPolicy,
+    type NormalizedCacheErrorPolicy,
+} from '../core/cache-error';
+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 { PendingCache } from '../core/pending-cache';
@@ -11,6 +22,8 @@ import { PendingCache } from '../core/pending-cache';
  */
 export type CacheKeyResolver = null | string | ((...args: unknown[]) => string);
 
+export type { CacheErrorCodec, CacheErrorPolicy };
+
 /**
  * @Cache 装饰器配置项
  */
@@ -32,6 +45,11 @@ export interface CacheOptions {
      * - function: 调用函数后使用 KeyBuilder.build(cacheName, [result])
      */
     key?: CacheKeyResolver;
+
+    /**
+     * 业务异常缓存策略；省略时不向 Provider 持久化业务异常。
+     */
+    errorCache?: CacheErrorPolicy;
 }
 
 /**
@@ -53,26 +71,176 @@ interface ErrorCacheEntry {
  */
 type CacheEntry<T> = SuccessCacheEntry<T> | ErrorCacheEntry;
 
+interface CacheWriteRequest<T> {
+    readonly provider: CacheProvider;
+    readonly cacheKey: string;
+    readonly entry: CacheEntry<T>;
+    readonly entryType: 'value' | 'error';
+    readonly ttl: number | undefined;
+    readonly logContext: CacheLogContext;
+}
+
+type CacheReadResult<T> =
+    | { readonly type: 'value'; readonly value: T }
+    | { readonly type: 'error'; readonly error: unknown }
+    | { readonly type: 'miss' };
+
+interface BusinessErrorRequest {
+    readonly error: unknown;
+    readonly errorPolicy: NormalizedCacheErrorPolicy | undefined;
+    readonly provider: CacheProvider;
+    readonly cacheKey: string;
+    readonly logContext: CacheLogContext;
+}
+
 const pendingCache = new PendingCache();
 
+/**
+ * 获取配置指向的缓存 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 语义提交缓存写入，仅捕获调用当下可观察的同步失败。
+ * @param request 写入所需 Provider、entry 和无业务数据日志上下文。
+ * @returns 无返回值；异步写入 Promise 不会被等待或消费。
+ * @throws Provider set 同步抛出的原始错误。
+ */
+function dispatchCacheWrite<T>(request: CacheWriteRequest<T>): void {
+    try {
+        request.provider.set(request.cacheKey, request.entry, request.ttl);
+    } catch (error) {
+        logCacheEvent('cache.operation_failed', { ...request.logContext, operation: 'write', error });
+        throw error;
+    }
+    logCacheEvent('cache.write_dispatched', { ...request.logContext, entryType: request.entryType });
+}
+
+/**
+ * 提交异常条目写入；同步 Provider 失败只记录基础设施错误，不遮蔽已经发生的业务异常。
+ * @param request 异常写入所需 Provider、entry、TTL 和稳定日志上下文。
+ * @returns 无返回值；异步写入 Promise 保持既有 fire-and-forget 边界。
+ */
+function dispatchCacheErrorWrite(request: CacheWriteRequest<never>): void {
+    try {
+        request.provider.set(request.cacheKey, request.entry, request.ttl);
+    } catch (error) {
+        logCacheEvent('cache.operation_failed', { ...request.logContext, operation: 'write', error });
+        return;
+    }
+    logCacheEvent('cache.write_dispatched', { ...request.logContext, entryType: 'error' });
+}
+
+function isErrorCacheEntry<T>(entry: CacheEntry<T>): entry is ErrorCacheEntry {
+    return typeof entry === 'object' && entry !== null && 'error' in entry;
+}
+
+/**
+ * 按当前异常策略分类 Provider 条目，并只把可成功解码的当前版本异常视为命中。
+ * @param entry Provider 返回的缓存联合条目。
+ * @param errorPolicy 当前装饰器归一化后的异常策略。
+ * @param logContext 当前方法的稳定日志上下文。
+ * @returns value/error 命中结果，或需要继续业务流程的 miss。
+ */
+function resolveCachedEntry<T>(
+    entry: CacheEntry<T>,
+    errorPolicy: NormalizedCacheErrorPolicy | undefined,
+    logContext: CacheLogContext
+): CacheReadResult<T> {
+    if (!isErrorCacheEntry(entry)) {
+        logCacheEvent('cache.hit', { ...logContext, entryType: 'value' });
+        return { type: 'value', value: entry.value };
+    }
+    if (!isCurrentCacheErrorPayload(entry.error)) {
+        logCacheEvent('cache.error_cache_skipped', { ...logContext, reason: 'legacy_entry' });
+        return { type: 'miss' };
+    }
+    if (errorPolicy === undefined) {
+        logCacheEvent('cache.error_cache_skipped', { ...logContext, reason: 'disabled_entry' });
+        return { type: 'miss' };
+    }
+    try {
+        const error = decodeCacheError(entry.error, errorPolicy);
+        logCacheEvent('cache.hit', { ...logContext, entryType: 'error' });
+        return { type: 'error', error };
+    } catch (_error) {
+        logCacheEvent('cache.error_cache_failed', { ...logContext, phase: 'decode' });
+        return { type: 'miss' };
+    }
+}
+
+/**
+ * 按固定顺序评估筛选器、编码异常并发起独立 TTL 写入，任何策略失败都保留原业务异常。
+ * @param request 本次业务异常、当前策略、Provider、完整 key 与稳定日志上下文。
+ * @returns 无返回值。
+ */
+function handleBusinessError(request: BusinessErrorRequest): void {
+    const { error, errorPolicy, provider, cacheKey, logContext } = request;
+    if (errorPolicy === undefined) {
+        logCacheEvent('cache.error_cache_skipped', { ...logContext, reason: 'disabled' });
+        return;
+    }
+    if (errorPolicy.shouldCache !== undefined) {
+        let accepted: boolean;
+        try {
+            accepted = errorPolicy.shouldCache(error);
+            if (typeof accepted !== 'boolean') {
+                throw new TypeError('Cache error shouldCache must return a boolean');
+            }
+        } catch (_error) {
+            logCacheEvent('cache.error_cache_failed', { ...logContext, phase: 'predicate' });
+            return;
+        }
+        if (!accepted) {
+            logCacheEvent('cache.error_cache_skipped', { ...logContext, reason: 'predicate_rejected' });
+            return;
+        }
+    }
+
+    let entry: ErrorCacheEntry;
+    try {
+        entry = { error: encodeCacheError(error, errorPolicy) };
+    } catch (_error) {
+        logCacheEvent('cache.error_cache_failed', { ...logContext, phase: 'encode' });
+        return;
+    }
+    dispatchCacheErrorWrite({ provider, cacheKey, entry, entryType: 'error', ttl: errorPolicy.ttl, logContext });
+}
+
 /**
  * 解析缓存 key
- * @param cacheName 缓存名称
  * @param keyResolver key 解析器
  * @param args 方法参数数组
+ * @param logContext 不包含业务参数和值的日志上下文
  * @returns 解析后的缓存 key
  */
-function resolveCacheKey(cacheName: string, keyResolver: CacheKeyResolver | undefined, args: unknown[]): string {
+function resolveCacheKey(
+    keyResolver: CacheKeyResolver | undefined,
+    args: unknown[],
+    logContext: CacheLogContext
+): string {
     if (keyResolver === undefined || keyResolver === null) {
-        return KeyBuilder.build(cacheName, args);
+        return KeyBuilder.build(logContext.cacheName, args);
     }
     if (typeof keyResolver === 'string') {
-        return KeyBuilder.build(cacheName, [keyResolver]);
+        return KeyBuilder.build(logContext.cacheName, [keyResolver]);
     }
     try {
-        return KeyBuilder.build(cacheName, [keyResolver(...args)]);
-    } catch {
-        return KeyBuilder.build(cacheName, args);
+        return KeyBuilder.build(logContext.cacheName, [keyResolver(...args)]);
+    } catch (_error) {
+        logCacheEvent('cache.key_fallback', { ...logContext, reason: 'resolver_error' });
+        return KeyBuilder.build(logContext.cacheName, args);
     }
 }
 
@@ -82,38 +250,64 @@ function resolveCacheKey(cacheName: string, keyResolver: CacheKeyResolver | unde
  * @param cacheName 缓存名称
  * @param options 配置项
  */
-export function Cache(cacheName: string, options?: CacheOptions) {
-    return function <T>(_target: object, _propertyKey: string, descriptor: PropertyDescriptor) {
+export function Cache(
+    cacheName: string,
+    options?: CacheOptions
+): (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => void {
+    const errorPolicy = normalizeCacheErrorPolicy(options?.errorCache);
+    return function <T>(_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[]) {
-            const cacheKey = resolveCacheKey(cacheName, options?.key, args);
-            const providerName = options?.providerName;
-            const provider = CacheProviderRegistry.get(providerName);
-
-            const cached = await provider.get(cacheKey);
-            if (cached !== undefined) {
-                const entry = cached as CacheEntry<T>;
-                if ('error' in entry) {
-                    throw entry.error;
-                }
-                return entry.value;
-            }
+        descriptor.value = function (...args: unknown[]): Promise<T> {
+            const cacheKey = resolveCacheKey(options?.key, args, logContext);
 
             const pending = pendingCache.get<T>(cacheKey);
             if (pending) {
+                logCacheEvent('cache.pending_hit', logContext);
                 return pending;
             }
 
             const promise = (async () => {
+                const provider = resolveCacheProvider(options?.providerName, logContext);
+                let cached: CacheEntry<T> | undefined;
+                try {
+                    cached = await provider.get<CacheEntry<T>>(cacheKey);
+                } catch (error) {
+                    logCacheEvent('cache.operation_failed', { ...logContext, operation: 'read', error });
+                    throw error;
+                }
+                if (cached !== undefined) {
+                    const cachedResult = resolveCachedEntry(cached, errorPolicy, logContext);
+                    if (cachedResult.type === 'value') {
+                        return cachedResult.value;
+                    }
+                    if (cachedResult.type === 'error') {
+                        throw cachedResult.error;
+                    }
+                }
+                logCacheEvent('cache.miss', logContext);
+
+                let result: T;
                 try {
-                    const result = await originalMethod.apply(this, args);
-                    provider.set(cacheKey, { value: result } as CacheEntry<T>, options?.ttl);
-                    return result;
+                    result = (await originalMethod.apply(this, args)) as T;
                 } catch (error) {
-                    provider.set(cacheKey, { error } as CacheEntry<T>, options?.ttl);
+                    handleBusinessError({ error, errorPolicy, provider, cacheKey, logContext });
                     throw error;
                 }
+                dispatchCacheWrite({
+                    provider,
+                    cacheKey,
+                    entry: { value: result },
+                    entryType: 'value',
+                    ttl: options?.ttl,
+                    logContext,
+                });
+                return result;
             })();
 
             pendingCache.set(cacheKey, promise);

package/src/index.ts

@@ -1,8 +1,11 @@
+export { createIoredisCacheClient } from './adapters/ioredis-cache-client';
+export { createNodeRedisCacheClient } from './adapters/node-redis-cache-client';
 export * from './core/cache-provider';
 export * from './core/cache-provider-registry';
 export * from './core/key-builder';
 export * from './core/native-cache';
 export * from './core/pending-cache';
+export * from './core/redis-cache-client';
 export * from './core/redis-cache';
 export * from './decorators/cache';
 export * from './decorators/cache-evict';