imean-service-engine 2.0.0 → 2.0.2

package/src/plugins/rate-limit/rate-limit-plugin.example.ts

@@ -1,171 +0,0 @@
-/**
- * RateLimitPlugin 示例实现
- * 演示如何与 CachePlugin 配合工作
- */
-
-import {
-  HandlerMetadata,
-  Microservice,
-  Plugin,
-  PluginModuleOptionsSchema,
-} from "../../core/types";
-
-export interface RateLimitOptions {
-  maxRequests?: number; // 最大请求数
-  windowMs?: number; // 时间窗口（毫秒）
-  keyGenerator?: (methodName: string, ...args: any[]) => string; // 限流键生成器
-}
-
-export interface RateLimitModuleOptions {
-  rateLimitMaxRequests?: number; // 模块级默认最大请求数
-  rateLimitWindowMs?: number; // 模块级默认时间窗口
-}
-
-/**
- * RateLimitPlugin - 限流插件
- *
- * 执行顺序说明：
- * - 如果 RateLimitPlugin 在 CachePlugin 之前注册，限流在外层，缓存在内层
- *   请求流程：限流检查 → 缓存检查 → 业务逻辑
- * - 如果 RateLimitPlugin 在 CachePlugin 之后注册，缓存在外层，限流在内层
- *   请求流程：缓存检查 → 限流检查 → 业务逻辑
- *
- * 推荐顺序：RateLimitPlugin → CachePlugin
- * 这样可以避免缓存命中时仍然进行限流检查
- */
-export class RateLimitPlugin implements Plugin<RateLimitModuleOptions> {
-  public readonly name = "rate-limit-plugin";
-  private requestCounts: Map<string, { count: number; resetAt: number }> =
-    new Map();
-  private defaultMaxRequests: number = 100;
-  private defaultWindowMs: number = 60000; // 1分钟
-  private engine: Microservice | null = null;
-
-  getModuleOptionsSchema(): PluginModuleOptionsSchema<RateLimitModuleOptions> {
-    return {
-      _type: {} as RateLimitModuleOptions,
-      validate: (options) => {
-        if (
-          options.rateLimitMaxRequests !== undefined &&
-          options.rateLimitMaxRequests <= 0
-        ) {
-          return `rateLimitMaxRequests must be greater than 0`;
-        }
-        if (
-          options.rateLimitWindowMs !== undefined &&
-          options.rateLimitWindowMs <= 0
-        ) {
-          return `rateLimitWindowMs must be greater than 0`;
-        }
-        return true;
-      },
-    };
-  }
-
-  onInit(engine: Microservice): void {
-    this.engine = engine;
-    console.log("[RateLimitPlugin] Initialized rate limit storage");
-  }
-
-  onHandlerLoad(handlers: HandlerMetadata[]): void {
-    // 筛选出所有 type="rate-limit" 的 Handler 元数据
-    const rateLimitHandlers = handlers.filter(
-      (handler) => handler.type === "rate-limit"
-    );
-
-    console.log(
-      `[RateLimitPlugin] Found ${rateLimitHandlers.length} rate limit handlers`
-    );
-
-    // 遍历限流 Handler，包装方法
-    // 注意：使用原型上的当前方法（可能已被其他插件包装），而不是 handler.method
-    for (const handler of rateLimitHandlers) {
-      const methodName = handler.methodName;
-      const moduleClass = handler.module;
-      const rateLimitOptions = handler.options as RateLimitOptions;
-
-      // 获取模块元数据以读取配置
-      const moduleMetadata = this.engine
-        ?.getModules()
-        .find((m) => m.clazz === moduleClass);
-
-      if (!moduleMetadata) {
-        console.warn(
-          `[RateLimitPlugin] Module metadata not found for ${moduleClass.name}`
-        );
-        continue;
-      }
-
-      // 获取模块配置
-      const moduleOptions = moduleMetadata.options as RateLimitModuleOptions;
-      const maxRequests =
-        rateLimitOptions.maxRequests ??
-        moduleOptions?.rateLimitMaxRequests ??
-        this.defaultMaxRequests;
-      const windowMs =
-        rateLimitOptions.windowMs ??
-        moduleOptions?.rateLimitWindowMs ??
-        this.defaultWindowMs;
-
-      // 生成限流键的函数
-      const keyGenerator =
-        rateLimitOptions.keyGenerator ||
-        ((methodName: string, ...args: any[]) =>
-          `${methodName}:${JSON.stringify(args)}`);
-
-      // 获取当前原型上的方法（可能已被其他插件包装）
-      const prototype = moduleClass.prototype;
-      const currentMethod = prototype[methodName];
-
-      // 包装当前方法（支持插件链式包装）
-      const rateLimitedMethod = async (...args: any[]) => {
-        // 生成限流键
-        const limitKey = keyGenerator(methodName, ...args);
-        const now = Date.now();
-
-        // 获取或初始化计数器
-        let counter = this.requestCounts.get(limitKey);
-        if (!counter || counter.resetAt <= now) {
-          counter = { count: 0, resetAt: now + windowMs };
-          this.requestCounts.set(limitKey, counter);
-        }
-
-        // 检查限流
-        if (counter.count >= maxRequests) {
-          console.log(
-            `[RateLimitPlugin] Rate limit exceeded for ${limitKey} (${counter.count}/${maxRequests})`
-          );
-          throw new Error(
-            `Rate limit exceeded: ${counter.count} requests in ${windowMs}ms`
-          );
-        }
-
-        // 增加计数
-        counter.count++;
-        console.log(
-          `[RateLimitPlugin] Request allowed for ${limitKey} (${counter.count}/${maxRequests})`
-        );
-
-        // 执行当前方法（可能是原始方法，也可能是被其他插件包装后的）
-        const result = await currentMethod.apply(
-          this.engine?.get(moduleClass),
-          args
-        );
-
-        return result;
-      };
-
-      // 替换原型上的方法
-      prototype[methodName] = rateLimitedMethod;
-
-      console.log(
-        `[RateLimitPlugin] Wrapped ${moduleClass.name}.${methodName} with rate limit (${maxRequests} requests per ${windowMs}ms)`
-      );
-    }
-  }
-
-  onDestroy(): void {
-    this.requestCounts.clear();
-    console.log("[RateLimitPlugin] Rate limit storage destroyed");
-  }
-}

package/src/plugins/route/components/Layout.tsx

@@ -1,42 +0,0 @@
-import { html } from "hono/html";
-
-const DEFAULT_FAVICON = (
-  <link
-    rel="icon"
-    href="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100' width='100' height='100'><defs><linearGradient id='nodeGradient' x1='0%' y1='0%' x2='100%' y2='100%'><stop offset='0%' stop-color='%233498db'/><stop offset='100%' stop-color='%232980b9'/></linearGradient><linearGradient id='centerNodeGradient' x1='0%' y1='0%' x2='100%' y2='100%'><stop offset='0%' stop-color='%232ecc71'/><stop offset='100%' stop-color='%2327ae60'/></linearGradient></defs><circle cx='50' cy='50' r='45' fill='%23f5f7fa'/><path d='M30,30 L50,50' stroke='%23bdc3c7' stroke-width='2' stroke-linecap='round'/><path d='M70,30 L50,50' stroke='%23bdc3c7' stroke-width='2' stroke-linecap='round'/><path d='M30,70 L50,50' stroke='%23bdc3c7' stroke-width='2' stroke-linecap='round'/><path d='M70,70 L50,50' stroke='%23bdc3c7' stroke-width='2' stroke-linecap='round'/><polygon points='30,15 45,25 45,45 30,55 15,45 15,25' fill='url(%23nodeGradient)' stroke='%232980b9' stroke-width='1.5'/><polygon points='70,15 85,25 85,45 70,55 55,45 55,25' fill='url(%23nodeGradient)' stroke='%232980b9' stroke-width='1.5'/><polygon points='30,45 45,55 45,75 30,85 15,75 15,55' fill='url(%23nodeGradient)' stroke='%232980b9' stroke-width='1.5'/><polygon points='70,45 85,55 85,75 70,85 55,75 55,55' fill='url(%23nodeGradient)' stroke='%232980b9' stroke-width='1.5'/><polygon points='50,30 65,40 65,60 50,70 35,60 35,40' fill='url(%23centerNodeGradient)' stroke='%2327ae60' stroke-width='2'/><circle cx='30' cy='30' r='3' fill='%23ffffff'/><circle cx='70' cy='30' r='3' fill='%23ffffff'/><circle cx='30' cy='70' r='3' fill='%23ffffff'/><circle cx='70' cy='70' r='3' fill='%23ffffff'/><circle cx='50' cy='50' r='4' fill='%23ffffff'/></svg>"
-    type="image/svg+xml"
-  ></link>
-);
-
-export const BaseLayout = (
-  props: { children?: any; title?: string; heads?: any } = {
-    title: "Microservice Template",
-  }
-) =>
-  html`<!DOCTYPE html>
-    <html>
-      <head>
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>${props.title}</title>
-        ${props.heads}
-      </head>
-      <body>
-        ${props.children}
-      </body>
-    </html>`;
-
-export const HtmxLayout = (
-  props: { children?: any; title: string; favicon?: any } = {
-    title: "Microservice Template",
-  }
-) =>
-  BaseLayout({
-    title: props.title,
-    heads: html`
-      <script src="https://unpkg.com/htmx.org@latest"></script>
-      <script src="https://unpkg.com/hyperscript.org@latest"></script>
-      <script src="https://cdn.tailwindcss.com"></script>
-      ${props.favicon || DEFAULT_FAVICON}
-    `,
-    children: props.children,
-  });

package/src/plugins/route/components/ServiceStatusPage.tsx

@@ -1,141 +0,0 @@
-import { type ServiceInfo } from "../../../mod.ts";
-
-interface InfoCardProps {
-  icon: string;
-  iconColor: string;
-  bgColor: string;
-  label: string;
-  value: string | any;
-}
-
-const InfoCard = ({
-  icon,
-  iconColor,
-  bgColor,
-  label,
-  value,
-}: InfoCardProps) => (
-  <div className={`${bgColor} p-4 rounded-lg`}>
-    <div className="flex items-center mb-2">
-      <svg
-        className={`w-5 h-5 ${iconColor} mr-2`}
-        fill="none"
-        stroke="currentColor"
-        viewBox="0 0 24 24"
-      >
-        <path
-          strokeLinecap="round"
-          strokeLinejoin="round"
-          strokeWidth={2}
-          d={icon}
-        />
-      </svg>
-      <span className="text-sm font-medium text-gray-600">{label}</span>
-    </div>
-    <p className={`text-xl font-semibold text-gray-900`}>{value}</p>
-  </div>
-);
-
-const getEnvironmentBadgeClass = (env: string): string => {
-  switch (env) {
-    case "prod":
-      return "bg-red-100 text-red-800";
-    case "stg":
-      return "bg-yellow-100 text-yellow-800";
-    case "dev":
-    default:
-      return "bg-blue-100 text-blue-800";
-  }
-};
-
-export const ServiceInfoCards = ({
-  serviceInfo,
-}: {
-  serviceInfo: ServiceInfo;
-}) => {
-  const infoCards = [
-    {
-      icon: "M7 4V2a1 1 0 011-1h8a1 1 0 011 1v2m-9 0h10m-10 0a2 2 0 00-2 2v14a2 2 0 002 2h10a2 2 0 002-2V6a2 2 0 00-2-2",
-      iconColor: "text-blue-600",
-      bgColor: "bg-blue-50",
-      label: "服务名称",
-      value: serviceInfo.name,
-    },
-    {
-      icon: "M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1",
-      iconColor: "text-orange-600",
-      bgColor: "bg-orange-50",
-      label: "服务路径",
-      value: serviceInfo.prefix || "/",
-      isMonospace: true,
-    },
-    {
-      icon: "M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z",
-      iconColor: "text-green-600",
-      bgColor: "bg-green-50",
-      label: "运行环境",
-      value: (
-        <span
-          className={`px-2 py-1 rounded-full text-sm ${getEnvironmentBadgeClass(serviceInfo.env ?? "dev")}`}
-        >
-          {serviceInfo.env ?? "dev"}
-        </span>
-      ),
-    },
-    {
-      icon: "M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z",
-      iconColor: "text-purple-600",
-      bgColor: "bg-purple-50",
-      label: "版本号",
-      value: serviceInfo.version || "unknown",
-    },
-  ];
-
-  return (
-    <div className="bg-white rounded-lg shadow-md p-6 mb-8">
-      <h2 className="text-2xl font-semibold text-gray-800 mb-6 flex items-center">
-        <svg
-          className="w-6 h-6 mr-2 text-blue-600"
-          fill="none"
-          stroke="currentColor"
-          viewBox="0 0 24 24"
-        >
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            strokeWidth={2}
-            d="M13 10V3L4 14h7v7l9-11h-7z"
-          />
-        </svg>
-        服务基本信息
-      </h2>
-
-      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-2 gap-6">
-        {infoCards.map((card, index) => (
-          <InfoCard key={index} {...card} />
-        ))}
-      </div>
-    </div>
-  );
-};
-
-export const ServiceStatusPage = ({
-  serviceInfo,
-}: {
-  serviceInfo: ServiceInfo;
-}) => {
-  return (
-    <div className="min-h-screen bg-gray-50 py-8">
-      <div className="max-w-6xl mx-auto px-4">
-        <div className="mb-8">
-          <h1 className="text-4xl font-bold text-gray-900 mb-2">
-            Service Status
-          </h1>
-        </div>
-        <ServiceInfoCards serviceInfo={serviceInfo} />
-      </div>
-    </div>
-  );
-};
-
-export default ServiceStatusPage;

package/src/plugins/route/decorator.ts

@@ -1,50 +0,0 @@
-import { Handler } from "../../core/decorators";
-import { RouteOptions } from "./types";
-
-/**
- * Route装饰器（Handler的语法糖封装）
- * 固定type="route"，简化HTTP路由标注
- * 使用最新的 Stage 3 装饰器标准
- * 
- * @example
- * ```typescript
- * @Route({ method: "GET", path: "/users" })
- * async getUsers(ctx: Context) {
- *   return ctx.json({ users: [] });
- * }
- * 
- * // 支持多个路径
- * @Route({ path: ["/", "/home", "/dashboard"] })
- * async homePage(ctx: Context) {
- *   return <HomePage />;
- * }
- * ```
- */
-export function Route(options: RouteOptions) {
-  return Handler({
-    type: "route",
-    options,
-  });
-}
-
-/**
- * Page装饰器（Route的别名，用于向后兼容）
- * 专门用于页面路由，默认使用 GET 方法
- * 
- * @example
- * ```typescript
- * @Page({ path: ["/", "/home"] })
- * async adminPage(ctx: Context) {
- *   return HtmxLayout({ title: "Admin", children: <AdminLayout /> });
- * }
- * ```
- */
-export function Page(options: RouteOptions) {
-  // 如果没有指定 method，默认为 GET
-  const pageOptions: RouteOptions = {
-    method: options.method || "GET",
-    ...options,
-  };
-  return Route(pageOptions);
-}
-

package/src/plugins/route/index.ts

@@ -1,16 +0,0 @@
-/**
- * Route Plugin - 路由插件
- * 
- * 提供HTTP路由功能，支持模块级前缀和中间件
- */
-
-export { RoutePlugin } from "./plugin";
-export { Route, Page } from "./decorator";
-export type {
-  RouteModuleOptions,
-  RouteOptions,
-  RoutePluginOptions,
-  HTTPMethod,
-} from "./types";
-export { BaseLayout, HtmxLayout } from "./components/Layout";
-

package/src/plugins/route/plugin.ts

@@ -1,218 +0,0 @@
-import { Context, Hono, MiddlewareHandler } from "hono";
-import {
-  HandlerMetadata,
-  Microservice,
-  Plugin,
-  PluginModuleOptionsSchema,
-  PluginPriority,
-} from "../../core/types";
-import logger from "../../core/logger";
-import { RouteModuleOptions, RouteOptions, RoutePluginOptions } from "./types";
-
-/**
- * RoutePlugin - 核心路由插件
- * 负责解析type="route"的Handler元数据，注册HTTP路由到Hono实例
- * 
- * @example
- * ```typescript
- * // 使用全局中间件（如鉴权）
- * const authMiddleware = async (ctx, next) => {
- *   // 验证 token
- *   await next();
- * };
- * 
- * const routePlugin = new RoutePlugin({
- *   globalMiddlewares: [authMiddleware],
- * });
- * ```
- */
-export class RoutePlugin implements Plugin<RouteModuleOptions> {
-  public readonly name = "route-plugin";
-  public readonly priority = PluginPriority.ROUTE;
-  private engine!: Microservice;
-  private globalMiddlewares: MiddlewareHandler[];
-
-  /**
-   * 构造函数
-   * @param options 插件配置选项
-   */
-  constructor(options?: RoutePluginOptions) {
-    this.globalMiddlewares = options?.globalMiddlewares || [];
-  }
-
-  /**
-   * 声明Module配置Schema（用于类型推导+运行时校验）
-   */
-  getModuleOptionsSchema(): PluginModuleOptionsSchema<RouteModuleOptions> {
-    return {
-      _type: {} as RouteModuleOptions,
-      validate: (options) => {
-        if (
-          options.routePrefix !== undefined &&
-          typeof options.routePrefix !== "string"
-        ) {
-          return "routePrefix must be a string";
-        }
-        if (options.routePrefix && !options.routePrefix.startsWith("/")) {
-          return `routePrefix must start with '/'`;
-        }
-        if (
-          options.routeMiddlewares !== undefined &&
-          !Array.isArray(options.routeMiddlewares)
-        ) {
-          return "routeMiddlewares must be an array";
-        }
-        return true;
-      },
-    };
-  }
-
-  /**
-   * 引擎初始化钩子：获取Hono实例
-   */
-  onInit(engine: Microservice): void {
-    this.engine = engine;
-    logger.info("RoutePlugin initialized");
-  }
-
-  /**
-   * Handler加载钩子：解析type="route"的Handler元数据，注册HTTP路由
-   */
-  onHandlerLoad(handlers: HandlerMetadata[]): void {
-    // 筛选出所有type="route"的Handler元数据
-    const routeHandlers = handlers.filter(
-      (handler) => handler.type === "route"
-    );
-
-    logger.info(`Found ${routeHandlers.length} route handler(s)`);
-
-    for (const handler of routeHandlers) {
-      const routeOptions = handler.options as RouteOptions;
-      const methodName = handler.methodName;
-      const moduleClass = handler.module;
-
-      // 获取模块实例
-      const moduleInstance = this.engine.get(moduleClass);
-      if (!moduleInstance) {
-        logger.warn(
-          `Module instance not found for ${moduleClass.name}, skipping route registration`
-        );
-        continue;
-      }
-
-      // 获取模块配置
-      const moduleMetadata = this.engine
-        .getModules()
-        .find((m: any) => m.clazz === moduleClass);
-      const moduleOptions = (moduleMetadata?.options ||
-        {}) as RouteModuleOptions;
-
-      // 构建路由路径数组（支持单个路径或多个路径）
-      const routePrefix = moduleOptions.routePrefix || "";
-      const paths = Array.isArray(routeOptions.path)
-        ? routeOptions.path
-        : [routeOptions.path];
-      const fullPaths = paths.map((p) => routePrefix + p);
-
-      // 构建路由处理器
-      const routeHandler = async (ctx: Context) => {
-        // 引擎保证此时原型上的方法已经被所有包装插件包装
-        // 直接调用方法名即可获取包装后的方法
-        const method = (moduleInstance as any)[methodName];
-        if (typeof method !== "function") {
-          return ctx.json({ error: "Handler method not found" }, 500);
-        }
-
-        try {
-          const result = await method.call(moduleInstance, ctx);
-          // Hono 会自动处理 JSX/HTML/Response 响应
-          // 如果返回的是普通对象，自动转换为 JSON
-          if (result instanceof Response) {
-            return result;
-          }
-          // 如果返回的是 JSX 或其他 Hono 支持的类型，直接返回
-          if (
-            typeof result === "string" ||
-            (typeof result === "object" && result !== null && "type" in result)
-          ) {
-            return result;
-          }
-          // 否则作为 JSON 返回
-          return ctx.json(result);
-        } catch (error) {
-          logger.error(
-            `Error in route handler ${moduleClass.name}.${methodName}`,
-            error
-          );
-          return ctx.json(
-            {
-              error: "Internal server error",
-              message: error instanceof Error ? error.message : String(error),
-            },
-            500
-          );
-        }
-      };
-
-      // 获取 Hono 实例
-      const hono = this.engine.getHono();
-
-      // 注册路由（支持单个方法或多个方法，默认为 GET）
-      const methods = routeOptions.method
-        ? Array.isArray(routeOptions.method)
-          ? routeOptions.method
-          : [routeOptions.method]
-        : ["GET"];
-
-      // 为每个路径注册路由
-      for (const fullPath of fullPaths) {
-        let route = hono;
-
-        // 应用全局中间件（最先执行）
-        if (this.globalMiddlewares.length > 0) {
-          route = route.use(fullPath, ...this.globalMiddlewares);
-        }
-
-        // 应用模块级中间件
-        if (
-          moduleOptions.routeMiddlewares &&
-          moduleOptions.routeMiddlewares.length > 0
-        ) {
-          route = route.use(fullPath, ...moduleOptions.routeMiddlewares);
-        }
-
-        // 应用路由级中间件（最后执行）
-        if (routeOptions.middlewares && routeOptions.middlewares.length > 0) {
-          route = route.use(fullPath, ...routeOptions.middlewares);
-        }
-
-        // 为每个 HTTP 方法注册路由
-        for (const method of methods) {
-          const methodLower = method.toLowerCase();
-          if (
-            methodLower === "get" ||
-            methodLower === "post" ||
-            methodLower === "put" ||
-            methodLower === "delete" ||
-            methodLower === "patch" ||
-            methodLower === "head" ||
-            methodLower === "options"
-          ) {
-            (route as any)[methodLower](fullPath, routeHandler);
-            const description = routeOptions.description
-              ? ` (${routeOptions.description})`
-              : "";
-            logger.info(
-              `Registered route: ${method.toUpperCase()} ${fullPath} -> ${moduleClass.name}.${methodName}${description}`
-            );
-          } else {
-            logger.warn(
-              `Unsupported HTTP method: ${method}, skipping route ${fullPath}`
-            );
-          }
-        }
-      }
-    }
-  }
-
-}