imean-service-engine 2.0.0 → 2.0.2

package/src/core/factory.test.ts

@@ -1,73 +0,0 @@
-import { beforeEach, describe, expect, it } from "vitest";
-import { CachePlugin } from "../plugins/cache";
-import { RoutePlugin } from "../plugins/route";
-import { Factory } from "./factory";
-
-describe("Factory", () => {
-  beforeEach(() => {
-    // 每个测试都会创建新的 Factory，使用不同的 key，自动隔离
-    // 不需要手动清空注册表
-  });
-  describe("create", () => {
-    it("应该创建类型化的 Module 装饰器和 Microservice 类", () => {
-      const { Module, Microservice } = Factory.create(new CachePlugin());
-
-      expect(Module).toBeDefined();
-      expect(typeof Module).toBe("function");
-      expect(Microservice).toBeDefined();
-      expect(typeof Microservice).toBe("function");
-    });
-
-    it("应该创建引擎实例并注册插件", () => {
-      const { Microservice } = Factory.create(new CachePlugin());
-
-      const engine = new Microservice({
-        name: "test-service",
-        version: "1.0.0",
-      });
-
-      expect(engine).toBeDefined();
-      expect(engine.getModules).toBeDefined();
-      expect(engine.start).toBeDefined();
-    });
-
-    it("应该在构造函数中正确注册所有插件", () => {
-      const cachePlugin = new CachePlugin();
-      const routePlugin = new RoutePlugin();
-
-      const { Microservice } = Factory.create(cachePlugin, routePlugin);
-
-      const engine = new Microservice({
-        name: "test-service",
-        version: "1.0.0",
-      });
-
-      // 验证插件已注册（通过检查模块配置类型）
-      const modules = engine.getModules();
-      expect(modules).toBeDefined();
-    });
-
-    it("应该只包含显式注册的插件", () => {
-      const { Module, Microservice } = Factory.create(
-        new CachePlugin(),
-        new RoutePlugin()
-      );
-
-      // 先创建引擎实例
-      const engine = new Microservice({
-        name: "test-service",
-        version: "1.0.0",
-      });
-
-      // 然后使用装饰器
-      @Module("test-module", {
-        routePrefix: "/api",
-        cacheDefaultTtl: 5000,
-      })
-      class TestService {}
-
-      expect(TestService).toBeDefined();
-      expect(engine.getModules()).toHaveLength(1);
-    });
-  });
-});

package/src/core/factory.ts

@@ -1,92 +0,0 @@
-import { createClassDecorator } from "../metadata/metadata";
-import { Microservice } from "./engine";
-import { MicroserviceOptions, ModuleDecorator, Plugin } from "./types";
-
-/**
- * 从插件数组中提取聚合的配置类型
- */
-type ExtractPluginOptions<T extends readonly Plugin<any>[]> =
-  T extends readonly [infer P1, ...infer Rest]
-    ? P1 extends Plugin<infer T1>
-      ? Rest extends readonly Plugin<any>[]
-        ? T1 & ExtractPluginOptions<Rest>
-        : T1
-      : ExtractPluginOptions<Rest extends readonly Plugin<any>[] ? Rest : []>
-    : Record<string, any>;
-
-/**
- * 从 Factory.create 返回值中提取 Microservice 实例类型
- */
-export type FactoryMicroservice<T extends ReturnType<typeof Factory.create>> =
-  T["Microservice"] extends new (options: any) => infer Instance
-    ? Instance
-    : never;
-
-/**
- * 从 Factory.create 返回值中提取 Module 装饰器类型
- */
-export type FactoryModule<T extends ReturnType<typeof Factory.create>> =
-  T["Module"];
-
-/**
- * Factory - 创建类型化的引擎实例
- * 
- * 注意：所有插件都必须显式注册，不会自动包含任何默认插件
- */
-export class Factory {
-  /**
-   * 创建类型化的引擎工厂
-   *
-   * @param plugins 插件列表（必须显式提供所有需要的插件）
-   * @returns 包含类型化的 Module 装饰器和 Microservice 类的对象
-   */
-  static create<TPlugins extends readonly Plugin<any>[]>(
-    ...plugins: TPlugins
-  ): {
-    Module: ModuleDecorator<ExtractPluginOptions<TPlugins>>;
-    Microservice: new (options: MicroserviceOptions) => Microservice<
-      ExtractPluginOptions<TPlugins>
-    >;
-  } {
-    type TAggregatedOptions = ExtractPluginOptions<TPlugins>;
-
-    // 为每个工厂创建过程生成唯一的 key
-    // 使用 Symbol 和时间戳确保唯一性
-    const moduleMetadataKey = Symbol.for(
-      `imean:moduleMetadata:${Date.now()}:${Math.random()}`
-    );
-
-    // 创建一个类型化的 Microservice 类
-    class TypedMicroservice extends Microservice<TAggregatedOptions> {
-      constructor(options: MicroserviceOptions) {
-        // 传递唯一的 key 给父类，用于模块发现
-        super(options, moduleMetadataKey);
-        // 注册所有插件（在父类构造函数之后，直接访问 protected 成员）
-        for (const plugin of plugins) {
-          this.registerPlugin(plugin);
-        }
-      }
-    }
-
-    // 创建类型化的 Module 装饰器
-    // 使用唯一的 key，这样不同工厂创建的装饰器会使用不同的 key
-    const baseDecorator = createClassDecorator(moduleMetadataKey);
-
-    const Module: ModuleDecorator<TAggregatedOptions> = (
-      name: string,
-      options?: TAggregatedOptions
-    ) => {
-      // 创建类级别的元数据（每个类独有的）
-      const classMetadata = {
-        name: name || undefined,
-        options: (options || {}) as TAggregatedOptions,
-      };
-      return baseDecorator(classMetadata) as any;
-    };
-
-    return {
-      Module,
-      Microservice: TypedMicroservice,
-    };
-  }
-}

package/src/core/logger.ts

@@ -1,65 +0,0 @@
-import winston, { format } from "winston";
-
-let TestHook: ((msg: string) => void) | null = null;
-
-export function setTestHook(hook: (msg: string) => void) {
-  TestHook = hook;
-}
-
-// 自定义日志格式，使输出更美观
-const customFormat = format.printf((info) => {
-  const { level, timestamp, message, ...meta } = info;
-  const splat = info[Symbol.for("splat")] as any[] | undefined;
-  
-  // 构建基础消息
-  let msg = `${timestamp} [${level}] ${message}`;
-  
-  // 添加额外的元数据
-  if (splat && Array.isArray(splat) && splat.length > 0) {
-    const metaStr = splat
-      .map((item: any) => {
-        if (item instanceof Error) {
-          return item.stack || item.message;
-        }
-        if (typeof item === "object") {
-          return JSON.stringify(item, null, 2);
-        }
-        return String(item);
-      })
-      .join("\n");
-    msg += `\n${metaStr}`;
-  }
-  
-  // 添加其他元数据
-  const metaKeys = Object.keys(meta).filter(
-    (key) => key !== Symbol.for("splat").toString()
-  );
-  if (metaKeys.length > 0) {
-    const metaObj: Record<string, any> = {};
-    for (const key of metaKeys) {
-      metaObj[key] = meta[key];
-    }
-    msg += `\n${JSON.stringify(metaObj, null, 2)}`;
-  }
-  
-  if (TestHook) {
-    TestHook(msg);
-  }
-  
-  return msg;
-});
-
-const logger = winston.createLogger({
-  level: process.env.LOG_LEVEL || "info",
-  transports: [
-    new winston.transports.Console({
-      format: format.combine(
-        format.colorize({ all: true }),
-        format.timestamp({ format: "YYYY-MM-DD HH:mm:ss.SSS" }),
-        customFormat
-      ),
-    }),
-  ],
-});
-
-export default logger;

package/src/core/testing.ts

@@ -1,73 +0,0 @@
-/**
- * 测试辅助模块
- * 提供常用的测试工具函数和类型，简化测试代码编写
- */
-
-import { Factory } from "./factory";
-import { MicroserviceOptions, Plugin } from "./types";
-
-/**
- * 默认测试配置
- */
-export const DEFAULT_TEST_OPTIONS = {
-  name: "test-service",
-  version: "1.0.0",
-} as const;
-
-/**
- * 创建测试引擎
- *
- * @example
- * ```ts
- * // 只传插件
- * const { engine, Module } = Testing.createTestEngine({
- *   plugins: [new CachePlugin()]
- * });
- *
- * // 传插件和 options
- * const { engine, Module } = Testing.createTestEngine({
- *   plugins: [new CachePlugin()],
- *   options: { prefix: "/api" }
- * });
- * ```
- */
-function createTestEngine<TPlugins extends readonly Plugin<any>[]>(config: {
-  plugins: TPlugins;
-  options?: Partial<MicroserviceOptions>;
-}): ReturnType<typeof Factory.create<TPlugins>> & {
-  engine: InstanceType<
-    ReturnType<typeof Factory.create<TPlugins>>["Microservice"]
-  >;
-} {
-  const factory = Factory.create(...config.plugins);
-  const Microservice = factory.Microservice;
-  const engine = new Microservice({
-    ...DEFAULT_TEST_OPTIONS,
-    ...config.options,
-  });
-
-  return {
-    ...factory,
-    engine,
-  };
-}
-
-/**
- * 等待指定时间（用于异步测试）
- *
- * @param ms 等待的毫秒数
- * @returns Promise
- */
-function wait(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * 测试辅助工具命名空间
- * 所有测试相关的工具函数都通过这个命名空间导出，避免命名冲突
- */
-export const Testing = {
-  createTestEngine,
-  DEFAULT_TEST_OPTIONS,
-  wait,
-} as const;

package/src/core/types.ts

@@ -1,191 +0,0 @@
-/**
- * 核心类型定义
- */
-
-import { Microservice } from "./engine";
-
-// 模块类类型
-export type Class = new (...args: any[]) => any;
-
-/**
- * 插件Module配置Schema（运行时+类型双维度）
- */
-export interface PluginModuleOptionsSchema<T = Record<string, any>> {
-  // 类型标记：仅用于TypeScript推导，运行时无值
-  _type: T;
-  // 运行时校验规则（可选）
-  validate?: (options: T) => boolean | string;
-}
-
-/**
- * 插件优先级
- * 数值越小，优先级越高（越先执行）
- * 引擎会自动按优先级排序，用户无需关心注册顺序
- */
-export enum PluginPriority {
-  /**
-   * 系统级优先级：系统核心功能插件（优雅停机等）
-   * 最高优先级，应该最先执行
-   */
-  SYSTEM = 50,
-
-  /**
-   * 最高优先级：安全相关插件（限流、认证等）
-   * 应该最先执行，快速拒绝无效请求
-   */
-  SECURITY = 100,
-
-  /**
-   * 高优先级：日志、监控等插件
-   * 记录所有请求，包括被安全插件拒绝的
-   */
-  LOGGING = 200,
-
-  /**
-   * 中优先级：业务逻辑插件（数据转换等）
-   * 在安全和日志之后执行
-   */
-  BUSINESS = 300,
-
-  /**
-   * 低优先级：性能优化插件（缓存等）
-   * 在业务逻辑之后执行，避免重复计算
-   */
-  PERFORMANCE = 400,
-
-  /**
-   * 最低优先级：路由插件
-   * 必须最后执行，注册HTTP路由
-   */
-  ROUTE = 1000,
-}
-
-/**
- * 核心插件接口
- */
-export interface Plugin<TModuleOptions = Record<string, any>> {
-  // 插件唯一名称
-  name: string;
-
-  /**
-   * 插件优先级（可选）
-   * 如果不指定，默认为 PluginPriority.BUSINESS
-   * 引擎会自动按优先级排序，用户无需关心注册顺序
-   *
-   * 优先级规则：
-   * - 数值越小，优先级越高（越先执行）
-   * - 相同优先级按注册顺序执行
-   */
-  priority?: PluginPriority | number;
-
-  // 声明插件的Module配置Schema（核心：用于类型推导+运行时校验）
-  getModuleOptionsSchema?: () => PluginModuleOptionsSchema<TModuleOptions>;
-  // 生命周期钩子
-  onInit?: (engine: Microservice) => void;
-  onModuleLoad?: (modules: ModuleMetadata[]) => void;
-  // Handler加载钩子：平铺的HandlerMetadata数组，每个装饰器都是独立条目
-  // 引擎会自动按优先级排序，用户无需关心注册顺序
-  onHandlerLoad?: (handlers: HandlerMetadata[]) => void;
-  onBeforeStart?: (engine: Microservice) => void;
-  onAfterStart?: (engine: Microservice) => void | Promise<void>;
-  onDestroy?: () => void | Promise<void>;
-}
-
-/**
- * 引擎创建选项
- */
-export interface MicroserviceOptions {
-  name: string; // 服务名称
-  version: string; // 语义化版本
-  hostname?: string; // 绑定主机名（默认0.0.0.0）
-  prefix?: string; // 路由前缀（默认""，用于Action插件的路由注册）
-}
-
-/**
- * Module装饰器类型（由引擎实例创建，自动推导类型）
- * 使用最新的 Stage 3 装饰器标准
- */
-export type ModuleDecorator<TOptions = Record<string, any>> = (
-  name: string,
-  options?: TOptions
-) => (target: Class, context: ClassDecoratorContext) => void;
-
-/**
- * 模块元数据
- */
-export interface ModuleMetadata<TOptions = Record<string, any>> {
-  name: string;
-  clazz: Class;
-  options: TOptions;
-}
-
-/**
- * Handler包装函数类型
- * 插件只需要提供这个函数，引擎自动管理包装链
- *
- * @param next 调用下一个包装层或原始方法
- * @param instance 模块实例
- * @param args 方法参数
- * @returns 方法执行结果
- */
-export type HandlerWrapper = (
-  next: () => Promise<any> | any,
-  instance: any,
-  ...args: any[]
-) => Promise<any> | any;
-
-/**
- * Handler元数据（单组元数据）
- * 提供简单的 wrap API，引擎自动管理包装链和执行顺序
- */
-export interface HandlerMetadata {
-  type: string; // 元数据类型（如route/cache/rate-limit）
-  options: Record<string, any>; // 该类型对应的自定义配置
-  method: Function; // 关联的模块方法（原始方法，仅供内部使用）
-  methodName: string; // 方法名称
-  module: Class; // 所属模块类
-
-  /**
-   * 包装当前方法（引擎自动管理包装链）
-   *
-   * 插件只需要调用这个方法，引擎会自动：
-   * - 按插件优先级构建包装链
-   * - 确保 RoutePlugin 最后执行
-   * - 自动应用包装到原型
-   *
-   * @param wrapper 包装函数
-   *   - next: 调用下一个包装层或原始方法
-   *   - instance: 模块实例
-   *   - args: 方法参数
-   *
-   * @example
-   * ```typescript
-   * handler.wrap(async (next, instance, ...args) => {
-   *   // 前置逻辑
-   *   const result = await next();
-   *   // 后置逻辑
-   *   return result;
-   * });
-   * ```
-   */
-  wrap(wrapper: HandlerWrapper): void;
-}
-
-/**
- * Stage 3 装饰器上下文类型
- */
-export type ClassDecoratorContext = {
-  kind: "class";
-  name: string | undefined;
-  addInitializer(initializer: () => void): void;
-};
-
-export type ClassMethodDecoratorContext = {
-  kind: "method";
-  name: string | symbol;
-  static: boolean;
-  private: boolean;
-  addInitializer(initializer: () => void): void;
-};
-export { Microservice };
-

package/src/index.ts

@@ -1,49 +0,0 @@
-/**
- * IMean Service Engine - 微服务引擎框架
- */
-
-// 核心类型
-export * from "./core/types";
-
-// 导出插件优先级枚举，方便插件开发者使用
-export { PluginPriority } from "./core/types";
-
-// 装饰器
-export { Handler } from "./core/decorators";
-
-// 异常
-export * from "./core/errors";
-
-// 预检
-export * from "./core/checker";
-
-// Route插件
-export * from "./plugins/route";
-
-// Action插件
-export * from "./plugins/action";
-
-// Cache插件
-export * from "./plugins/cache";
-
-// GracefulShutdown插件
-export * from "./plugins/graceful-shutdown";
-
-// Schedule插件
-export * from "./plugins/schedule";
-
-// clientCode插件
-export * from "./plugins/client-code";
-
-// 便捷导出：引擎创建函数（仅通过 Factory 创建）
-export { Factory } from "./core/factory";
-export type { MicroserviceOptions } from "./core/types";
-
-// 测试辅助工具（仅在测试环境中使用）
-export * from "./core/testing";
-
-// 导出 zod（固定版本，用户可以直接从主包导入）
-export { z } from "zod";
-
-// 导出 hono
-export { Context, MiddlewareHandler } from "hono";