@jintianxiayu/cache-decorator 0.1.2 → 1.0.0

package/test/cache-evict.test.ts

@@ -4,175 +4,175 @@ import { CacheProviderRegistry } from '../src/core/cache-provider-registry';
 import { MemoryCacheProvider } from '../src/core/native-cache';
 
 describe('@CacheEvict 装饰器', () => {
-  let memoryProvider: MemoryCacheProvider;
-
-  beforeAll(() => {
-    memoryProvider = new MemoryCacheProvider();
-    CacheProviderRegistry.register('memory', memoryProvider);
-    CacheProviderRegistry.setDefault('memory');
-  });
-
-  afterEach(() => {
-    memoryProvider.clear();
-  });
-
-  describe('按入参清除', () => {
-    it('应清除对应缓存条目', async () => {
-      let getUserCallCount = 0;
-      let updateUserCallCount = 0;
-
-      class UserService {
-        @Cache('user-cache')
-        async getUser(id: number) {
-          getUserCallCount++;
-          return { id };
-        }
-
-        @CacheEvict('user-cache')
-        async updateUser(id: number) {
-          updateUserCallCount++;
-          return { id, updated: true };
-        }
-      }
-
-      const service = new UserService();
-      await service.getUser(1);
-      await service.getUser(1);
-      expect(getUserCallCount).toBe(1);
-
-      await service.updateUser(1);
-      await service.getUser(1);
-      expect(getUserCallCount).toBe(2);
-      expect(updateUserCallCount).toBe(1);
+    let memoryProvider: MemoryCacheProvider;
+
+    beforeAll(() => {
+        memoryProvider = new MemoryCacheProvider();
+        CacheProviderRegistry.register('memory', memoryProvider);
+        CacheProviderRegistry.setDefault('memory');
     });
-  });
-
-  describe('清除所有条目', () => {
-    it('应清除该缓存名称下所有条目', async () => {
-      let getUserCallCount = 0;
-      let getOrderCallCount = 0;
-      let clearCallCount = 0;
-
-      class Service {
-        @Cache('user-cache')
-        async getUser(id: number) {
-          getUserCallCount++;
-          return { id };
-        }
-
-        @Cache('order-cache')
-        async getOrder(id: number) {
-          getOrderCallCount++;
-          return { id };
-        }
-
-        @CacheEvict('user-cache', { allEntries: true })
-        async clearAllUsers() {
-          clearCallCount++;
-          return true;
-        }
-      }
-
-      const service = new Service();
-      await service.getUser(1);
-      await service.getUser(2);
-      await service.getOrder(1);
-      expect(getUserCallCount).toBe(2);
-      expect(getOrderCallCount).toBe(1);
-
-      await service.clearAllUsers();
-      expect(clearCallCount).toBe(1);
-
-      await service.getUser(1);
-      await service.getUser(2);
-      await service.getOrder(1);
-      expect(getUserCallCount).toBe(4);
-      expect(getOrderCallCount).toBe(1);
+
+    afterEach(() => {
+        memoryProvider.clear();
     });
-  });
-
-  describe('key 选项', () => {
-    it('key 为字符串时应删除对应缓存条目', async () => {
-      let getUserCallCount = 0;
-
-      class UserService {
-        @Cache('user-cache', { key: 'all-users' })
-        async getUsers() {
-          getUserCallCount++;
-          return [{ id: 1 }, { id: 2 }];
-        }
-
-        @CacheEvict('user-cache', { key: 'all-users' })
-        async clearUsers() {
-          return true;
-        }
-      }
-
-      const service = new UserService();
-      await service.getUsers();
-      await service.getUsers();
-      expect(getUserCallCount).toBe(1);
-
-      await service.clearUsers();
-      await service.getUsers();
-      expect(getUserCallCount).toBe(2);
+
+    describe('按入参清除', () => {
+        it('应清除对应缓存条目', async () => {
+            let getUserCallCount = 0;
+            let updateUserCallCount = 0;
+
+            class UserService {
+                @Cache('user-cache')
+                async getUser(id: number) {
+                    getUserCallCount++;
+                    return { id };
+                }
+
+                @CacheEvict('user-cache')
+                async updateUser(id: number) {
+                    updateUserCallCount++;
+                    return { id, updated: true };
+                }
+            }
+
+            const service = new UserService();
+            await service.getUser(1);
+            await service.getUser(1);
+            expect(getUserCallCount).toBe(1);
+
+            await service.updateUser(1);
+            await service.getUser(1);
+            expect(getUserCallCount).toBe(2);
+            expect(updateUserCallCount).toBe(1);
+        });
     });
 
-    it('key 为函数时应使用函数返回值删除缓存条目', async () => {
-      let getUserCallCount = 0;
-
-      class UserService {
-        @Cache('user-cache', { key: (...args: unknown[]) => String(args[0]) })
-        async getUser(id: number) {
-          getUserCallCount++;
-          return { id };
-        }
-
-        @CacheEvict('user-cache', { key: (...args: unknown[]) => String(args[0]) })
-        async deleteUser(id: number) {
-          return { id, deleted: true };
-        }
-      }
-
-      const service = new UserService();
-      await service.getUser(1);
-      await service.getUser(2);
-      expect(getUserCallCount).toBe(2);
-
-      await service.deleteUser(1);
-      await service.getUser(1);
-      await service.getUser(2);
-      expect(getUserCallCount).toBe(3);
+    describe('清除所有条目', () => {
+        it('应清除该缓存名称下所有条目', async () => {
+            let getUserCallCount = 0;
+            let getOrderCallCount = 0;
+            let clearCallCount = 0;
+
+            class Service {
+                @Cache('user-cache')
+                async getUser(id: number) {
+                    getUserCallCount++;
+                    return { id };
+                }
+
+                @Cache('order-cache')
+                async getOrder(id: number) {
+                    getOrderCallCount++;
+                    return { id };
+                }
+
+                @CacheEvict('user-cache', { allEntries: true })
+                async clearAllUsers() {
+                    clearCallCount++;
+                    return true;
+                }
+            }
+
+            const service = new Service();
+            await service.getUser(1);
+            await service.getUser(2);
+            await service.getOrder(1);
+            expect(getUserCallCount).toBe(2);
+            expect(getOrderCallCount).toBe(1);
+
+            await service.clearAllUsers();
+            expect(clearCallCount).toBe(1);
+
+            await service.getUser(1);
+            await service.getUser(2);
+            await service.getOrder(1);
+            expect(getUserCallCount).toBe(4);
+            expect(getOrderCallCount).toBe(1);
+        });
     });
 
-    it('allEntries 为 true 时忽略 key 选项', async () => {
-      let getUserCallCount = 0;
-      let clearCallCount = 0;
-
-      class UserService {
-        @Cache('user-cache', { key: 'specific-key' })
-        async getUsers() {
-          getUserCallCount++;
-          return [];
-        }
-
-        @CacheEvict('user-cache', { allEntries: true, key: 'ignored-key' })
-        async clearAllUsers() {
-          clearCallCount++;
-          return true;
-        }
-      }
-
-      const service = new UserService();
-      await service.getUsers();
-      await service.getUsers();
-      expect(getUserCallCount).toBe(1);
-
-      await service.clearAllUsers();
-      expect(clearCallCount).toBe(1);
-
-      await service.getUsers();
-      expect(getUserCallCount).toBe(2);
+    describe('key 选项', () => {
+        it('key 为字符串时应删除对应缓存条目', async () => {
+            let getUserCallCount = 0;
+
+            class UserService {
+                @Cache('user-cache', { key: 'all-users' })
+                async getUsers() {
+                    getUserCallCount++;
+                    return [{ id: 1 }, { id: 2 }];
+                }
+
+                @CacheEvict('user-cache', { key: 'all-users' })
+                async clearUsers() {
+                    return true;
+                }
+            }
+
+            const service = new UserService();
+            await service.getUsers();
+            await service.getUsers();
+            expect(getUserCallCount).toBe(1);
+
+            await service.clearUsers();
+            await service.getUsers();
+            expect(getUserCallCount).toBe(2);
+        });
+
+        it('key 为函数时应使用函数返回值删除缓存条目', async () => {
+            let getUserCallCount = 0;
+
+            class UserService {
+                @Cache('user-cache', { key: (...args: unknown[]) => String(args[0]) })
+                async getUser(id: number) {
+                    getUserCallCount++;
+                    return { id };
+                }
+
+                @CacheEvict('user-cache', { key: (...args: unknown[]) => String(args[0]) })
+                async deleteUser(id: number) {
+                    return { id, deleted: true };
+                }
+            }
+
+            const service = new UserService();
+            await service.getUser(1);
+            await service.getUser(2);
+            expect(getUserCallCount).toBe(2);
+
+            await service.deleteUser(1);
+            await service.getUser(1);
+            await service.getUser(2);
+            expect(getUserCallCount).toBe(3);
+        });
+
+        it('allEntries 为 true 时忽略 key 选项', async () => {
+            let getUserCallCount = 0;
+            let clearCallCount = 0;
+
+            class UserService {
+                @Cache('user-cache', { key: 'specific-key' })
+                async getUsers() {
+                    getUserCallCount++;
+                    return [];
+                }
+
+                @CacheEvict('user-cache', { allEntries: true, key: 'ignored-key' })
+                async clearAllUsers() {
+                    clearCallCount++;
+                    return true;
+                }
+            }
+
+            const service = new UserService();
+            await service.getUsers();
+            await service.getUsers();
+            expect(getUserCallCount).toBe(1);
+
+            await service.clearAllUsers();
+            expect(clearCallCount).toBe(1);
+
+            await service.getUsers();
+            expect(getUserCallCount).toBe(2);
+        });
     });
-  });
-});
+});

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

@@ -0,0 +1,129 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { runCommand } from './helpers/package-consumer';
+
+jest.setTimeout(30_000);
+
+interface CacheLogMetadata {
+    readonly event: string;
+    readonly cacheName: string;
+    readonly methodName: string;
+    readonly providerName: string;
+    readonly entryType?: string;
+    readonly operation?: string;
+    readonly error?: {
+        readonly name: string;
+        readonly message: string;
+        readonly password: string;
+        readonly email: string;
+    };
+}
+
+interface JsonLogEvent {
+    readonly level: string;
+    readonly name: string;
+    readonly message: string;
+    readonly traceId: string;
+    readonly meta: CacheLogMetadata;
+}
+
+interface ChildResult {
+    readonly code: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+
+const packageRoot = resolve(__dirname, '..');
+const loggerRoot = resolve(packageRoot, '../logger');
+const fixture = join(__dirname, 'fixtures', 'cache-logger-child.mjs');
+
+/**
+ * 在隔离进程运行真实 Logger fixture，确保关闭流程完整刷新结构化输出。
+ * @param profileLevel cache 命名 profile 的筛选级别。
+ * @returns 子进程退出码和完整标准流。
+ * @throws 子进程无法启动时拒绝。
+ */
+function runFixture(profileLevel: 'debug' | 'error'): Promise<ChildResult> {
+    return new Promise((resolveResult, reject) => {
+        const child = spawn(process.execPath, [fixture, profileLevel], {
+            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/)
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as JsonLogEvent);
+}
+
+beforeAll(() => {
+    const compiler = require.resolve('typescript/bin/tsc');
+    runCommand({ executable: process.execPath, args: [compiler, '-p', loggerRoot], cwd: loggerRoot });
+    runCommand({ executable: process.execPath, args: [compiler, '-p', packageRoot], cwd: packageRoot });
+});
+
+it('cache-operation-logging/M03 cache-operation-logging/M04 使用真实命名 Logger 脱敏并关联 traceId', async () => {
+    const result = await runFixture('debug');
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).not.toContain('provider-password-secret');
+    expect(result.stdout).not.toContain('provider@example.com');
+    expect(result.stdout).not.toContain('business-value-secret');
+
+    const output = parseEvents(result.stdout);
+    expect(output.map(({ level, meta }) => `${level}:${meta.event}`)).toEqual([
+        'debug:cache.miss',
+        'debug:cache.write_dispatched',
+        'error:cache.operation_failed',
+    ]);
+    expect(output.every(({ name }) => name === '@jintianxiayu/cache-decorator')).toBe(true);
+    expect(output.every(({ traceId }) => traceId === 'cache-fixture-trace')).toBe(true);
+    expect(output.every(({ meta }) => !('traceId' in meta))).toBe(true);
+    expect(output[2]?.meta).toMatchObject({
+        event: 'cache.operation_failed',
+        cacheName: 'fixture-failure-users',
+        methodName: 'getUser',
+        providerName: 'failing',
+        operation: 'read',
+        error: {
+            name: 'Error',
+            message: 'redis unavailable',
+            password: '********',
+            email: 'pr***@example.com',
+        },
+    });
+});
+
+it('cache-operation-logging/Logger 配置筛选输出且复用应用提供的唯一 Logger runtime', async () => {
+    const result = await runFixture('error');
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+    const output = parseEvents(result.stdout);
+    expect(output).toHaveLength(1);
+    expect(output[0]).toMatchObject({
+        level: 'error',
+        name: '@jintianxiayu/cache-decorator',
+        traceId: 'cache-fixture-trace',
+        meta: { event: 'cache.operation_failed', operation: 'read' },
+    });
+});
+
+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'))
+        .join('\n');
+    expect(sources).not.toContain('LoggerContext');
+});

package/test/cache-logger.test.ts

@@ -0,0 +1,153 @@
+import type { LoggerInterface } from '@jintianxiayu/logger';
+
+type CacheLoggerModule = typeof import('../src/core/cache-logger');
+
+interface CacheLoggerHarness {
+    readonly cacheLogger: CacheLoggerModule;
+    readonly getLogger: jest.Mock<LoggerInterface, [string]>;
+    readonly logger: jest.Mocked<LoggerInterface>;
+}
+
+const logContext = {
+    cacheName: 'users',
+    methodName: 'findUser',
+    providerName: 'default',
+} as const;
+
+function createMockLogger(): jest.Mocked<LoggerInterface> {
+    return {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    };
+}
+
+/**
+ * 为每个用例重新加载 cache Logger 模块，隔离模块级 Logger 缓存并允许注入获取失败。
+ * @param getLoggerImplementation 可选的 LoggerFactory.getLogger 替代实现。
+ * @returns 独立模块、Logger 获取 mock 和四个 level 方法 mock。
+ * @throws 隔离模块未能同步加载时抛出。
+ */
+function loadCacheLogger(getLoggerImplementation?: (name: string) => LoggerInterface): CacheLoggerHarness {
+    jest.resetModules();
+    const logger = createMockLogger();
+    const getLogger = jest.fn<LoggerInterface, [string]>(getLoggerImplementation ?? (() => logger));
+    jest.doMock('@jintianxiayu/logger', () => ({ LoggerFactory: { getLogger } }));
+    let cacheLogger: CacheLoggerModule | undefined;
+    jest.isolateModules(() => {
+        cacheLogger = jest.requireActual<CacheLoggerModule>('../src/core/cache-logger');
+    });
+    if (!cacheLogger) {
+        throw new Error('Cache logger module was not loaded');
+    }
+    return { cacheLogger, getLogger, logger };
+}
+
+afterEach(() => {
+    jest.resetModules();
+    jest.dontMock('@jintianxiayu/logger');
+});
+
+it('cache-operation-logging/L01 导入和 decorator 求值不初始化 Logger', () => {
+    const { getLogger } = loadCacheLogger();
+    const { Cache } = jest.requireActual<typeof import('../src/decorators/cache')>('../src/decorators/cache');
+    const { CacheEvict } = jest.requireActual<typeof import('../src/decorators/cache-evict')>(
+        '../src/decorators/cache-evict'
+    );
+
+    Cache('users');
+    CacheEvict('users');
+
+    expect(getLogger).not.toHaveBeenCalled();
+});
+
+it('cache-operation-logging/L02 首次运行期事件获取并复用应用命名 Logger', () => {
+    const { cacheLogger, getLogger, logger } = loadCacheLogger();
+
+    cacheLogger.logCacheEvent('cache.miss', logContext);
+    cacheLogger.logCacheEvent('cache.hit', { ...logContext, entryType: 'value' });
+
+    expect(getLogger).toHaveBeenCalledTimes(1);
+    expect(getLogger).toHaveBeenCalledWith('@jintianxiayu/cache-decorator');
+    expect(logger.debug).toHaveBeenCalledTimes(2);
+});
+
+it('cache-operation-logging/正常缓存决策使用 debug', () => {
+    const { cacheLogger, logger } = loadCacheLogger();
+    const events = [
+        'cache.pending_hit',
+        'cache.hit',
+        'cache.miss',
+        'cache.write_dispatched',
+        'cache.evict_dispatched',
+        'cache.evict_completed',
+    ] as const;
+
+    for (const event of events) {
+        cacheLogger.logCacheEvent(event, logContext);
+    }
+
+    expect(logger.debug).toHaveBeenCalledTimes(events.length);
+    expect(logger.debug.mock.calls.map((call) => (call[1] as { event: string }).event)).toEqual(events);
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+});
+
+it('cache-operation-logging/可恢复回退与淘汰跳过使用 warn', () => {
+    const { cacheLogger, logger } = loadCacheLogger();
+
+    cacheLogger.logCacheEvent('cache.key_fallback', { ...logContext, reason: 'resolver_error' });
+    cacheLogger.logCacheEvent('cache.evict_skipped', { ...logContext, reason: 'business_error' });
+
+    expect(logger.warn).toHaveBeenCalledTimes(2);
+    expect(logger.warn.mock.calls.map((call) => (call[1] as { event: string }).event)).toEqual([
+        'cache.key_fallback',
+        'cache.evict_skipped',
+    ]);
+    expect(logger.debug).not.toHaveBeenCalled();
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+});
+
+it('cache-operation-logging/缓存基础设施失败使用 error', () => {
+    const { cacheLogger, logger } = loadCacheLogger();
+    const providerError = new Error('redis unavailable');
+
+    cacheLogger.logCacheEvent('cache.operation_failed', {
+        ...logContext,
+        operation: 'read',
+        error: providerError,
+    });
+
+    expect(logger.error).toHaveBeenCalledWith(
+        'Cache operation failed',
+        expect.objectContaining({ event: 'cache.operation_failed', operation: 'read', error: providerError })
+    );
+    expect(logger.debug).not.toHaveBeenCalled();
+    expect(logger.info).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+});
+
+it('Logger 获取或写入同步失败时不向缓存调用方抛出', () => {
+    const getLoggerError = new Error('invalid logger config');
+    const failedGet = loadCacheLogger(() => {
+        throw getLoggerError;
+    });
+    expect(() => failedGet.cacheLogger.logCacheEvent('cache.miss', logContext)).not.toThrow();
+
+    const failedWrite = loadCacheLogger();
+    failedWrite.logger.debug.mockImplementationOnce(() => {
+        throw new Error('transport failed');
+    });
+    expect(() => failedWrite.cacheLogger.logCacheEvent('cache.miss', logContext)).not.toThrow();
+});
+
+it('Provider 日志标签将缺省和空名称稳定映射为 default', () => {
+    const { cacheLogger } = loadCacheLogger();
+
+    expect(cacheLogger.cacheProviderLabel(undefined)).toBe('default');
+    expect(cacheLogger.cacheProviderLabel('')).toBe('default');
+    expect(cacheLogger.cacheProviderLabel('redis-primary')).toBe('redis-primary');
+});