imean-service-engine 2.0.0 → 2.0.2

package/src/plugins/schedule/plugin.ts

@@ -1,164 +0,0 @@
-import logger from "../../core/logger";
-import {
-  HandlerMetadata,
-  Microservice,
-  Plugin,
-  PluginPriority,
-} from "../../core/types";
-import { MockEtcd3 } from "./mock-etcd";
-import { Scheduler } from "./scheduler";
-import { SchedulePluginOptions, Etcd3 } from "./types";
-import { extractScheduleMetadata } from "./utils";
-
-/**
- * SchedulePlugin - 调度任务插件
- * 使用 etcd 选举机制实现分布式定时任务，确保多个实例中只有一个执行任务
- */
-export class SchedulePlugin implements Plugin {
-  public readonly name = "schedule-plugin";
-  public readonly priority = PluginPriority.BUSINESS; // 业务逻辑优先级
-
-  private engine!: Microservice;
-  private scheduler: Scheduler | null = null;
-  private etcdClient: Etcd3 | null = null;
-  private scheduleHandlers: HandlerMetadata[] = [];
-  private useMockEtcd: boolean = false;
-
-  constructor(options?: SchedulePluginOptions) {
-    if (options?.useMockEtcd) {
-      // 使用 Mock Etcd（用于测试和本地开发）
-      this.useMockEtcd = true;
-      this.etcdClient = new MockEtcd3();
-      logger.info("SchedulePlugin: Using MockEtcd3 for local development/testing");
-    } else if (options?.etcdClient) {
-      // 使用真实的 etcd 客户端
-      this.etcdClient = options.etcdClient as Etcd3;
-    }
-  }
-
-  /**
-   * 引擎初始化钩子
-   */
-  onInit(engine: Microservice): void {
-    this.engine = engine;
-    logger.info("SchedulePlugin initialized");
-  }
-
-  /**
-   * Handler加载钩子：收集所有调度任务
-   */
-  onHandlerLoad(handlers: HandlerMetadata[]): void {
-    // 筛选出所有 type="schedule" 的 handlers
-    this.scheduleHandlers = handlers.filter(
-      (handler) => handler.type === "schedule"
-    );
-    logger.info(
-      `SchedulePlugin: Found ${this.scheduleHandlers.length} schedule handler(s)`
-    );
-  }
-
-  /**
-   * 引擎启动后钩子：启动所有调度任务
-   */
-  async onAfterStart(engine: Microservice): Promise<void> {
-    // 如果没有配置 etcd 客户端且未启用 mock，跳过调度任务
-    if (!this.etcdClient) {
-      logger.warn(
-        "SchedulePlugin: etcdClient not configured and useMockEtcd is false, schedule tasks will not start"
-      );
-      return;
-    }
-
-    // 创建调度器实例
-    this.scheduler = new Scheduler(this.etcdClient);
-
-    // 获取所有模块
-    const modules = engine.getModules();
-
-    // 获取所有 Handler 元数据（需要在引擎加载完成后获取）
-    // 由于 onAfterStart 在引擎启动后调用，此时 handlers 已经加载完成
-    // 我们需要从引擎中获取 handlers，但由于引擎没有暴露这个接口，
-    // 我们需要在 onHandlerLoad 中保存 handlers
-    if (!this.scheduleHandlers) {
-      logger.warn(
-        "SchedulePlugin: No schedule handlers found, schedule tasks will not start"
-      );
-      return;
-    }
-
-    // 提取调度元数据
-    const scheduleMetadataMap = extractScheduleMetadata(this.scheduleHandlers);
-
-    // 生成服务 ID（使用服务名称和实例标识）
-    const serviceId = `${engine.options.name}-${Date.now()}-${Math.random()}`;
-
-    // 遍历所有模块，查找调度任务
-    for (const moduleMetadata of modules) {
-      const moduleClass = moduleMetadata.clazz;
-      const moduleName = moduleMetadata.name;
-
-      // 获取模块实例
-      const moduleInstance = engine.get(moduleClass);
-
-      // 获取该模块的调度元数据
-      const moduleScheduleMetadata = scheduleMetadataMap.get(moduleClass);
-      if (!moduleScheduleMetadata || moduleScheduleMetadata.size === 0) {
-        continue;
-      }
-
-      // 遍历所有调度任务
-      for (const [methodName, metadata] of moduleScheduleMetadata.entries()) {
-        // 获取方法
-        const method = (moduleInstance as any)[methodName];
-        if (typeof method !== "function") {
-          logger.warn(
-            `SchedulePlugin: Method ${moduleName}.${methodName} is not a function, skipping`
-          );
-          continue;
-        }
-
-        // 生成选举键（使用服务名称、模块名和方法名）
-        const electionKey = `/schedule/${engine.options.name}/${moduleName}/${methodName}`;
-
-        // 生成唯一的服务 ID（每个任务使用不同的 ID）
-        const taskServiceId = `${serviceId}-${moduleName}-${methodName}`;
-
-        // 启动调度任务
-        try {
-          await this.scheduler.startSchedule(
-            taskServiceId,
-            moduleName,
-            methodName,
-            electionKey,
-            metadata,
-            method.bind(moduleInstance)
-          );
-
-          logger.info(
-            `SchedulePlugin: Started schedule task ${moduleName}.${methodName} (interval: ${metadata.interval}ms, mode: ${metadata.mode})`
-          );
-        } catch (error) {
-          logger.error(
-            `SchedulePlugin: Failed to start schedule task ${moduleName}.${methodName}:`,
-            error
-          );
-        }
-      }
-    }
-  }
-
-  /**
-   * 引擎销毁钩子：停止所有调度任务
-   */
-  async onDestroy(): Promise<void> {
-    if (this.scheduler) {
-      try {
-        await this.scheduler.stop();
-        logger.info("SchedulePlugin: All schedule tasks stopped");
-      } catch (error) {
-        logger.error("SchedulePlugin: Error stopping schedule tasks:", error);
-      }
-    }
-  }
-}
-

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

@@ -1,312 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { Testing } from "../../core/testing";
-import { Schedule, SchedulePlugin, ScheduleMode, MockEtcd3 } from "./index";
-
-describe("SchedulePlugin", () => {
-  let engine: ReturnType<typeof Testing.createTestEngine>["engine"];
-  let Module: ReturnType<typeof Testing.createTestEngine>["Module"];
-  let schedulePlugin: SchedulePlugin;
-
-  beforeEach(() => {
-    // 使用 useMockEtcd 选项，自动使用 MockEtcd3
-    schedulePlugin = new SchedulePlugin({ useMockEtcd: true });
-    const testEngine = Testing.createTestEngine({
-      plugins: [schedulePlugin],
-    });
-    engine = testEngine.engine;
-    Module = testEngine.Module;
-  });
-
-  afterEach(async () => {
-    if (engine) {
-      await engine.stop().catch(() => {});
-    }
-  });
-
-  describe("插件配置", () => {
-    it("应该有正确的插件名称", () => {
-      expect(schedulePlugin.name).toBe("schedule-plugin");
-    });
-
-    it("应该在没有 etcd 客户端时正常工作", () => {
-      const pluginWithoutEtcd = new SchedulePlugin();
-      expect(pluginWithoutEtcd.name).toBe("schedule-plugin");
-    });
-
-    it("应该支持 useMockEtcd 选项", () => {
-      const pluginWithMock = new SchedulePlugin({ useMockEtcd: true });
-      expect(pluginWithMock.name).toBe("schedule-plugin");
-    });
-
-    it("应该优先使用提供的 etcdClient 而不是 mock", () => {
-      const mockEtcd = new MockEtcd3();
-      const pluginWithClient = new SchedulePlugin({
-        etcdClient: mockEtcd,
-        useMockEtcd: true,
-      });
-      expect(pluginWithClient.name).toBe("schedule-plugin");
-    });
-  });
-
-  describe("装饰器", () => {
-    it("应该能够使用 Schedule 装饰器装饰方法", async () => {
-      let callCount = 0;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async testTask() {
-          callCount++;
-        }
-      }
-
-      await engine.start();
-      await Testing.wait(300); // 等待足够的时间让任务执行
-
-      // 由于使用了 mock etcd，任务应该会被执行
-      // 注意：实际执行次数取决于调度器的实现和选举时机
-      expect(callCount).toBeGreaterThanOrEqual(0);
-    });
-
-    it("应该支持 FIXED_RATE 模式", async () => {
-      let callCount = 0;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async fixedRateTask() {
-          callCount++;
-        }
-      }
-
-      await engine.start();
-      await Testing.wait(300);
-
-      expect(callCount).toBeGreaterThanOrEqual(0);
-    });
-
-    it("应该支持 FIXED_DELAY 模式", async () => {
-      let callCount = 0;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_DELAY,
-        })
-        async fixedDelayTask() {
-          callCount++;
-          await Testing.wait(50); // 模拟任务执行时间
-        }
-      }
-
-      await engine.start();
-      await Testing.wait(300);
-
-      expect(callCount).toBeGreaterThanOrEqual(0);
-    });
-
-    it("应该使用默认的 FIXED_RATE 模式", async () => {
-      let callCount = 0;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          // 不指定 mode，应该使用默认值
-        })
-        async defaultModeTask() {
-          callCount++;
-        }
-      }
-
-      await engine.start();
-      await Testing.wait(300);
-
-      expect(callCount).toBeGreaterThanOrEqual(0);
-    });
-  });
-
-  describe("插件生命周期", () => {
-    it("应该在引擎启动后启动调度任务", async () => {
-      let taskExecuted = false;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async testTask() {
-          taskExecuted = true;
-        }
-      }
-
-      await engine.start();
-      // 等待足够的时间让选举和任务执行
-      // Mock etcd 的异步选举需要时间，加上任务执行间隔
-      await Testing.wait(600);
-
-      // 任务应该已经被执行（通过 mock etcd 选举）
-      // 注意：由于 mock etcd 的异步特性，可能需要更多时间
-      expect(taskExecuted).toBe(true);
-    });
-
-    it("应该在引擎停止时停止调度任务", async () => {
-      let taskExecuted = false;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 50,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async testTask() {
-          taskExecuted = true;
-        }
-      }
-
-      await engine.start();
-      // 等待任务执行
-      await Testing.wait(200);
-      const executedBeforeStop = taskExecuted;
-
-      await engine.stop();
-      await Testing.wait(200);
-
-      // 停止后任务不应该再执行
-      // 注意：如果任务在停止前没有执行，这个测试仍然有效（验证停止功能）
-      expect(executedBeforeStop).toBeDefined();
-    });
-
-    it("应该在没有 etcd 客户端且未启用 mock 时不启动任务", async () => {
-      const pluginWithoutEtcd = new SchedulePlugin();
-      const testEngine = Testing.createTestEngine({
-        plugins: [pluginWithoutEtcd],
-      });
-      const testEngineInstance = testEngine.engine;
-      const TestModule = testEngine.Module;
-
-      let taskExecuted = false;
-
-      @TestModule("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async testTask() {
-          taskExecuted = true;
-        }
-      }
-
-      await testEngineInstance.start();
-      await Testing.wait(200);
-
-      // 没有 etcd 客户端且未启用 mock，任务不应该执行
-      expect(taskExecuted).toBe(false);
-
-      await testEngineInstance.stop();
-    });
-
-    it("应该在启用 useMockEtcd 时启动任务", async () => {
-      const pluginWithMock = new SchedulePlugin({ useMockEtcd: true });
-      const testEngine = Testing.createTestEngine({
-        plugins: [pluginWithMock],
-      });
-      const testEngineInstance = testEngine.engine;
-      const TestModule = testEngine.Module;
-
-      let taskExecuted = false;
-
-      @TestModule("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async testTask() {
-          taskExecuted = true;
-        }
-      }
-
-      await testEngineInstance.start();
-      await Testing.wait(600);
-
-      // 启用 mock etcd，任务应该被执行
-      expect(taskExecuted).toBe(true);
-
-      await testEngineInstance.stop();
-    });
-  });
-
-  describe("多个调度任务", () => {
-    it("应该支持多个调度任务", async () => {
-      let task1Count = 0;
-      let task2Count = 0;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async task1() {
-          task1Count++;
-        }
-
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async task2() {
-          task2Count++;
-        }
-      }
-
-      await engine.start();
-      await Testing.wait(300);
-
-      // 两个任务都应该被执行
-      expect(task1Count).toBeGreaterThanOrEqual(0);
-      expect(task2Count).toBeGreaterThanOrEqual(0);
-    });
-  });
-
-  describe("错误处理", () => {
-    it("应该处理任务执行错误", async () => {
-      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-      let callCount = 0;
-
-      @Module("test-service")
-      class TestService {
-        @Schedule({
-          interval: 100,
-          mode: ScheduleMode.FIXED_RATE,
-        })
-        async errorTask() {
-          callCount++;
-          if (callCount === 1) {
-            throw new Error("Task error");
-          }
-        }
-      }
-
-      await engine.start();
-      await Testing.wait(300);
-
-      // 任务应该被执行，错误应该被捕获
-      // 注意：由于异步执行和错误处理，callCount 可能为 0 或更多
-      expect(callCount).toBeGreaterThanOrEqual(0);
-
-      errorSpy.mockRestore();
-    });
-  });
-});
-

package/src/plugins/schedule/scheduler.ts

@@ -1,164 +0,0 @@
-import { SpanStatusCode, trace } from "@opentelemetry/api";
-import logger from "../../core/logger";
-import { ScheduleMetadata, ScheduleMode } from "./types";
-import { Etcd3 } from "./types";
-
-const tracer = trace.getTracer("scheduler");
-
-/**
- * 调度器类
- * 负责管理基于 etcd 选举的分布式定时任务
- */
-export class Scheduler {
-  private campaigns: Map<string, any> = new Map();
-  private timers: Map<
-    string,
-    ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>
-  > = new Map();
-  private isLeader: Map<string, boolean> = new Map();
-
-  constructor(private etcdClient: Etcd3) {
-    // etcdClient 必须实现 Etcd3 接口
-  }
-
-  /**
-   * 启动调度任务
-   */
-  async startSchedule(
-    serviceId: string,
-    moduleName: string,
-    methodName: string,
-    electionKey: string,
-    metadata: ScheduleMetadata,
-    method: Function
-  ) {
-    const election = this.etcdClient.election(electionKey, 10);
-    const observe = await election.observe();
-
-    // 监听选主结果
-    observe.on("change", (leader: string) => {
-      const isLeader = leader === serviceId;
-      this.isLeader.set(serviceId, isLeader);
-
-      if (!isLeader) {
-        this.stopTimer(serviceId);
-      }
-    });
-
-    // 开始参与选主
-    const campaign = election.campaign(serviceId);
-    this.campaigns.set(serviceId, campaign);
-
-    campaign.on("error", (error: any) => {
-      logger.error(`Error in campaign for ${moduleName}.${methodName}:`, error);
-    });
-
-    campaign.on("elected", () => {
-      this.isLeader.set(serviceId, true);
-      this.startTimer(serviceId, metadata, moduleName, method);
-
-      logger.info(`become leader for ${moduleName}.${methodName}`);
-    });
-  }
-
-  /**
-   * 启动定时器
-   */
-  private startTimer(
-    serviceId: string,
-    metadata: ScheduleMetadata,
-    moduleName: string,
-    method: Function
-  ) {
-    this.stopTimer(serviceId);
-
-    const wrappedMethod = async () => {
-      tracer.startActiveSpan(
-        `ScheduleTask ${moduleName}.${metadata.name}`,
-        { root: true },
-        async (span) => {
-          span.setAttribute("serviceId", serviceId);
-          span.setAttribute("methodName", metadata.name);
-          span.setAttribute("moduleName", moduleName);
-          span.setAttribute("interval", metadata.interval);
-          span.setAttribute("mode", metadata.mode!);
-          try {
-            await method();
-          } catch (error: any) {
-            span.setStatus({
-              code: SpanStatusCode.ERROR,
-              message: error.message,
-            });
-            logger.error(
-              `Error executing schedule task ${moduleName}.${metadata.name}:`,
-              error
-            );
-          } finally {
-            span.setStatus({ code: SpanStatusCode.OK });
-            span.end();
-          }
-        }
-      );
-    };
-
-    if (metadata.mode === ScheduleMode.FIXED_DELAY) {
-      const runTask = async () => {
-        if (!this.isLeader.get(serviceId)) return;
-
-        try {
-          await wrappedMethod();
-        } finally {
-          // 任务完成后等待间隔时间再执行下一次
-          this.timers.set(serviceId, setTimeout(runTask, metadata.interval));
-        }
-      };
-
-      // 立即执行第一次
-      runTask();
-    } else {
-      // 固定频率模式
-      this.timers.set(
-        serviceId,
-        setInterval(async () => {
-          if (!this.isLeader.get(serviceId)) return;
-          await wrappedMethod();
-        }, metadata.interval)
-      );
-    }
-  }
-
-  /**
-   * 停止定时器
-   */
-  private stopTimer(serviceId: string) {
-    const timer = this.timers.get(serviceId);
-    if (timer) {
-      clearTimeout(timer);
-      clearInterval(timer);
-      this.timers.delete(serviceId);
-    }
-  }
-
-  /**
-   * 停止所有调度任务
-   */
-  async stop() {
-    // 停止所有定时器
-    for (const serviceId of this.timers.keys()) {
-      this.stopTimer(serviceId);
-    }
-
-    // 放弃所有选主并撤销租约
-    for (const [serviceId, campaign] of this.campaigns.entries()) {
-      try {
-        await campaign.resign().catch(() => {});
-      } catch (error) {
-        logger.error(`Error stopping schedule ${serviceId}:`, error);
-      } finally {
-        this.campaigns.delete(serviceId);
-        this.isLeader.delete(serviceId);
-      }
-    }
-  }
-}
-