@jintianxiayu/cache-decorator 0.1.2

package/dist/decorators/cache.d.ts

@@ -0,0 +1,37 @@
+import 'reflect-metadata';
+/**
+ * 缓存 key 解析器类型
+ * - null: 使用自动生成逻辑
+ * - string: 直接作为 key 值的一部分
+ * - function: 接收方法参数数组，返回自定义字符串
+ */
+export type CacheKeyResolver = null | string | ((...args: unknown[]) => string);
+/**
+ * @Cache 装饰器配置项
+ */
+export interface CacheOptions {
+    /**
+     * 过期时间（秒）
+     */
+    ttl?: number;
+    /**
+     * 指定 CacheProvider 名称
+     */
+    providerName?: string;
+    /**
+     * 自定义缓存 key 生成逻辑
+     * - undefined/null: 使用默认逻辑 KeyBuilder.build(cacheName, args)
+     * - string: 使用 KeyBuilder.build(cacheName, [key])
+     * - function: 调用函数后使用 KeyBuilder.build(cacheName, [result])
+     */
+    key?: CacheKeyResolver;
+}
+/**
+ * 缓存装饰器
+ * 为方法添加声明式缓存功能，支持 TTL 过期和请求合并
+ * @param cacheName 缓存名称
+ * @param options 配置项
+ */
+export declare function Cache(cacheName: string, options?: CacheOptions): <T>(_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => void;
+export { CacheProviderRegistry } from '../core/cache-provider-registry';
+//# sourceMappingURL=cache.d.ts.map

package/dist/decorators/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/decorators/cache.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAK1B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC;CACxB;AA4CD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,IAC5C,CAAC,EAChB,SAAS,MAAM,EACf,cAAc,MAAM,EACpB,YAAY,kBAAkB,UAsCjC;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/decorators/cache.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheProviderRegistry = void 0;
+exports.Cache = Cache;
+require("reflect-metadata");
+const cache_provider_registry_1 = require("../core/cache-provider-registry");
+const key_builder_1 = require("../core/key-builder");
+const pending_cache_1 = require("../core/pending-cache");
+const pendingCache = new pending_cache_1.PendingCache();
+/**
+ * 解析缓存 key
+ * @param cacheName 缓存名称
+ * @param keyResolver key 解析器
+ * @param args 方法参数数组
+ * @returns 解析后的缓存 key
+ */
+function resolveCacheKey(cacheName, keyResolver, args) {
+    if (keyResolver === undefined || keyResolver === null) {
+        return key_builder_1.KeyBuilder.build(cacheName, args);
+    }
+    if (typeof keyResolver === 'string') {
+        return key_builder_1.KeyBuilder.build(cacheName, [keyResolver]);
+    }
+    try {
+        return key_builder_1.KeyBuilder.build(cacheName, [keyResolver(...args)]);
+    }
+    catch {
+        return key_builder_1.KeyBuilder.build(cacheName, args);
+    }
+}
+/**
+ * 缓存装饰器
+ * 为方法添加声明式缓存功能，支持 TTL 过期和请求合并
+ * @param cacheName 缓存名称
+ * @param options 配置项
+ */
+function Cache(cacheName, options) {
+    return function (_target, _propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const cacheKey = resolveCacheKey(cacheName, options?.key, args);
+            const providerName = options?.providerName;
+            const provider = cache_provider_registry_1.CacheProviderRegistry.get(providerName);
+            const cached = await provider.get(cacheKey);
+            if (cached !== undefined) {
+                const entry = cached;
+                if ('error' in entry) {
+                    throw entry.error;
+                }
+                return entry.value;
+            }
+            const pending = pendingCache.get(cacheKey);
+            if (pending) {
+                return pending;
+            }
+            const promise = (async () => {
+                try {
+                    const result = await originalMethod.apply(this, args);
+                    provider.set(cacheKey, { value: result }, options?.ttl);
+                    return result;
+                }
+                catch (error) {
+                    provider.set(cacheKey, { error }, options?.ttl);
+                    throw error;
+                }
+            })();
+            pendingCache.set(cacheKey, promise);
+            return promise;
+        };
+    };
+}
+var cache_provider_registry_2 = require("../core/cache-provider-registry");
+Object.defineProperty(exports, "CacheProviderRegistry", { enumerable: true, get: function () { return cache_provider_registry_2.CacheProviderRegistry; } });
+//# sourceMappingURL=cache.js.map

package/dist/decorators/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/decorators/cache.ts"],"names":[],"mappings":";;;AAoFA,sBA0CC;AA9HD,4BAA0B;AAC1B,6EAAwE;AACxE,qDAAiD;AACjD,yDAAqD;AAoDrD,MAAM,YAAY,GAAG,IAAI,4BAAY,EAAE,CAAC;AAExC;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,SAAiB,EAAE,WAAyC,EAAE,IAAe;IACpG,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC;QACH,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,wBAAU,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,KAAK,CAAC,SAAiB,EAAE,OAAsB;IAC7D,OAAO,UACL,OAAe,EACf,YAAoB,EACpB,UAA8B;QAE9B,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC;QAExC,UAAU,CAAC,KAAK,GAAG,KAAK,WAAW,GAAG,IAAe;YACnD,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YAChE,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;YAC3C,MAAM,QAAQ,GAAG,+CAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAEzD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,KAAK,GAAG,MAAuB,CAAC;gBACtC,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;oBACrB,MAAM,KAAK,CAAC,KAAK,CAAC;gBACpB,CAAC;gBACD,OAAO,KAAK,CAAC,KAAK,CAAC;YACrB,CAAC;YAED,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAI,QAAQ,CAAC,CAAC;YAC9C,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,OAAO,CAAC;YACjB,CAAC;YAED,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC1B,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBACtD,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAmB,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;oBACzE,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAmB,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;oBACjE,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC,CAAC,EAAE,CAAC;YAEL,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,2EAAwE;AAA/D,gIAAA,qBAAqB,OAAA"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+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';
+export * from './decorators/cache';
+export * from './decorators/cache-evict';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./core/cache-provider"), exports);
+__exportStar(require("./core/cache-provider-registry"), exports);
+__exportStar(require("./core/key-builder"), exports);
+__exportStar(require("./core/native-cache"), exports);
+__exportStar(require("./core/pending-cache"), exports);
+__exportStar(require("./core/redis-cache"), exports);
+__exportStar(require("./decorators/cache"), exports);
+__exportStar(require("./decorators/cache-evict"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,wDAAsC;AACtC,iEAA+C;AAC/C,qDAAmC;AACnC,sDAAoC;AACpC,uDAAqC;AACrC,qDAAmC;AACnC,qDAAmC;AACnC,2DAAyC"}

package/jest.config.js

@@ -0,0 +1,14 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>'],
+  testMatch: ['**/test/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts'
+  ],
+  transform: {
+    '^.+\\.ts$': 'ts-jest'
+  }
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "@jintianxiayu/cache-decorator",
+    "version": "0.1.2",
+    "description": "Method caching decorators for TypeScript",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc",
+        "test": "jest",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "reflect-metadata": "^0.2.2"
+    },
+    "devDependencies": {
+        "@types/ioredis": "^4.28.10",
+        "@types/node": "^22.10.0",
+        "ioredis": "^5.10.1",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.2.0",
+        "typescript": "^5.7.0"
+    },
+    "peerDependencies": {
+        "reflect-metadata": "^0.2.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "gitHead": "357e736abbe6b25a707663c1b9e027b2e8b532a6"
+}

package/src/core/cache-provider-registry.ts

@@ -0,0 +1,53 @@
+import { CacheProvider } from './cache-provider';
+
+const providers = new Map<string, CacheProvider>();
+let defaultName: string | undefined;
+
+/**
+ * 全局缓存提供者注册表
+ * 用于注册和获取不同类型的 CacheProvider
+ */
+export class CacheProviderRegistry {
+  /**
+   * 注册缓存提供者
+   * @param name 提供者名称
+   * @param provider 缓存提供者实例
+   */
+  static register(name: string, provider: CacheProvider): void {
+    providers.set(name, provider);
+  }
+
+  /**
+   * 获取缓存提供者
+   * @param name 提供者名称，不指定则使用默认提供者
+   * @returns 缓存提供者实例
+   * @throws 未注册且无默认提供者时抛出错误
+   */
+  static get(name?: string): CacheProvider {
+    const providerName = name || defaultName;
+    if (!providerName) {
+      throw new Error('No CacheProvider registered and no default set');
+    }
+    const provider = providers.get(providerName);
+    if (!provider) {
+      throw new Error(`CacheProvider "${providerName}" not found`);
+    }
+    return provider;
+  }
+
+  /**
+   * 设置默认缓存提供者
+   * @param name 提供者名称
+   */
+  static setDefault(name: string): void {
+    defaultName = name;
+  }
+
+  /**
+   * 清空注册表
+   */
+  static clear(): void {
+    providers.clear();
+    defaultName = undefined;
+  }
+}

package/src/core/cache-provider.ts

@@ -0,0 +1,37 @@
+/**
+ * 缓存提供者接口，定义缓存存储后端的统一契约
+ * 支持可插拔的缓存实现（Memory、Redis、自定义）
+ */
+export interface CacheProvider {
+  /**
+   * 获取缓存值
+   * @param key 缓存键
+   * @returns 缓存值，不存在或已过期返回 undefined
+   */
+  get<T>(key: string): T | undefined | Promise<T | undefined>;
+
+  /**
+   * 设置缓存值
+   * @param key 缓存键
+   * @param value 缓存值
+   * @param ttl 过期时间（秒），不设置则永不过期
+   */
+  set<T>(key: string, value: T, ttl?: number): void | Promise<void>;
+
+  /**
+   * 删除指定缓存
+   * @param key 缓存键
+   */
+  delete(key: string): void | Promise<void>;
+
+  /**
+   * 清除所有缓存
+   */
+  clear(): void | Promise<void>;
+
+  /**
+   * 根据模式删除匹配的缓存键
+   * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
+   */
+  deleteByPattern(pattern: string): void | Promise<void>;
+}

package/src/core/key-builder.ts

@@ -0,0 +1,31 @@
+/**
+ * 缓存 Key 构建器
+ * 负责将缓存名称和参数转换为统一的 key 字符串
+ */
+export class KeyBuilder {
+  /**
+   * 构建缓存 key
+   * @param cacheName 缓存名称
+   * @param args 方法参数列表
+   * @returns 格式为 {cacheName}:{serializedArgs} 的 key 字符串
+   */
+  static build(cacheName: string, args: unknown[]): string {
+    if (args.length === 0) {
+      return cacheName;
+    }
+    const serializedArgs = args
+      .map(arg => {
+        if (arg === null || arg === undefined) return 'null';
+        if (typeof arg === 'object') {
+          try {
+            return JSON.stringify(arg);
+          } catch {
+            return String(arg);
+          }
+        }
+        return String(arg);
+      })
+      .join('&');
+    return `${cacheName}:${serializedArgs}`;
+  }
+}

package/src/core/native-cache.ts

@@ -0,0 +1,53 @@
+import { CacheProvider } from './cache-provider';
+
+/**
+ * 缓存条目结构
+ */
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number | null;
+}
+
+/**
+ * 内存缓存提供者，基于 Map 实现
+ * 适用于单机应用，缓存随进程重启清除
+ */
+export class MemoryCacheProvider implements CacheProvider {
+  private cache = new Map<string, CacheEntry<unknown>>();
+
+  get<T>(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return undefined;
+    }
+    return entry.value as T;
+  }
+
+  set<T>(key: string, value: T, ttl?: number): void {
+    const expiresAt = ttl ? Date.now() + ttl * 1000 : null;
+    this.cache.set(key, { value, expiresAt });
+  }
+
+  delete(key: string): void {
+    this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * 根据模式删除匹配的缓存键
+   * @param pattern glob模式字符串（如 user:*），末尾的 * 作为前缀匹配
+   */
+  deleteByPattern(pattern: string): void {
+    const prefix = pattern.replace(/\*$/, '');
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+}

package/src/core/pending-cache.ts

@@ -0,0 +1,26 @@
+/**
+ * 请求合并缓存
+ * 用于在并发场景下返回同一个 Promise，避免重复执行
+ */
+export class PendingCache {
+  private pending = new Map<string, Promise<unknown>>();
+
+  get<T>(key: string): Promise<T> | undefined {
+    return this.pending.get(key) as Promise<T> | undefined;
+  }
+
+  set<T>(key: string, promise: Promise<T>): void {
+    this.pending.set(key, promise);
+    promise.finally(() => {
+      this.pending.delete(key);
+    });
+  }
+
+  delete(key: string): void {
+    this.pending.delete(key);
+  }
+
+  clear(): void {
+    this.pending.clear();
+  }
+}

package/src/core/redis-cache.ts

@@ -0,0 +1,62 @@
+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');
+  }
+}

package/src/decorators/cache-evict.ts

@@ -0,0 +1,73 @@
+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';

package/src/decorators/cache.ts

@@ -0,0 +1,129 @@
+import 'reflect-metadata';
+import { CacheProviderRegistry } from '../core/cache-provider-registry';
+import { KeyBuilder } from '../core/key-builder';
+import { PendingCache } from '../core/pending-cache';
+
+/**
+ * 缓存 key 解析器类型
+ * - null: 使用自动生成逻辑
+ * - string: 直接作为 key 值的一部分
+ * - function: 接收方法参数数组，返回自定义字符串
+ */
+export type CacheKeyResolver = null | string | ((...args: unknown[]) => string);
+
+/**
+ * @Cache 装饰器配置项
+ */
+export interface CacheOptions {
+  /**
+   * 过期时间（秒）
+   */
+  ttl?: number;
+
+  /**
+   * 指定 CacheProvider 名称
+   */
+  providerName?: string;
+
+  /**
+   * 自定义缓存 key 生成逻辑
+   * - undefined/null: 使用默认逻辑 KeyBuilder.build(cacheName, args)
+   * - string: 使用 KeyBuilder.build(cacheName, [key])
+   * - function: 调用函数后使用 KeyBuilder.build(cacheName, [result])
+   */
+  key?: CacheKeyResolver;
+}
+
+/**
+ * 成功缓存条目
+ */
+interface SuccessCacheEntry<T> {
+  value: T;
+}
+
+/**
+ * 错误缓存条目
+ */
+interface ErrorCacheEntry {
+  error: unknown;
+}
+
+/**
+ * 缓存条目联合类型
+ */
+type CacheEntry<T> = SuccessCacheEntry<T> | ErrorCacheEntry;
+
+const pendingCache = new PendingCache();
+
+/**
+ * 解析缓存 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);
+  }
+}
+
+/**
+ * 缓存装饰器
+ * 为方法添加声明式缓存功能，支持 TTL 过期和请求合并
+ * @param cacheName 缓存名称
+ * @param options 配置项
+ */
+export function Cache(cacheName: string, options?: CacheOptions) {
+  return function <T>(
+    _target: object,
+    _propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    const originalMethod = descriptor.value;
+
+    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;
+      }
+
+      const pending = pendingCache.get<T>(cacheKey);
+      if (pending) {
+        return pending;
+      }
+
+      const promise = (async () => {
+        try {
+          const result = await originalMethod.apply(this, args);
+          provider.set(cacheKey, { value: result } as CacheEntry<T>, options?.ttl);
+          return result;
+        } catch (error) {
+          provider.set(cacheKey, { error } as CacheEntry<T>, options?.ttl);
+          throw error;
+        }
+      })();
+
+      pendingCache.set(cacheKey, promise);
+      return promise;
+    };
+  };
+}
+
+export { CacheProviderRegistry } from '../core/cache-provider-registry';