imean-service-engine 2.0.0 → 2.0.2

package/src/core/engine.ts

@@ -1,635 +0,0 @@
-import { serve } from "@hono/node-server";
-import { Hono } from "hono";
-import * as net from "net";
-import { getClassesByKey, getClassMetadata } from "../metadata/metadata";
-import { getAllHandlerMetadata } from "./decorators";
-import { DuplicateModuleError, PluginNameRequiredError } from "./errors";
-import logger from "./logger";
-import {
-  Class,
-  HandlerMetadata,
-  HandlerWrapper,
-  MicroserviceOptions,
-  ModuleMetadata,
-  Plugin,
-  PluginPriority,
-} from "./types";
-
-// 注意：MODULE_METADATA_KEY 已移除，每个工厂实例使用唯一的 key
-
-/**
- * 微服务引擎实现类
- * @internal 此类型仅供内部使用，用户应通过 Factory.create() 创建引擎实例
- */
-export class Microservice<ModuleOptions = Record<string, any>> {
-  // 存储已注册的模块
-  private modules: ModuleMetadata<ModuleOptions>[] = [];
-  // 存储已注册的插件（按注册顺序）
-  protected plugins: Plugin<Record<string, any>>[] = [];
-  // 插件注册表（以name为键，用于覆盖逻辑）
-  protected pluginRegistry: Map<string, Plugin<Record<string, any>>> =
-    new Map();
-  // 模块实例缓存（单例管理）
-  private moduleInstances: Map<Class, any> = new Map();
-  // 引擎配置（冻结，只读）
-  public readonly options: Readonly<MicroserviceOptions>;
-  // 是否已启动
-  private started: boolean = false;
-  // 模块元数据键（用于通过双向访问查找模块）
-  private readonly moduleMetadataKey: symbol;
-
-  // 实际使用的端口（启动后设置）
-  private actualPort: number | null = null;
-  // Hono 实例（由引擎统一管理）
-  private hono: Hono = new Hono();
-  // HTTP 服务器实例
-  private server: any = null;
-
-  constructor(options: MicroserviceOptions, moduleMetadataKey: symbol) {
-    // 合并默认配置并冻结
-    this.options = Object.freeze({
-      hostname: "0.0.0.0",
-      ...options,
-    });
-    this.moduleMetadataKey = moduleMetadataKey;
-  }
-
-  /**
-   * 获取 Hono 实例（供插件使用）
-   */
-  getHono(): Hono {
-    return this.hono;
-  }
-
-  /**
-   * 内部注册插件方法（供构造函数和子类使用）
-   * @protected
-   */
-  protected registerPlugin<T>(plugin: Plugin<T>): void {
-    // 校验插件名称
-    if (!plugin.name || plugin.name.trim() === "") {
-      throw new PluginNameRequiredError();
-    }
-
-    // 处理插件覆盖逻辑
-    const existingPlugin = this.pluginRegistry.get(plugin.name);
-    if (existingPlugin) {
-      // 移除旧插件
-      const oldIndex = this.plugins.indexOf(existingPlugin);
-      if (oldIndex >= 0) {
-        this.plugins.splice(oldIndex, 1);
-      }
-      logger.info(`Override plugin: ${plugin.name}`);
-    }
-
-    // 注册新插件（使用类型断言，因为运行时兼容）
-    this.pluginRegistry.set(plugin.name, plugin as Plugin<Record<string, any>>);
-    this.plugins.push(plugin as Plugin<Record<string, any>>);
-  }
-
-  /**
-   * 加载并注册所有模块（通过唯一的 key 查找）
-   * 在引擎启动时调用，使用双向访问机制查找所有被装饰的类
-   *
-   * 注意：
-   * - 每个引擎实例使用唯一的 moduleMetadataKey，实现隔离
-   * - 模块类是静态的，可以被多个引擎实例共享
-   * - 每个引擎实例会创建独立的模块实例，互不影响
-   */
-  private loadModules(): void {
-    // 清空已注册的模块（每个引擎实例独立管理）
-    this.modules = [];
-
-    // 通过唯一的 key 获取所有被装饰的类（使用双向访问）
-    const moduleClasses = getClassesByKey(this.moduleMetadataKey);
-
-    for (const moduleClass of moduleClasses) {
-      // 从元数据中获取模块信息
-      const metadata = getClassMetadata(moduleClass, this.moduleMetadataKey);
-      const moduleName = metadata.name || moduleClass.name;
-
-      // 检查模块名是否已注册（在同一引擎实例中，不允许同名模块）
-      // 注意：不同引擎实例可以注册同名模块，因为它们创建的是不同的实例
-      const existingModule = this.modules.find((m) => m.name === moduleName);
-      if (existingModule) {
-        throw new DuplicateModuleError(moduleName);
-      }
-
-      // 注册模块到引擎
-      const moduleMetadata: ModuleMetadata<ModuleOptions> = {
-        name: moduleName,
-        clazz: moduleClass,
-        options: (metadata.options || {}) as ModuleOptions,
-      };
-
-      this.modules.push(moduleMetadata);
-    }
-  }
-
-  /**
-   * 加载Handler元数据（平铺结构）
-   * 每个装饰器都是独立的HandlerMetadata条目
-   * 为每个方法创建包装链管理器，提供简单的 wrap API
-   */
-  private loadHandlerMetadata(): HandlerMetadata[] {
-    const handlers: HandlerMetadata[] = [];
-    // 为每个方法维护包装链（key: moduleName.methodName）
-    const wrapperChains = new Map<string, HandlerWrapper[]>();
-    // 保存原始方法引用（key: moduleName.methodName）
-    const originalMethods = new Map<string, Function>();
-
-    for (const module of this.modules) {
-      // 重要：先实例化模块类，触发装饰器的 addInitializer，收集元数据
-      // 这确保了 Stage 3 装饰器的元数据能够被正确收集
-      if (!this.moduleInstances.has(module.clazz)) {
-        this.get(module.clazz);
-      }
-
-      // 获取模块类的所有Handler元数据
-      const allMetadata = getAllHandlerMetadata(module.clazz);
-
-      for (const [methodName, metadataList] of allMetadata.entries()) {
-        const method = (module.clazz.prototype as any)[methodName];
-        const methodNameStr = String(methodName);
-        const methodKey = `${module.clazz.name}.${methodNameStr}`;
-
-        // 保存原始方法
-        if (!originalMethods.has(methodKey)) {
-          originalMethods.set(methodKey, method);
-          wrapperChains.set(methodKey, []);
-        }
-
-        // 将每个装饰器元数据转换为独立的HandlerMetadata条目
-        for (const meta of metadataList) {
-          const chain = wrapperChains.get(methodKey)!;
-
-          handlers.push({
-            ...meta,
-            method: originalMethods.get(methodKey)!,
-            methodName: methodNameStr,
-            module: module.clazz,
-            // 提供简单的 wrap API：插件只需要调用这个方法
-            wrap: (wrapper: HandlerWrapper) => {
-              chain.push(wrapper);
-            },
-          });
-        }
-      }
-    }
-
-    // 保存包装链和原始方法，供 applyWrapperChains 使用
-    (this as any).__wrapperChains__ = wrapperChains;
-    (this as any).__originalMethods__ = originalMethods;
-
-    return handlers;
-  }
-
-  /**
-   * 应用所有包装链到原型
-   * 在所有插件执行完 onHandlerLoad 后调用
-   */
-  private applyWrapperChains(): void {
-    const wrapperChains = (this as any).__wrapperChains__ as Map<
-      string,
-      HandlerWrapper[]
-    >;
-    const originalMethods = (this as any).__originalMethods__ as Map<
-      string,
-      Function
-    >;
-
-    if (!wrapperChains || !originalMethods) return;
-
-    // 为每个方法应用包装链
-    for (const [methodKey, chain] of wrapperChains.entries()) {
-      if (chain.length === 0) continue;
-
-      // 解析方法键
-      const [moduleName, methodName] = methodKey.split(".");
-      const module = this.modules.find((m) => m.clazz.name === moduleName);
-      if (!module) continue;
-
-      const originalMethod = originalMethods.get(methodKey)!;
-      const prototype = module.clazz.prototype;
-
-      // 从后往前构建包装链（最后一个包装器在最外层）
-      let wrappedMethod = originalMethod;
-
-      for (let i = chain.length - 1; i >= 0; i--) {
-        const wrapper = chain[i];
-        const next = wrappedMethod;
-
-        wrappedMethod = async function (this: any, ...args: any[]) {
-          return wrapper(() => next.apply(this, args), this, ...args);
-        } as Function;
-      }
-
-      // 更新原型
-      prototype[methodName] = wrappedMethod;
-    }
-  }
-
-  /**
-   * 检查端口是否可用
-   */
-  private async isPortAvailable(
-    port: number,
-    hostname: string
-  ): Promise<boolean> {
-    return new Promise((resolve) => {
-      const server = net.createServer();
-      server.unref();
-      server.listen(port, hostname, () => {
-        server.once("close", () => resolve(true));
-        server.close();
-      });
-      server.on("error", () => resolve(false));
-    });
-  }
-
-  /**
-   * 寻找一个随机的可用端口
-   */
-  private getRandomPort(hostname: string): Promise<number> {
-    return new Promise((resolve, reject) => {
-      const server = net.createServer();
-      server.unref(); // 防止 server.listen 保持进程活动
-      server.on("error", reject);
-      server.listen(0, hostname, () => {
-        const port = (server.address() as net.AddressInfo).port;
-        server.close((err) => {
-          if (err) {
-            return reject(err);
-          }
-          resolve(port);
-        });
-      });
-    });
-  }
-
-  /**
-   * 启动引擎
-   * @param requestedPort 启动端口（可选，默认0，表示随机端口）
-   * @returns 实际使用的端口号
-   */
-  async start(requestedPort: number = 0): Promise<number> {
-    if (this.started) {
-      throw new Error("Engine is already started");
-    }
-
-    try {
-      // 1. 确定实际使用的端口
-      const { port, hostname } = await this.determinePort(requestedPort);
-
-      // 2. 初始化模块和插件
-      this.initializeModulesAndPlugins();
-
-      // 3. 处理 Handler 元数据和插件包装
-      this.processHandlers();
-
-      // 4. 执行插件启动钩子
-      await this.executePluginStartHooks();
-
-      // 5. 启动 HTTP 服务器
-      this.startHttpServer(port, hostname);
-
-      // 6. 标记为已启动
-      this.started = true;
-      logger.info(
-        `${this.options.name} v${this.options.version} started successfully on port ${this.actualPort}`
-      );
-
-      return this.actualPort!;
-    } catch (error) {
-      logger.error("Failed to start engine", error);
-      throw error;
-    }
-  }
-
-  /**
-   * 确定实际使用的端口
-   */
-  private async determinePort(
-    requestedPort: number
-  ): Promise<{ port: number; hostname: string }> {
-    const hostname = this.options.hostname || "0.0.0.0";
-
-    if (requestedPort !== 0) {
-      const portAvailable = await this.isPortAvailable(requestedPort, hostname);
-      if (portAvailable) {
-        this.actualPort = requestedPort;
-        return { port: this.actualPort, hostname };
-      }
-      logger.info(
-        `Port ${requestedPort} is in use, finding a random available port...`
-      );
-    }
-
-    this.actualPort = await this.getRandomPort(hostname);
-    return { port: this.actualPort!, hostname };
-  }
-
-  /**
-   * 初始化模块和插件
-   */
-  private initializeModulesAndPlugins(): void {
-    // 加载并注册所有模块（从全局注册表扫描）
-    this.loadModules();
-
-    // 执行插件 onInit
-    this.executePluginHook("onInit", (plugin) => {
-      plugin.onInit?.(this as Microservice<Record<string, any>>);
-    });
-
-    // 执行插件 onModuleLoad
-    this.executePluginHook("onModuleLoad", (plugin) => {
-      plugin.onModuleLoad?.(
-        this.modules as ModuleMetadata<Record<string, any>>[]
-      );
-    });
-  }
-
-  /**
-   * 处理 Handler 元数据和插件包装
-   */
-  private processHandlers(): void {
-    // 加载 Handler 元数据（平铺结构，包含 wrap API）
-    const handlers = this.loadHandlerMetadata();
-
-    // 按优先级排序插件
-    const sortedPlugins = this.sortPluginsByPriority();
-
-    // 分离包装插件和路由插件
-    const { wrapperPlugins, routePlugins } =
-      this.separateWrapperAndRoutePlugins(sortedPlugins);
-
-    // 先执行包装插件（按优先级排序），它们可以调用 handler.wrap()
-    this.executePluginHook(
-      "onHandlerLoad",
-      (plugin) => {
-        plugin.onHandlerLoad?.(handlers);
-      },
-      wrapperPlugins
-    );
-
-    // 应用所有包装链到原型（在所有包装插件执行完后，RoutePlugin 执行前）
-    this.applyWrapperChains();
-
-    // 最后执行路由插件（按优先级排序，确保调用的是已被包装后的方法）
-    this.executePluginHook(
-      "onHandlerLoad",
-      (plugin) => {
-        plugin.onHandlerLoad?.(handlers);
-      },
-      routePlugins
-    );
-  }
-
-  /**
-   * 执行插件启动钩子
-   */
-  private async executePluginStartHooks(): Promise<void> {
-    // 执行插件 onBeforeStart
-    this.executePluginHook("onBeforeStart", (plugin) => {
-      plugin.onBeforeStart?.(this as Microservice<Record<string, any>>);
-    });
-
-    // 执行插件 onAfterStart（支持异步）
-    for (const plugin of this.plugins) {
-      try {
-        await plugin.onAfterStart?.(this as Microservice<Record<string, any>>);
-      } catch (error) {
-        throw new Error(
-          `Plugin ${plugin.name} failed in onAfterStart: ${
-            error instanceof Error ? error.message : String(error)
-          }`
-        );
-      }
-    }
-
-    // 在所有插件完成后，注册版本路由
-    this.registerVersionRoute();
-  }
-
-  /**
-   * 注册版本路由（/prefix/version）
-   * 用于健康检查和探针
-   */
-  private registerVersionRoute(): void {
-    const prefix = this.options.prefix || "";
-    const versionPath = prefix ? `${prefix}` : "/";
-
-    // 检查路由是否已存在
-    // 使用 hono.routes 来检查已注册的路由
-    const existingRoutes = this.hono.routes;
-    const routeExists = existingRoutes.some(
-      (route) => route.path === versionPath && route.method === "GET"
-    );
-
-    if (routeExists) {
-      logger.info(
-        `Version route ${versionPath} already exists, skipping registration`
-      );
-      return;
-    }
-
-    // 注册版本路由
-    try {
-      this.hono.get(versionPath, async (ctx) => {
-        return ctx.json({
-          name: this.options.name,
-          version: this.options.version,
-          status: "running",
-        });
-      });
-
-      logger.info(`Registered version route: GET ${versionPath}`);
-    } catch (error) {
-      // 如果注册失败（可能是因为路由匹配器已经构建），记录日志
-      if (
-        error instanceof Error &&
-        error.message.includes("matcher is already built")
-      ) {
-        logger.warn(
-          `Cannot register version route ${versionPath}: route matcher is already built. ` +
-            `If you have already registered a route at ${versionPath}, it will be used instead.`
-        );
-      } else {
-        throw error;
-      }
-    }
-  }
-
-  /**
-   * 启动 HTTP 服务器
-   */
-  private startHttpServer(port: number, hostname: string): void {
-    // serve() 如果启动失败会抛出错误，成功则服务器立即可以接受连接
-    this.server = serve({
-      fetch: this.hono.fetch,
-      port,
-      hostname,
-    });
-
-    logger.info(`HTTP server started on http://${hostname}:${port}`);
-  }
-
-  /**
-   * 按优先级排序插件
-   */
-  private sortPluginsByPriority(): Plugin[] {
-    return [...this.plugins].sort((a, b) => {
-      const priorityA = this.getPluginPriority(a);
-      const priorityB = this.getPluginPriority(b);
-
-      // 按优先级排序（数值越小，优先级越高）
-      if (priorityA !== priorityB) {
-        return priorityA - priorityB;
-      }
-
-      // 相同优先级按注册顺序（保持稳定排序）
-      const indexA = this.plugins.indexOf(a);
-      const indexB = this.plugins.indexOf(b);
-      return indexA - indexB;
-    });
-  }
-
-  /**
-   * 获取插件优先级
-   */
-  private getPluginPriority(plugin: Plugin): number {
-    return plugin.priority ?? PluginPriority.BUSINESS;
-  }
-
-  /**
-   * 分离包装插件和路由插件
-   */
-  private separateWrapperAndRoutePlugins(sortedPlugins: Plugin[]): {
-    wrapperPlugins: Plugin[];
-    routePlugins: Plugin[];
-  } {
-    const wrapperPlugins: Plugin[] = [];
-    const routePlugins: Plugin[] = [];
-
-    for (const plugin of sortedPlugins) {
-      const priority = this.getPluginPriority(plugin);
-      if (priority === PluginPriority.ROUTE) {
-        routePlugins.push(plugin);
-      } else {
-        wrapperPlugins.push(plugin);
-      }
-    }
-
-    return { wrapperPlugins, routePlugins };
-  }
-
-  /**
-   * 执行插件钩子（通用方法）
-   */
-  private executePluginHook(
-    hookName: string,
-    callback: (plugin: Plugin) => void,
-    plugins: Plugin[] = this.plugins
-  ): void {
-    for (const plugin of plugins) {
-      try {
-        callback(plugin);
-      } catch (error) {
-        throw new Error(
-          `Plugin ${plugin.name} failed in ${hookName}: ${
-            error instanceof Error ? error.message : String(error)
-          }`
-        );
-      }
-    }
-  }
-
-  /**
-   * 停止引擎
-   */
-  async stop(): Promise<void> {
-    if (!this.started) {
-      return;
-    }
-
-    try {
-      // 关闭 HTTP 服务器
-      if (this.server) {
-        // serve() 返回的对象可能不是标准的 Node.js Server
-        // 检查是否有 close 方法，如果有则调用
-        if (typeof this.server.close === "function") {
-          // 尝试使用回调方式关闭（标准 Node.js Server）
-          if (this.server.close.length > 0) {
-            await new Promise<void>((resolve, reject) => {
-              this.server.close((err: any) => {
-                if (err) {
-                  reject(err);
-                } else {
-                  resolve();
-                }
-              });
-            });
-          } else {
-            // 如果没有回调参数，直接调用
-            this.server.close();
-            // 给一点时间让服务器完全关闭
-            await new Promise((resolve) => setTimeout(resolve, 10));
-          }
-        }
-        this.server = null;
-        logger.info("HTTP server stopped");
-      }
-
-      // 执行插件onDestroy（逆序）
-      for (let i = this.plugins.length - 1; i >= 0; i--) {
-        const plugin = this.plugins[i];
-        try {
-          await plugin.onDestroy?.();
-        } catch (error) {
-          logger.error(`Plugin ${plugin.name} failed in onDestroy`, error);
-        }
-      }
-
-      // 清理资源
-      this.modules = [];
-      this.moduleInstances.clear();
-      this.started = false;
-      this.actualPort = null;
-
-      logger.info(`${this.options.name} stopped`);
-    } catch (error) {
-      logger.error("Failed to stop engine", error);
-      throw error;
-    }
-  }
-
-  /**
-   * 获取模块实例（单例）
-   * @param moduleClass 模块类
-   * @returns 模块实例
-   */
-  get<T extends Class>(moduleClass: T): InstanceType<T> {
-    if (!this.moduleInstances.has(moduleClass)) {
-      this.moduleInstances.set(moduleClass, new moduleClass());
-    }
-    return this.moduleInstances.get(moduleClass) as InstanceType<T>;
-  }
-
-  /**
-   * 获取已注册的模块列表
-   */
-  getModules(): ModuleMetadata<Record<string, any>>[] {
-    // 如果模块尚未加载，先加载模块
-    if (this.modules.length === 0 && !this.started) {
-      this.loadModules();
-    }
-    return [...this.modules] as ModuleMetadata<Record<string, any>>[];
-  }
-
-  /**
-   * 获取实际使用的端口
-   */
-  getPort(): number | null {
-    return this.actualPort;
-  }
-}

package/src/core/errors.ts

@@ -1,28 +0,0 @@
-/**
- * 核心异常类型定义
- */
-
-export class PluginNameRequiredError extends Error {
-  constructor(pluginName?: string) {
-    super(
-      `Plugin name is required${pluginName ? ` (plugin: ${pluginName})` : ""}`
-    );
-    this.name = "PluginNameRequiredError";
-  }
-}
-
-export class ModuleConfigValidationError extends Error {
-  constructor(moduleName: string, pluginName: string, message: string) {
-    super(
-      `[ModuleConfigError] Module ${moduleName} (plugin ${pluginName}): ${message}`
-    );
-    this.name = "ModuleConfigValidationError";
-  }
-}
-
-export class DuplicateModuleError extends Error {
-  constructor(moduleName: string) {
-    super(`Module ${moduleName} is already registered`);
-    this.name = "DuplicateModuleError";
-  }
-}