imean-service-engine 2.0.0 → 2.0.2

package/src/plugins/cache/adapter.ts

@@ -1,324 +0,0 @@
-/**
- * Cache Adapter 接口
- * 定义缓存存储的抽象接口，支持不同的存储后端
- */
-
-import { CacheItem } from "./types";
-
-/**
- * 缓存适配器接口
- */
-export interface CacheAdapter {
-  /**
-   * 获取缓存项
-   * @param key 缓存键
-   * @returns 缓存项，如果不存在或已过期则返回 null
-   */
-  get<T = any>(key: string): Promise<CacheItem<T> | null>;
-
-  /**
-   * 设置缓存项
-   * @param key 缓存键
-   * @param item 缓存项
-   */
-  set<T = any>(key: string, item: CacheItem<T>): Promise<void>;
-
-  /**
-   * 删除缓存项
-   * @param key 缓存键
-   * @returns 是否删除成功
-   */
-  delete(key: string): Promise<boolean>;
-
-  /**
-   * 清空所有缓存
-   */
-  clear(): Promise<void>;
-
-  /**
-   * 获取所有缓存键（用于统计）
-   * @returns 缓存键数组（不包含过期项）
-   */
-  keys(): Promise<string[]>;
-
-  /**
-   * 清理所有过期项（高效批量清理）
-   * @returns 清理的过期项数量
-   */
-  cleanupExpired?(): Promise<number>;
-
-  /**
-   * 获取缓存统计信息
-   */
-  getStats(): Promise<{
-    size: number;
-    entries: Array<{ key: string; expiresAt: number; createdAt: number }>;
-  }>;
-}
-
-/**
- * 内存缓存适配器
- * 使用 Map 存储，适合单进程应用
- *
- * 注意：过期项会在以下情况被自动清理：
- * 1. get() 时检查并删除过期项
- * 2. keys() 和 getStats() 会过滤过期项
- * 3. 建议通过 CachePlugin 的定期清理机制主动清理过期项
- */
-export class MemoryCacheAdapter implements CacheAdapter {
-  private cache: Map<string, CacheItem> = new Map();
-
-  async get<T = any>(key: string): Promise<CacheItem<T> | null> {
-    const item = this.cache.get(key);
-    if (!item) {
-      return null;
-    }
-
-    // 检查是否过期，过期则删除
-    if (item.expiresAt <= Date.now()) {
-      this.cache.delete(key);
-      return null;
-    }
-
-    return item as CacheItem<T>;
-  }
-
-  async set<T = any>(key: string, item: CacheItem<T>): Promise<void> {
-    this.cache.set(key, item);
-  }
-
-  async delete(key: string): Promise<boolean> {
-    return this.cache.delete(key);
-  }
-
-  async clear(): Promise<void> {
-    this.cache.clear();
-  }
-
-  async keys(): Promise<string[]> {
-    // 过滤过期项，避免返回无效键
-    const now = Date.now();
-    return Array.from(this.cache.entries())
-      .filter(([_, item]) => item.expiresAt > now)
-      .map(([key]) => key);
-  }
-
-  /**
-   * 清理所有过期项（高效批量清理）
-   * 这个方法比通过 keys() + get() + delete() 更高效
-   */
-  async cleanupExpired(): Promise<number> {
-    const now = Date.now();
-    let cleaned = 0;
-
-    // 直接遍历 Map 并删除过期项
-    for (const [key, item] of this.cache.entries()) {
-      if (item.expiresAt <= now) {
-        this.cache.delete(key);
-        cleaned++;
-      }
-    }
-
-    return cleaned;
-  }
-
-  async getStats(): Promise<{
-    size: number;
-    entries: Array<{ key: string; expiresAt: number; createdAt: number }>;
-  }> {
-    const now = Date.now();
-    const validEntries = Array.from(this.cache.entries())
-      .filter(([_, item]) => item.expiresAt > now)
-      .map(([key, item]) => ({
-        key,
-        expiresAt: item.expiresAt,
-        createdAt: item.createdAt,
-      }));
-
-    return {
-      size: validEntries.length,
-      entries: validEntries,
-    };
-  }
-}
-
-/**
- * Redis 缓存适配器配置
- */
-export interface RedisCacheAdapterOptions {
-  /**
-   * Redis 客户端实例（需要实现基本的 get/set/del/keys 方法）
-   * 可以是 ioredis、node-redis 等
-   */
-  client: {
-    get(key: string): Promise<string | null>;
-    set(
-      key: string,
-      value: string,
-      expiryMode?: string,
-      time?: number
-    ): Promise<string | null>;
-    del(key: string): Promise<number>;
-    keys(pattern: string): Promise<string[]>;
-  };
-
-  /**
-   * 键前缀，用于区分不同应用的缓存
-   * 默认：'cache:'
-   */
-  keyPrefix?: string;
-}
-
-/**
- * Redis 缓存适配器
- * 使用 Redis 作为存储后端，适合分布式应用
- *
- * 注意：Redis 本身支持 TTL（Time To Live），过期键会自动删除，
- * 因此不需要手动清理过期项。当使用 SET key value EX seconds 时，
- * Redis 会在过期后自动删除键。
- */
-export class RedisCacheAdapter implements CacheAdapter {
-  private client: RedisCacheAdapterOptions["client"];
-  private keyPrefix: string;
-
-  constructor(options: RedisCacheAdapterOptions) {
-    this.client = options.client;
-    this.keyPrefix = options.keyPrefix || "cache:";
-  }
-
-  private getKey(key: string): string {
-    return `${this.keyPrefix}${key}`;
-  }
-
-  async get<T = any>(key: string): Promise<CacheItem<T> | null> {
-    const redisKey = this.getKey(key);
-    const data = await this.client.get(redisKey);
-
-    // Redis 会自动删除过期键，如果键已过期，get() 会返回 null
-    if (!data) {
-      return null;
-    }
-
-    try {
-      const item: CacheItem<T> = JSON.parse(data);
-
-      // 双重检查：虽然 Redis 会自动删除过期键，但为了兼容性
-      // （某些 Redis 客户端或测试环境可能不会立即删除），
-      // 仍然检查 expiresAt。在真实 Redis 环境中，这个检查通常是多余的。
-      if (item.expiresAt <= Date.now()) {
-        await this.delete(key);
-        return null;
-      }
-
-      return item;
-    } catch (error) {
-      // 解析失败，删除无效数据
-      await this.delete(key);
-      return null;
-    }
-  }
-
-  async set<T = any>(key: string, item: CacheItem<T>): Promise<void> {
-    const redisKey = this.getKey(key);
-    const data = JSON.stringify(item);
-
-    // 计算 TTL（秒）
-    const ttl = Math.max(0, Math.floor((item.expiresAt - Date.now()) / 1000));
-
-    // 使用 SET 命令的 EX 选项设置过期时间
-    await this.client.set(redisKey, data, "EX", ttl);
-  }
-
-  async delete(key: string): Promise<boolean> {
-    const redisKey = this.getKey(key);
-    const result = await this.client.del(redisKey);
-    return result > 0;
-  }
-
-  async clear(): Promise<void> {
-    const pattern = `${this.keyPrefix}*`;
-    const keys = await this.client.keys(pattern);
-
-    if (keys.length > 0) {
-      // 批量删除（注意：这里假设 client 支持批量删除）
-      // 如果不支持，可以逐个删除
-      await Promise.all(keys.map((key) => this.client.del(key)));
-    }
-  }
-
-  async keys(): Promise<string[]> {
-    const pattern = `${this.keyPrefix}*`;
-    const redisKeys = await this.client.keys(pattern);
-
-    // 移除前缀
-    return redisKeys.map((key) => key.replace(this.keyPrefix, ""));
-  }
-
-  /**
-   * 清理所有过期项
-   *
-   * 注意：Redis 本身支持自动过期（通过 SET key value EX seconds），
-   * 过期键会被 Redis 自动删除。但在某些情况下（如测试环境、某些 Redis 客户端），
-   * 可能需要手动清理。此方法会检查并清理：
-   * 1. 已过期但尚未被 Redis 删除的键（双重保险）
-   * 2. JSON 解析失败的数据
-   */
-  async cleanupExpired(): Promise<number> {
-    const pattern = `${this.keyPrefix}*`;
-    const redisKeys = await this.client.keys(pattern);
-    let cleaned = 0;
-
-    // 检查并清理过期项和无效数据
-    for (const redisKey of redisKeys) {
-      const data = await this.client.get(redisKey);
-      if (!data) {
-        // 已被 Redis 自动过期删除，跳过
-        continue;
-      }
-
-      try {
-        const item: CacheItem = JSON.parse(data);
-        // 检查是否过期（双重保险，虽然 Redis 应该已经删除了）
-        if (item.expiresAt <= Date.now()) {
-          await this.client.del(redisKey);
-          cleaned++;
-        }
-      } catch {
-        // JSON 解析失败，删除无效数据
-        await this.client.del(redisKey);
-        cleaned++;
-      }
-    }
-
-    return cleaned;
-  }
-
-  async getStats(): Promise<{
-    size: number;
-    entries: Array<{ key: string; expiresAt: number; createdAt: number }>;
-  }> {
-    const allKeys = await this.keys();
-    const entries: Array<{
-      key: string;
-      expiresAt: number;
-      createdAt: number;
-    }> = [];
-
-    // 获取所有缓存项的元数据
-    for (const key of allKeys) {
-      const item = await this.get(key);
-      if (item) {
-        entries.push({
-          key,
-          expiresAt: item.expiresAt,
-          createdAt: item.createdAt,
-        });
-      }
-    }
-
-    return {
-      size: entries.length,
-      entries,
-    };
-  }
-}

package/src/plugins/cache/cache-plugin.test.ts

@@ -1,269 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { Testing } from "../../core/testing";
-import { Cache, CachePlugin } from "./index";
-
-describe("CachePlugin", () => {
-  let engine: ReturnType<typeof Testing.createTestEngine>["engine"];
-  let Module: ReturnType<typeof Testing.createTestEngine>["Module"];
-  let cachePlugin: CachePlugin;
-
-  beforeEach(() => {
-    // 每个测试都会创建新的 Factory，使用不同的 key，自动隔离
-    cachePlugin = new CachePlugin();
-    const testEngine = Testing.createTestEngine({ plugins: [cachePlugin] });
-    engine = testEngine.engine;
-    Module = testEngine.Module;
-  });
-
-  afterEach(async () => {
-    // 清理：停止引擎并清空缓存
-    if (engine) {
-      await engine.stop().catch(() => {});
-    }
-    await cachePlugin.clear();
-  });
-
-  describe("插件配置", () => {
-    it("应该有正确的插件名称", () => {
-      expect(cachePlugin.name).toBe("cache-plugin");
-    });
-
-    it("应该声明Module配置Schema", () => {
-      const schema = cachePlugin.getModuleOptionsSchema?.();
-      expect(schema).toBeDefined();
-      expect(schema?.validate).toBeDefined();
-    });
-
-    it("应该校验Module配置", () => {
-      const schema = cachePlugin.getModuleOptionsSchema?.();
-      if (!schema?.validate) return;
-
-      // 有效的配置
-      expect(schema.validate({ cacheDefaultTtl: 5000 })).toBe(true);
-
-      // 无效的配置（TTL为负数）
-      const result = schema.validate({ cacheDefaultTtl: -1 });
-      expect(result).not.toBe(true);
-      expect(typeof result).toBe("string");
-    });
-  });
-
-  describe("缓存功能", () => {
-    it("应该能够缓存方法结果", async () => {
-      let callCount = 0;
-
-      @Module("test-module")
-      class TestService {
-        @Cache({ ttl: 1000 })
-        async getData(id: number) {
-          callCount++;
-          return { id, value: `data-${id}` };
-        }
-      }
-
-      // 启动引擎，让插件正常初始化和处理 handlers
-      await engine.start();
-
-      const instance = engine.get(TestService);
-
-      // 第一次调用，应该执行原始方法
-      const result1 = await instance.getData(1);
-      expect(result1).toEqual({ id: 1, value: "data-1" });
-      expect(callCount).toBe(1);
-
-      // 第二次调用，应该从缓存返回
-      const result2 = await instance.getData(1);
-      expect(result2).toEqual({ id: 1, value: "data-1" });
-      expect(callCount).toBe(1); // 调用次数不变
-
-      await engine.stop();
-    });
-
-    it("应该支持自定义 key 函数", async () => {
-      @Module("test-module")
-      class TestService {
-        @Cache({
-          ttl: 1000,
-          key: (id: number) => ({ id }), // key 函数返回对象
-        })
-        async getData(id: number) {
-          return { id };
-        }
-      }
-
-      await engine.start();
-      const instance = engine.get(TestService);
-      await instance.getData(1);
-
-      const stats = await cachePlugin.getStats();
-      // 缓存键格式：模块名:方法名:hash
-      expect(stats.entries.length).toBeGreaterThan(0);
-      const cacheKey = stats.entries[0].key;
-      expect(cacheKey).toMatch(/^test-module:getData:[a-f0-9]{64}$/);
-
-      await engine.stop();
-    });
-
-    it("应该使用模块名和方法名作为缓存键前缀", async () => {
-      @Module("user-service")
-      class UserService {
-        @Cache({ ttl: 1000 })
-        async getUser(id: number) {
-          return { id, name: "User" };
-        }
-      }
-
-      @Module("order-service")
-      class OrderService {
-        @Cache({ ttl: 1000 })
-        async getOrder(id: number) {
-          return { id, total: 100 };
-        }
-      }
-
-      await engine.start();
-      const userInstance = engine.get(UserService);
-      const orderInstance = engine.get(OrderService);
-
-      await userInstance.getUser(1);
-      await orderInstance.getOrder(1);
-
-      const stats = await cachePlugin.getStats();
-      expect(stats.entries.length).toBe(2);
-
-      // 验证缓存键前缀
-      const userKey = stats.entries.find((e) => e.key.startsWith("user-service:getUser:"));
-      const orderKey = stats.entries.find((e) => e.key.startsWith("order-service:getOrder:"));
-
-      expect(userKey).toBeDefined();
-      expect(orderKey).toBeDefined();
-      expect(userKey?.key).not.toBe(orderKey?.key); // 不同模块的相同参数应该有不同的键
-
-      await engine.stop();
-    });
-
-    it("应该对 key 函数的返回值进行 ejson 序列化和 hash", async () => {
-      @Module("test-module")
-      class TestService {
-        @Cache({
-          ttl: 1000,
-          key: (id: number, name: string) => ({
-            id,
-            name,
-            date: new Date("2024-01-01"),
-            map: new Map([["key", "value"]]),
-          }),
-        })
-        async getData(id: number, name: string) {
-          return { id, name };
-        }
-      }
-
-      await engine.start();
-      const instance = engine.get(TestService);
-
-      // 相同参数应该使用相同的缓存键
-      await instance.getData(1, "test");
-      await instance.getData(1, "test");
-
-      const stats = await cachePlugin.getStats();
-      expect(stats.entries.length).toBe(1); // 应该只有一条缓存
-
-      // 不同参数应该使用不同的缓存键
-      await instance.getData(2, "test");
-      expect((await cachePlugin.getStats()).entries.length).toBe(2);
-
-      await engine.stop();
-    });
-
-    it("应该在不提供 key 函数时使用入参生成缓存键", async () => {
-      @Module("test-module")
-      class TestService {
-        @Cache({ ttl: 1000 })
-        async getData(id: number, name: string) {
-          return { id, name };
-        }
-      }
-
-      await engine.start();
-      const instance = engine.get(TestService);
-
-      await instance.getData(1, "test");
-
-      const stats = await cachePlugin.getStats();
-      expect(stats.entries.length).toBe(1);
-      const cacheKey = stats.entries[0].key;
-      // 缓存键格式：模块名:方法名:hash（hash 基于 args）
-      expect(cacheKey).toMatch(/^test-module:getData:[a-f0-9]{64}$/);
-
-      await engine.stop();
-    });
-
-    it("应该支持模块级默认TTL", async () => {
-      @Module("test-module", {
-        cacheDefaultTtl: 2000,
-      })
-      class TestService {
-        @Cache() // 使用模块默认TTL
-        async getData() {
-          return { value: "data" };
-        }
-      }
-
-      await engine.start();
-      const instance = engine.get(TestService);
-      await instance.getData();
-
-      const stats = await cachePlugin.getStats();
-      const entry = stats.entries[0];
-      if (entry) {
-        expect(entry.expiresAt - entry.createdAt).toBeGreaterThanOrEqual(2000);
-      } else {
-        throw new Error("No cache entry found");
-      }
-
-      await engine.stop();
-    });
-  });
-
-  describe("缓存管理", () => {
-    it("应该能够获取缓存统计信息", async () => {
-      const stats = await cachePlugin.getStats();
-      expect(stats).toHaveProperty("size");
-      expect(stats).toHaveProperty("entries");
-      expect(Array.isArray(stats.entries)).toBe(true);
-    });
-
-    it("应该能够清空所有缓存", async () => {
-      await cachePlugin.clear();
-      const stats = await cachePlugin.getStats();
-      expect(stats.size).toBe(0);
-    });
-
-    it("应该能够删除指定的缓存项", async () => {
-      @Module("test-module")
-      class TestService {
-        @Cache({ ttl: 1000 })
-        async getData(id: number) {
-          return { id };
-        }
-      }
-
-      await engine.start();
-      const instance = engine.get(TestService);
-      await instance.getData(1);
-
-      const stats = await cachePlugin.getStats();
-      const key = stats.entries[0]?.key;
-
-      if (key) {
-        const deleted = await cachePlugin.delete(key);
-        expect(deleted).toBe(true);
-        const newStats = await cachePlugin.getStats();
-        expect(newStats.size).toBe(0);
-      }
-
-      await engine.stop();
-    });
-  });
-});

package/src/plugins/cache/decorator.ts

@@ -1,26 +0,0 @@
-import { Handler } from "../../core/decorators";
-import { CacheOptions } from "./types";
-
-/**
- * Cache装饰器
- * 用于标记需要缓存的方法
- * 
- * @example
- * ```typescript
- * @Cache({ ttl: 5000 })
- * async getUser(id: number) {
- *   return { id, name: "John" };
- * }
- * ```
- */
-export function Cache(options: CacheOptions = {}) {
-  return Handler({
-    type: "cache",
-    options: {
-      ttl: options.ttl ?? 60000, // 默认1分钟
-      key: options.key, // key 函数
-      enabled: options.enabled ?? true,
-    },
-  });
-}
-

package/src/plugins/cache/index.ts

@@ -1,20 +0,0 @@
-/**
- * Cache Plugin - 缓存插件
- * 
- * 提供缓存功能，支持多种存储后端（内存、Redis等），支持TTL和自定义键生成器
- */
-
-export { CachePlugin } from "./plugin";
-export { Cache } from "./decorator";
-export {
-  CacheAdapter,
-  MemoryCacheAdapter,
-  RedisCacheAdapter,
-} from "./adapter";
-export type {
-  CacheModuleOptions,
-  CacheOptions,
-  CacheItem,
-} from "./types";
-export type { RedisCacheAdapterOptions } from "./adapter";
-