@jintianxiayu/cache-decorator 1.0.1 → 1.0.2

package/test/cache-logger.integration.test.ts

@@ -37,6 +37,7 @@ interface ChildResult {
 const packageRoot = resolve(__dirname, '..');
 const loggerRoot = resolve(packageRoot, '../logger');
 const fixture = join(__dirname, 'fixtures', 'cache-logger-child.mjs');
+const providerFailureFixture = join(__dirname, 'fixtures', 'cache-provider-failure-child.mjs');
 
 /**
  * 在隔离进程运行真实 Logger fixture，确保关闭流程完整刷新结构化输出。
@@ -62,6 +63,29 @@ function runFixture(profileLevel: 'debug' | 'error'): Promise<ChildResult> {
     });
 }
 
+/**
+ * 在严格未处理 rejection 模式运行 Provider 异步失败 fixture。
+ * @returns 子进程退出码和完整标准流。
+ * @throws 子进程无法启动时拒绝。
+ */
+function runProviderFailureFixture(): Promise<ChildResult> {
+    return new Promise((resolveResult, reject) => {
+        const child = spawn(process.execPath, ['--unhandled-rejections=strict', providerFailureFixture], {
+            cwd: packageRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk: string) => (stdout += chunk));
+        child.stderr.on('data', (chunk: string) => (stderr += chunk));
+        child.once('error', reject);
+        child.once('exit', (code) => resolveResult({ code, stdout, stderr }));
+    });
+}
+
 function parseEvents(output: string): JsonLogEvent[] {
     return output
         .split(/\r?\n/)
@@ -121,6 +145,12 @@ it('cache-operation-logging/Logger 配置筛选输出且复用应用提供的唯
     });
 });
 
+it('异步缓存写入和单 key 删除拒绝不会触发未处理 rejection', async () => {
+    const result = await runProviderFailureFixture();
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+});
+
 it('cache decorator 源码不读取或写入 LoggerContext', () => {
     const sources = ['src/core/cache-logger.ts', 'src/decorators/cache.ts', 'src/decorators/cache-evict.ts']
         .map((file) => readFileSync(join(packageRoot, file), 'utf8'))

package/test/cache-logging.test.ts

@@ -307,13 +307,12 @@ it('cache-operation-logging/C06 回填后的重复调用命中缓存且不重复
     expect(events(mockLogger.debug)).toEqual(['cache.miss', 'cache.write_dispatched', 'cache.hit']);
 });
 
-it('cache-operation-logging/F04 异步 set 拒绝不会被等待或消费', async () => {
+it('cache-operation-logging/F04 异步 set 拒绝被观察但不改变业务结果', async () => {
     let rejectWrite: ((reason?: unknown) => void) | undefined;
     const writeError = new Error('async write failed');
     const writePromise = new Promise<void>((_resolve, reject) => {
         rejectWrite = reject;
     });
-    const observedWriteFailure = writePromise.catch((error: unknown) => error);
     const thenSpy = jest.spyOn(writePromise, 'then');
     const provider = createProvider(undefined);
     provider.set.mockReturnValue(writePromise);
@@ -328,7 +327,7 @@ it('cache-operation-logging/F04 异步 set 拒绝不会被等待或消费', asyn
 
     await expect(new UserService().getUser()).resolves.toBe(10);
     expect(provider.set).toHaveBeenCalledTimes(1);
-    expect(thenSpy).not.toHaveBeenCalled();
+    expect(thenSpy).toHaveBeenCalledTimes(1);
     expect(events(mockLogger.debug)).toEqual(['cache.miss', 'cache.write_dispatched']);
     expect(events(mockLogger.debug)).not.toContain('cache.write_completed');
 
@@ -336,15 +335,66 @@ it('cache-operation-logging/F04 异步 set 拒绝不会被等待或消费', asyn
         throw new Error('Write rejecter was not initialized');
     }
     rejectWrite(writeError);
-    await expect(observedWriteFailure).resolves.toBe(writeError);
+    await Promise.resolve();
+    expect(loggedMetadata(mockLogger.error)).toContainEqual({
+        event: 'cache.operation_failed',
+        cacheName: 'async-write-users',
+        methodName: 'getUser',
+        providerName: 'async-write-provider',
+        operation: 'write',
+        error: writeError,
+    });
 });
 
-it('cache-operation-logging/F01 Provider 解析失败记录原始注册表异常且不执行业务', async () => {
+it('cache-operation-logging/F07 异常条目异步 set 拒绝被消费且保留原业务异常', async () => {
+    let rejectWrite: ((reason?: unknown) => void) | undefined;
+    const writeError = new Error('async error entry write failed');
+    const writePromise = new Promise<void>((_resolve, reject) => {
+        rejectWrite = reject;
+    });
+    const provider = createProvider(undefined);
+    provider.set.mockReturnValue(writePromise);
+    CacheProviderRegistry.register('async-error-write-provider', provider.provider);
+    const businessError = new Error('original business error');
+
+    class UserService {
+        @Cache('async-error-write-users', {
+            providerName: 'async-error-write-provider',
+            errorCache: { ttl: 5 },
+        })
+        getUser(): never {
+            throw businessError;
+        }
+    }
+
+    await expect(new UserService().getUser()).rejects.toBe(businessError);
+    expect(events(mockLogger.debug)).toEqual(['cache.miss', 'cache.write_dispatched']);
+    expect(mockLogger.error).not.toHaveBeenCalled();
+
+    if (!rejectWrite) {
+        throw new Error('Write rejecter was not initialized');
+    }
+    rejectWrite(writeError);
+    await Promise.resolve();
+    expect(loggedMetadata(mockLogger.error)).toEqual([
+        {
+            event: 'cache.operation_failed',
+            cacheName: 'async-error-write-users',
+            methodName: 'getUser',
+            providerName: 'async-error-write-provider',
+            operation: 'write',
+            error: writeError,
+        },
+    ]);
+});
+
+it('cache-operation-logging/F01 Provider 解析失败记录原始注册表异常并旁路执行业务', async () => {
     const registryError = new Error('provider resolution failed');
     jest.spyOn(CacheProviderRegistry, 'get').mockImplementation(() => {
         throw registryError;
     });
-    const businessMethod = jest.fn();
+    const businessResult = { id: 20 };
+    const businessMethod = jest.fn(() => businessResult);
 
     class UserService {
         @Cache('missing-provider-users', { providerName: 'missing-provider' })
@@ -353,8 +403,8 @@ it('cache-operation-logging/F01 Provider 解析失败记录原始注册表异常
         }
     }
 
-    await expect(new UserService().getUser()).rejects.toBe(registryError);
-    expect(businessMethod).not.toHaveBeenCalled();
+    await expect(new UserService().getUser()).resolves.toBe(businessResult);
+    expect(businessMethod).toHaveBeenCalledTimes(1);
     expect(events(mockLogger.debug)).toEqual([]);
     expect(loggedMetadata(mockLogger.error)).toEqual([
         {
@@ -368,11 +418,12 @@ it('cache-operation-logging/F01 Provider 解析失败记录原始注册表异常
     ]);
 });
 
-it('cache-operation-logging/F02 cache-operation-logging/M03 读取失败记录同一错误且不转为 miss', async () => {
+it('cache-operation-logging/F02 cache-operation-logging/M03 读取失败记录同一错误并旁路执行业务', async () => {
     const readError = new Error('redis unavailable');
     const provider = createProvider(Promise.reject(readError));
     CacheProviderRegistry.register('unavailable-provider', provider.provider);
-    const businessMethod = jest.fn();
+    const businessResult = { id: 21 };
+    const businessMethod = jest.fn(() => businessResult);
 
     class UserService {
         @Cache('unavailable-users', { providerName: 'unavailable-provider' })
@@ -381,10 +432,10 @@ it('cache-operation-logging/F02 cache-operation-logging/M03 读取失败记录
         }
     }
 
-    await expect(new UserService().getUser()).rejects.toBe(readError);
+    await expect(new UserService().getUser()).resolves.toBe(businessResult);
     expect(provider.get).toHaveBeenCalledTimes(1);
     expect(provider.set).not.toHaveBeenCalled();
-    expect(businessMethod).not.toHaveBeenCalled();
+    expect(businessMethod).toHaveBeenCalledTimes(1);
     expect(events(mockLogger.debug)).not.toContain('cache.miss');
     expect(loggedMetadata(mockLogger.error)).toEqual([
         {
@@ -511,14 +562,14 @@ it('cache-operation-logging/L03 Logger debug 失败不影响 cache hit', async (
     expect(businessMethod).not.toHaveBeenCalled();
 });
 
-it('cache-operation-logging/L04 Logger error 失败不遮蔽原始读取异常', async () => {
+it('cache-operation-logging/L04 Logger error 失败不影响读取失败后的业务旁路', async () => {
     const readError = new Error('provider read failed');
     const provider = createProvider(Promise.reject(readError));
     CacheProviderRegistry.register('logger-error-provider', provider.provider);
     mockLogger.error.mockImplementationOnce(() => {
         throw new Error('logger error failed');
     });
-    const businessMethod = jest.fn();
+    const businessMethod = jest.fn(() => 'business-result');
 
     class UserService {
         @Cache('logger-error-users', { providerName: 'logger-error-provider' })
@@ -527,12 +578,38 @@ it('cache-operation-logging/L04 Logger error 失败不遮蔽原始读取异常',
         }
     }
 
-    await expect(new UserService().getUser()).rejects.toBe(readError);
-    expect(businessMethod).not.toHaveBeenCalled();
+    await expect(new UserService().getUser()).resolves.toBe('business-result');
+    expect(businessMethod).toHaveBeenCalledTimes(1);
+    expect(events(mockLogger.debug)).not.toContain('cache.miss');
+});
+
+it('cache-operation-logging/L04 Provider 与 Logger 同时失败时保留原业务异常', async () => {
+    const providerError = new Error('provider read failed');
+    const provider = createProvider(Promise.reject(providerError));
+    CacheProviderRegistry.register('logger-business-error-provider', provider.provider);
+    mockLogger.error.mockImplementationOnce(() => {
+        throw new Error('logger error failed');
+    });
+    const businessError = new Error('original business failure');
+    const shouldCache = jest.fn((_error: unknown): boolean => true);
+
+    class UserService {
+        @Cache('logger-business-error-users', {
+            providerName: 'logger-business-error-provider',
+            errorCache: { ttl: 5, shouldCache },
+        })
+        getUser(): never {
+            throw businessError;
+        }
+    }
+
+    await expect(new UserService().getUser()).rejects.toBe(businessError);
+    expect(shouldCache).not.toHaveBeenCalled();
+    expect(provider.set).not.toHaveBeenCalled();
     expect(events(mockLogger.debug)).not.toContain('cache.miss');
 });
 
-it('正常结果同步 set 失败只记录一次 write operation 且不进入异常策略', async () => {
+it('正常结果同步 set 失败只记录一次 write operation 且保留业务结果', async () => {
     const writeError = new Error('synchronous write failed');
     const provider = createProvider(undefined);
     const shouldCache = jest.fn((_error: unknown): boolean => true);
@@ -551,7 +628,7 @@ it('正常结果同步 set 失败只记录一次 write operation 且不进入异
         }
     }
 
-    await expect(new UserService().getUser()).rejects.toBe(writeError);
+    await expect(new UserService().getUser()).resolves.toBe(12);
     expect(provider.set).toHaveBeenCalledTimes(1);
     expect(shouldCache).not.toHaveBeenCalled();
     expect(loggedMetadata(mockLogger.error)).toContainEqual({

package/test/cache.test.ts

@@ -350,7 +350,7 @@ describe('异常策略配置边界', () => {
 });
 
 describe('异常策略编排', () => {
-    it('Provider 读取失败不调用异常筛选器、codec 或业务方法', async () => {
+    it('Provider 同步读取失败时旁路缓存并执行业务方法', async () => {
         const provider = createProvider();
         const readError = new Error('redis unavailable');
         provider.get.mockImplementation(() => {
@@ -360,7 +360,8 @@ describe('异常策略编排', () => {
         const shouldCache = jest.fn(() => true);
         const encode = jest.fn((error: unknown): unknown => error);
         const decode = jest.fn((payload: unknown): unknown => payload);
-        const businessMethod = jest.fn();
+        const businessResult = { id: 1 };
+        const businessMethod = jest.fn(() => businessResult);
 
         class UserService {
             @Cache('failed-read-users', {
@@ -372,14 +373,91 @@ describe('异常策略编排', () => {
             }
         }
 
-        await expect(new UserService().getUser()).rejects.toBe(readError);
-        expect(businessMethod).not.toHaveBeenCalled();
+        await expect(new UserService().getUser()).resolves.toBe(businessResult);
+        expect(businessMethod).toHaveBeenCalledTimes(1);
         expect(shouldCache).not.toHaveBeenCalled();
         expect(encode).not.toHaveBeenCalled();
         expect(decode).not.toHaveBeenCalled();
         expect(provider.set).not.toHaveBeenCalled();
     });
+});
+
+describe('Provider 故障旁路', () => {
+    it.each(['missing', 'sync-read', 'async-read'] as const)(
+        'Provider %s 故障旁路时传播原始业务异常且不执行异常策略',
+        async (failureMode) => {
+            const provider = createProvider();
+            const providerError = new Error(`provider ${failureMode}`);
+            if (failureMode === 'sync-read') {
+                provider.get.mockImplementation(() => {
+                    throw providerError;
+                });
+                CacheProviderRegistry.register('failed-provider', provider.provider);
+            } else if (failureMode === 'async-read') {
+                provider.get.mockRejectedValue(providerError);
+                CacheProviderRegistry.register('failed-provider', provider.provider);
+            }
+
+            const businessError = new Error(`business ${failureMode}`);
+            const shouldCache = jest.fn((_error: unknown): boolean => true);
+            const encode = jest.fn((error: unknown): unknown => error);
+            const decode = jest.fn((payload: unknown): unknown => payload);
+            const businessMethod = jest.fn(() => {
+                throw businessError;
+            });
+
+            class UserService {
+                @Cache('failed-provider-users', {
+                    providerName: 'failed-provider',
+                    errorCache: { ttl: 5, shouldCache, codec: { encode, decode } },
+                })
+                getUser(): never {
+                    return businessMethod();
+                }
+            }
+
+            await expect(new UserService().getUser()).rejects.toBe(businessError);
+            expect(businessMethod).toHaveBeenCalledTimes(1);
+            expect(provider.get).toHaveBeenCalledTimes(failureMode === 'missing' ? 0 : 1);
+            expect(provider.set).not.toHaveBeenCalled();
+            expect(shouldCache).not.toHaveBeenCalled();
+            expect(encode).not.toHaveBeenCalled();
+            expect(decode).not.toHaveBeenCalled();
+        }
+    );
+
+    it('Provider 异步读取失败时并发调用复用 pending Promise 且 settled 后清理', async () => {
+        const provider = createProvider();
+        const readFailure = createRejectionDeferred();
+        provider.get.mockReturnValue(readFailure.promise);
+        CacheProviderRegistry.register('pending-failed-read', provider.provider);
+        const businessMethod = jest.fn(() => 23);
 
+        class UserService {
+            @Cache('pending-failed-read-users', { providerName: 'pending-failed-read' })
+            getUser(): number {
+                return businessMethod();
+            }
+        }
+
+        const service = new UserService();
+        const first = service.getUser();
+        const second = service.getUser();
+        expect(second).toBe(first);
+        expect(provider.get).toHaveBeenCalledTimes(1);
+
+        readFailure.reject(new Error('redis read failed'));
+        await expect(Promise.all([first, second])).resolves.toEqual([23, 23]);
+        expect(businessMethod).toHaveBeenCalledTimes(1);
+        expect(provider.set).not.toHaveBeenCalled();
+
+        await expect(service.getUser()).resolves.toBe(23);
+        expect(provider.get).toHaveBeenCalledTimes(2);
+        expect(businessMethod).toHaveBeenCalledTimes(2);
+    });
+});
+
+describe('异常策略编排', () => {
     it('key resolver 失败后的业务成功只写入正常结果', async () => {
         const provider = createProvider();
         CacheProviderRegistry.register('key-fallback', provider.provider);
@@ -601,7 +679,7 @@ describe('异常策略编排', () => {
         expect(provider.set).toHaveBeenCalledTimes(1);
     });
 
-    it('正常写入同步失败不进入异常缓存策略', async () => {
+    it('正常写入同步失败不进入异常缓存策略且保留业务结果', async () => {
         const provider = createProvider();
         const writeError = new Error('normal write failed');
         const shouldCache = jest.fn((_error: unknown): boolean => true);
@@ -620,7 +698,7 @@ describe('异常策略编排', () => {
             }
         }
 
-        await expect(new UserService().getUser()).rejects.toBe(writeError);
+        await expect(new UserService().getUser()).resolves.toBe('value');
         expect(provider.set).toHaveBeenCalledTimes(1);
         expect(shouldCache).not.toHaveBeenCalled();
     });

package/test/fixtures/cache-logger-child.mjs

@@ -1,108 +1,108 @@
-import assert from 'node:assert/strict';
-import { realpathSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import cachePackage from '../../dist/index.js';
-import loggerPackage from '../../../logger/dist/index.js';
-
-const { Cache, CacheProviderRegistry, MemoryCacheProvider } = cachePackage;
-const { LoggerContext, LoggerFactory } = loggerPackage;
-const CACHE_LOGGER_NAME = '@jintianxiayu/cache-decorator';
-const profileLevel = process.argv[2];
-const fixtureDirectory = dirname(fileURLToPath(import.meta.url));
-const fixtureRequire = createRequire(import.meta.url);
-if (profileLevel !== 'debug' && profileLevel !== 'error') {
-    throw new Error('Expected cache Logger profile level: debug or error');
-}
-
-/** 将 legacy method decorator 应用到 JavaScript fixture 的指定方法。 */
-function decorateMethod(target, methodName, decorator) {
-    const descriptor = Object.getOwnPropertyDescriptor(target, methodName);
-    assert.ok(descriptor);
-    decorator(target, methodName, descriptor);
-    Object.defineProperty(target, methodName, descriptor);
-}
-
-/** 在应用初始化 Logger 后执行正常缓存和 Provider 失败调用。 */
-async function main() {
-    LoggerFactory.init({
-        root: {
-            level: 'error',
-            console: { enabled: false, colors: false, format: 'json' },
-            file: { enabled: false },
-        },
-        loggers: {
-            [CACHE_LOGGER_NAME]: {
-                level: profileLevel,
-                console: { enabled: true, colors: false, format: 'json' },
-                file: { enabled: false },
-            },
-        },
-        masking: { enabled: true },
-        processErrors: {
-            uncaughtException: false,
-            unhandledRejection: false,
-            exitOnError: false,
-        },
-    });
-
-    const cachePackageRoot = resolve(fixtureDirectory, '../..');
-    const requireFromCache = createRequire(join(cachePackageRoot, 'package.json'));
-    const directLoggerEntry = fixtureRequire.resolve('@jintianxiayu/logger');
-    const cacheLoggerEntry = requireFromCache.resolve('@jintianxiayu/logger');
-    assert.equal(realpathSync(directLoggerEntry), realpathSync(cacheLoggerEntry));
-    const namedLogger = LoggerFactory.getLogger(CACHE_LOGGER_NAME);
-
-    const memoryProvider = new MemoryCacheProvider();
-    const providerError = Object.assign(new Error('redis unavailable'), {
-        password: 'provider-password-secret',
-        email: 'provider@example.com',
-    });
-    const failingProvider = {
-        get: async () => {
-            throw providerError;
-        },
-        set: () => undefined,
-        delete: () => undefined,
-        clear: () => undefined,
-        deleteByPattern: () => undefined,
-    };
-
-    class SuccessService {
-        getUser() {
-            return { id: 17, password: 'business-value-secret' };
-        }
-    }
-    decorateMethod(SuccessService.prototype, 'getUser', Cache('fixture-users', { providerName: 'memory' }));
-
-    class FailureService {
-        getUser() {
-            throw new Error('business method must not run');
-        }
-    }
-    decorateMethod(FailureService.prototype, 'getUser', Cache('fixture-failure-users', { providerName: 'failing' }));
-
-    CacheProviderRegistry.register('memory', memoryProvider);
-    CacheProviderRegistry.register('failing', failingProvider);
-    try {
-        const result = await LoggerContext.withContext({ traceId: 'cache-fixture-trace' }, () =>
-            new SuccessService().getUser()
-        );
-        assert.deepEqual(result, { id: 17, password: 'business-value-secret' });
-
-        const failure = LoggerContext.withContext({ traceId: 'cache-fixture-trace' }, () =>
-            new FailureService().getUser()
-        );
-        await assert.rejects(failure, (error) => error === providerError);
-        assert.strictEqual(LoggerFactory.getLogger(CACHE_LOGGER_NAME), namedLogger);
-    } finally {
-        CacheProviderRegistry.clear();
-        await LoggerFactory.shutdown({ timeout: 2_000 });
-    }
-}
-
-main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
-    process.exitCode = 1;
-});
+import assert from 'node:assert/strict';
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import cachePackage from '../../dist/index.js';
+import loggerPackage from '../../../logger/dist/index.js';
+
+const { Cache, CacheProviderRegistry, MemoryCacheProvider } = cachePackage;
+const { LoggerContext, LoggerFactory } = loggerPackage;
+const CACHE_LOGGER_NAME = '@jintianxiayu/cache-decorator';
+const profileLevel = process.argv[2];
+const fixtureDirectory = dirname(fileURLToPath(import.meta.url));
+const fixtureRequire = createRequire(import.meta.url);
+if (profileLevel !== 'debug' && profileLevel !== 'error') {
+    throw new Error('Expected cache Logger profile level: debug or error');
+}
+
+/** 将 legacy method decorator 应用到 JavaScript fixture 的指定方法。 */
+function decorateMethod(target, methodName, decorator) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, methodName);
+    assert.ok(descriptor);
+    decorator(target, methodName, descriptor);
+    Object.defineProperty(target, methodName, descriptor);
+}
+
+/** 在应用初始化 Logger 后执行正常缓存和 Provider 失败调用。 */
+async function main() {
+    LoggerFactory.init({
+        root: {
+            level: 'error',
+            console: { enabled: false, colors: false, format: 'json' },
+            file: { enabled: false },
+        },
+        loggers: {
+            [CACHE_LOGGER_NAME]: {
+                level: profileLevel,
+                console: { enabled: true, colors: false, format: 'json' },
+                file: { enabled: false },
+            },
+        },
+        masking: { enabled: true },
+        processErrors: {
+            uncaughtException: false,
+            unhandledRejection: false,
+            exitOnError: false,
+        },
+    });
+
+    const cachePackageRoot = resolve(fixtureDirectory, '../..');
+    const requireFromCache = createRequire(join(cachePackageRoot, 'package.json'));
+    const directLoggerEntry = fixtureRequire.resolve('@jintianxiayu/logger');
+    const cacheLoggerEntry = requireFromCache.resolve('@jintianxiayu/logger');
+    assert.equal(realpathSync(directLoggerEntry), realpathSync(cacheLoggerEntry));
+    const namedLogger = LoggerFactory.getLogger(CACHE_LOGGER_NAME);
+
+    const memoryProvider = new MemoryCacheProvider();
+    const providerError = Object.assign(new Error('redis unavailable'), {
+        password: 'provider-password-secret',
+        email: 'provider@example.com',
+    });
+    const failingProvider = {
+        get: async () => {
+            throw providerError;
+        },
+        set: () => undefined,
+        delete: () => undefined,
+        clear: () => undefined,
+        deleteByPattern: () => undefined,
+    };
+
+    class SuccessService {
+        getUser() {
+            return { id: 17, password: 'business-value-secret' };
+        }
+    }
+    decorateMethod(SuccessService.prototype, 'getUser', Cache('fixture-users', { providerName: 'memory' }));
+
+    class FailureService {
+        getUser() {
+            return { id: 18, source: 'business-bypass' };
+        }
+    }
+    decorateMethod(FailureService.prototype, 'getUser', Cache('fixture-failure-users', { providerName: 'failing' }));
+
+    CacheProviderRegistry.register('memory', memoryProvider);
+    CacheProviderRegistry.register('failing', failingProvider);
+    try {
+        const result = await LoggerContext.withContext({ traceId: 'cache-fixture-trace' }, () =>
+            new SuccessService().getUser()
+        );
+        assert.deepEqual(result, { id: 17, password: 'business-value-secret' });
+
+        const bypassResult = await LoggerContext.withContext({ traceId: 'cache-fixture-trace' }, () =>
+            new FailureService().getUser()
+        );
+        assert.deepEqual(bypassResult, { id: 18, source: 'business-bypass' });
+        assert.strictEqual(LoggerFactory.getLogger(CACHE_LOGGER_NAME), namedLogger);
+    } finally {
+        CacheProviderRegistry.clear();
+        await LoggerFactory.shutdown({ timeout: 2_000 });
+    }
+}
+
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+    process.exitCode = 1;
+});

package/test/fixtures/cache-provider-failure-child.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import cachePackage from '../../dist/index.js';
+
+const { Cache, CacheEvict, CacheProviderRegistry } = cachePackage;
+
+/** 将 legacy method decorator 应用到 JavaScript fixture 的指定方法。 */
+function decorateMethod(target, methodName, decorator) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, methodName);
+    assert.ok(descriptor);
+    decorator(target, methodName, descriptor);
+    Object.defineProperty(target, methodName, descriptor);
+}
+
+/** 执行异步写入和删除拒绝场景，进程必须在 strict rejection 模式下正常退出。 */
+async function main() {
+    const writeError = new Error('async cache write failed');
+    const deleteError = new Error('async cache delete failed');
+    const writeProvider = {
+        get: () => undefined,
+        set: () => Promise.reject(writeError),
+        delete: () => undefined,
+        clear: () => undefined,
+        deleteByPattern: () => undefined,
+    };
+    const deleteProvider = {
+        get: () => undefined,
+        set: () => undefined,
+        delete: () => Promise.reject(deleteError),
+        clear: () => undefined,
+        deleteByPattern: () => undefined,
+    };
+
+    class UserService {
+        getUser() {
+            return 'business-value';
+        }
+
+        updateUser() {
+            return 'business-update';
+        }
+    }
+
+    decorateMethod(UserService.prototype, 'getUser', Cache('failure-fixture-users', { providerName: 'write' }));
+    decorateMethod(
+        UserService.prototype,
+        'updateUser',
+        CacheEvict('failure-fixture-users', { providerName: 'delete' })
+    );
+    CacheProviderRegistry.register('write', writeProvider);
+    CacheProviderRegistry.register('delete', deleteProvider);
+
+    try {
+        const service = new UserService();
+        assert.equal(await service.getUser(), 'business-value');
+        assert.equal(await service.updateUser(), 'business-update');
+        await new Promise((resolve) => setImmediate(resolve));
+    } finally {
+        CacheProviderRegistry.clear();
+    }
+}
+
+const currentFile = fileURLToPath(import.meta.url);
+if (currentFile === join(process.cwd(), 'test', 'fixtures', 'cache-provider-failure-child.mjs')) {
+    main().catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}