imean-service-engine 2.0.0 → 2.0.2

package/src/plugins/action/plugin.ts

@@ -1,349 +0,0 @@
-import * as ejson from "ejson";
-import { Context } from "hono";
-import logger from "../../core/logger";
-import {
-  HandlerMetadata,
-  Microservice,
-  Plugin,
-  PluginModuleOptionsSchema,
-  PluginPriority,
-} from "../../core/types";
-import { ActionModuleOptions, ActionOptions } from "./types";
-import { buildActionPath, parseAndValidateParams } from "./utils";
-
-/**
- * 检查对象是否是 AsyncIterable
- */
-function isAsyncIterable(obj: any): obj is AsyncIterable<any> {
-  return obj != null && typeof obj[Symbol.asyncIterator] === "function";
-}
-
-/**
- * ActionPlugin - 动作处理插件
- * 提供基于下标的参数传递、zod 校验和自动参数注入
- */
-export class ActionPlugin implements Plugin<ActionModuleOptions> {
-  public readonly name = "action-plugin";
-  public readonly priority = PluginPriority.ROUTE; // 路由插件优先级最低，必须最后执行
-  private engine!: Microservice;
-
-  /**
-   * 声明Module配置Schema（用于类型推导+运行时校验）
-   */
-  getModuleOptionsSchema(): PluginModuleOptionsSchema<ActionModuleOptions> {
-    return {
-      _type: {} as ActionModuleOptions,
-      validate: (options) => {
-        if (
-          options.actionMiddlewares !== undefined &&
-          !Array.isArray(options.actionMiddlewares)
-        ) {
-          return "actionMiddlewares must be an array";
-        }
-        return true;
-      },
-    };
-  }
-
-  /**
-   * 引擎初始化钩子：获取Hono实例
-   */
-  onInit(engine: Microservice): void {
-    this.engine = engine;
-    logger.info("ActionPlugin initialized");
-  }
-
-  /**
-   * Handler加载钩子：解析type="action"的Handler元数据，注册HTTP路由
-   */
-  onHandlerLoad(handlers: HandlerMetadata[]): void {
-    // 筛选出所有type="action"的Handler元数据
-    const actionHandlers = handlers.filter(
-      (handler) => handler.type === "action"
-    );
-
-    logger.info(`Found ${actionHandlers.length} action handler(s)`);
-
-    for (const handler of actionHandlers) {
-      const actionOptions = handler.options as ActionOptions;
-      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 action registration`
-        );
-        continue;
-      }
-
-      // 获取模块配置
-      const moduleMetadata = this.engine
-        .getModules()
-        .find((m: any) => m.clazz === moduleClass);
-      if (!moduleMetadata) {
-        logger.warn(
-          `Module metadata not found for ${moduleClass.name}, skipping action registration`
-        );
-        continue;
-      }
-      const moduleOptions = (moduleMetadata.options ||
-        {}) as ActionModuleOptions;
-
-      // 构建路由路径（引擎prefix + 模块名 + Handler名）
-      const enginePrefix = this.engine.options.prefix || "";
-      const actionPath = buildActionPath(
-        enginePrefix,
-        moduleMetadata.name,
-        methodName
-      );
-
-      // 获取参数校验 schemas
-      const paramSchemas = actionOptions.params || [];
-      const returnSchema = actionOptions.returns;
-
-      // 构建路由处理器
-      const actionHandler = async (ctx: Context) => {
-        // 引擎保证此时原型上的方法已经被所有包装插件包装
-        // 直接调用方法名即可获取包装后的方法
-        const method = (moduleInstance as any)[methodName];
-        if (typeof method !== "function") {
-          const errorResponse = ejson.stringify({
-            success: false,
-            error: "Action method not found",
-          });
-          return ctx.text(errorResponse, 500, {
-            "Content-Type": "application/json",
-          });
-        }
-
-        try {
-          // 解析请求体中的下标参数
-          // 支持 GET 请求（从 query 参数解析）和 POST 等（从 body 解析）
-          let body: any = {};
-          if (ctx.req.method === "GET") {
-            // GET 请求从 query 参数解析
-            const url = new URL(ctx.req.url);
-            url.searchParams.forEach((value, key) => {
-              body[key] = value;
-            });
-          } else {
-            // POST 等请求从 body 解析，使用 ejson 反序列化以支持更多数据类型
-            try {
-              const rawBody = await ctx.req.text();
-              if (rawBody) {
-                body = ejson.parse(rawBody);
-              }
-            } catch (parseError) {
-              // 如果 ejson 解析失败，尝试 JSON 解析（向后兼容）
-              try {
-                body = await ctx.req.json().catch(() => ({}));
-              } catch {
-                body = {};
-              }
-            }
-          }
-
-          // 解析并验证参数（一次性验证所有参数）
-          const validation = parseAndValidateParams(body, paramSchemas);
-          if (!validation.success) {
-            const errors = validation.error.issues || [];
-            const errorMessage = `Validation failed: ${errors
-              .map((e) => {
-                // 处理路径：如果是参数索引（数字），显示为参数位置；否则显示为路径
-                const path = e.path || [];
-                const pathStr =
-                  path.length > 0
-                    ? path
-                        .map((p, i) => {
-                          // 第一个路径是参数索引（"0", "1"等），转换为参数位置
-                          if (
-                            i === 0 &&
-                            typeof p === "string" &&
-                            /^\d+$/.test(p)
-                          ) {
-                            return `参数[${p}]`;
-                          }
-                          // 后续路径是嵌套属性
-                          return String(p);
-                        })
-                        .join(".")
-                    : "unknown";
-                return `${pathStr}: ${e.message}`;
-              })
-              .join(", ")}`;
-            const errorResponse = ejson.stringify({
-              success: false,
-              error: errorMessage,
-            });
-            return ctx.text(errorResponse, 400, {
-              "Content-Type": "application/json",
-            });
-          }
-
-          // 调用方法，自动注入参数
-          // 检查方法是否需要 Context 参数：如果方法的参数数量比定义的参数多 1，则第一个参数是 Context
-          const methodLength = method.length;
-          const paramsLength = paramSchemas.length;
-          const args = [...validation.data];
-
-          // 如果方法参数数量比定义的参数多 1，且第一个参数可能是 Context
-          if (methodLength > paramsLength) {
-            // 将 Context 作为第一个参数注入
-            args.unshift(ctx);
-          }
-
-          const result = await method.apply(moduleInstance, args);
-
-          // 如果是流式返回（async generator），转换为 HTTP 流式响应（SSE 格式）
-          if (actionOptions.stream) {
-            if (!isAsyncIterable(result)) {
-              const errorResponse = ejson.stringify({
-                success: false,
-                error: "Stream action must return AsyncIterable",
-              });
-              return ctx.text(errorResponse, 500, {
-                "Content-Type": "application/json",
-              });
-            }
-
-            // 使用流式响应格式
-            // 客户端使用 tryParseCompleteJson 函数来处理流式响应，支持从缓冲区解析完整的 JSON 对象
-            // 格式：{ value?: T, done: boolean, error?: string }
-            // 客户端会累积不完整的 chunk 到缓冲区，然后使用 tryParseCompleteJson 解析完整的 JSON 对象
-            // 所以我们可以直接发送 JSON 对象，客户端会自动处理合并的 chunk
-            const encoder = new TextEncoder();
-            const iterator = result[Symbol.asyncIterator]();
-            const stream = new ReadableStream<Uint8Array>({
-              async start(controller) {
-                try {
-                  while (true) {
-                    const { value, done } = await iterator.next();
-                    if (done) {
-                      // 发送结束标记
-                      controller.enqueue(
-                        encoder.encode(ejson.stringify({ done: true }))
-                      );
-                      controller.close();
-                      break;
-                    }
-                    // 发送数据块，每个 JSON 对象是完整的
-                    // 客户端会使用 tryParseCompleteJson 来处理可能被合并的 chunk
-                    controller.enqueue(
-                      encoder.encode(ejson.stringify({ value, done: false }))
-                    );
-                  }
-                } catch (error) {
-                  // 发送错误
-                  controller.enqueue(
-                    encoder.encode(
-                      ejson.stringify({
-                        error:
-                          error instanceof Error
-                            ? error.message
-                            : String(error),
-                        done: true,
-                      })
-                    )
-                  );
-                  controller.close();
-                }
-              },
-            });
-
-            return new Response(stream, {
-              headers: {
-                "Content-Type": "text/event-stream",
-                "Cache-Control": "no-cache",
-                Connection: "keep-alive",
-              },
-            });
-          }
-
-          // 校验返回值（如果提供了 return schema）
-          if (returnSchema) {
-            const returnValidation = returnSchema.safeParse(result);
-            if (!returnValidation.success) {
-              logger.error(
-                `Return value validation failed for ${moduleClass.name}.${methodName}`,
-                returnValidation.error
-              );
-              const returnErrors = returnValidation.error.issues || [];
-              const errorMessage = `Return value validation failed: ${returnErrors
-                .map((e) => {
-                  const path = e.path || [];
-                  const pathStr =
-                    path.length > 0
-                      ? path.map((p) => String(p)).join(".")
-                      : "root";
-                  return `${pathStr}: ${e.message}`;
-                })
-                .join(", ")}`;
-              const errorResponse = ejson.stringify({
-                success: false,
-                error: errorMessage,
-              });
-              return ctx.text(errorResponse, 400, {
-                "Content-Type": "application/json",
-              });
-            }
-            // 使用 ejson 序列化成功响应
-            const successResponse = ejson.stringify({
-              success: true,
-              data: returnValidation.data,
-            });
-            return ctx.text(successResponse, 200, {
-              "Content-Type": "application/json",
-            });
-          }
-
-          // 使用 ejson 序列化成功响应
-          const successResponse = ejson.stringify({
-            success: true,
-            data: result,
-          });
-          return ctx.text(successResponse, 200, {
-            "Content-Type": "application/json",
-          });
-        } catch (error) {
-          logger.error(
-            `Error in action handler ${moduleClass.name}.${methodName}`,
-            error
-          );
-          const errorResponse = ejson.stringify({
-            success: false,
-            error: error instanceof Error ? error.message : String(error),
-          });
-          return ctx.text(errorResponse, 500, {
-            "Content-Type": "application/json",
-          });
-        }
-      };
-
-      // 获取 Hono 实例
-      const hono = this.engine.getHono();
-
-      // 应用模块级中间件
-      let route = hono;
-      if (
-        moduleOptions.actionMiddlewares &&
-        moduleOptions.actionMiddlewares.length > 0
-      ) {
-        route = route.use(actionPath, ...moduleOptions.actionMiddlewares);
-      }
-
-      // 应用动作级中间件
-      if (actionOptions.middlewares && actionOptions.middlewares.length > 0) {
-        route = route.use(actionPath, ...actionOptions.middlewares);
-      }
-
-      // 注册路由（固定支持 GET 和 POST）
-      route.get(actionPath, actionHandler);
-      route.post(actionPath, actionHandler);
-      logger.info(
-        `[注册动作] ${moduleClass.name}.${methodName} ${actionOptions.description}`
-      );
-    }
-  }
-}

package/src/plugins/action/types.ts

@@ -1,49 +0,0 @@
-import { z } from "zod";
-import { MiddlewareHandler } from "hono";
-
-/**
- * Action装饰器配置选项
- */
-export interface ActionOptions {
-  /**
-   * 动作描述
-   */
-  description?: string;
-
-  /**
-   * 参数校验 Schema（使用 zod）
-   * 数组顺序对应方法参数的顺序
-   */
-  params: z.ZodTypeAny[];
-
-  /**
-   * 返回值校验 Schema（使用 zod）
-   */
-  returns?: z.ZodTypeAny;
-
-  /**
-   * 是否流式返回（默认 false）
-   */
-  stream?: boolean;
-
-  /**
-   * 是否幂等（默认 false）
-   */
-  idempotence?: boolean;
-
-  /**
-   * 路由专属中间件
-   */
-  middlewares?: MiddlewareHandler[];
-}
-
-/**
- * ActionPlugin的Module配置
- */
-export interface ActionModuleOptions {
-  /**
-   * 模块级路由中间件
-   */
-  actionMiddlewares?: MiddlewareHandler[];
-}
-

package/src/plugins/action/utils.test.ts

@@ -1,196 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { z } from "zod";
-import {
-  buildActionPath,
-  buildParamsSchema,
-  parseAndValidateParams,
-} from "./utils";
-
-describe("ActionPlugin Utils", () => {
-  describe("buildParamsSchema", () => {
-    it("应该能够构建参数验证 Schema", () => {
-      const schemas = [z.string(), z.number()];
-      const paramsSchema = buildParamsSchema(schemas);
-
-      // 验证 Schema 结构
-      const result = paramsSchema.safeParse({ "0": "Alice", "1": 25 });
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data["0"]).toBe("Alice");
-        expect(result.data["1"]).toBe(25);
-      }
-    });
-
-    it("应该支持空数组", () => {
-      const schemas: z.ZodTypeAny[] = [];
-      const paramsSchema = buildParamsSchema(schemas);
-
-      const result = paramsSchema.safeParse({});
-      expect(result.success).toBe(true);
-    });
-
-    it("应该支持可选参数", () => {
-      const schemas = [z.string(), z.number().optional(), z.string()];
-      const paramsSchema = buildParamsSchema(schemas);
-
-      // 缺少可选参数应该通过验证
-      const result = paramsSchema.safeParse({ "0": "Alice", "2": "Bob" });
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data["0"]).toBe("Alice");
-        expect(result.data["1"]).toBeUndefined();
-        expect(result.data["2"]).toBe("Bob");
-      }
-    });
-
-    it("应该支持复杂类型", () => {
-      const UserSchema = z.object({
-        id: z.string(),
-        name: z.string(),
-      });
-      const schemas = [z.string(), UserSchema];
-      const paramsSchema = buildParamsSchema(schemas);
-
-      const result = paramsSchema.safeParse({
-        "0": "test",
-        "1": { id: "1", name: "Alice" },
-      });
-      expect(result.success).toBe(true);
-    });
-  });
-
-  describe("parseAndValidateParams", () => {
-    it("应该能够解析并验证参数", () => {
-      const body = { "0": "Alice", "1": 25 };
-      const schemas = [z.string(), z.number()];
-      const result = parseAndValidateParams(body, schemas);
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data).toEqual(["Alice", 25]);
-      }
-    });
-
-    it("应该返回空数组当没有定义参数时", () => {
-      const body = { "0": "Alice" };
-      const schemas: z.ZodTypeAny[] = [];
-      const result = parseAndValidateParams(body, schemas);
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data).toEqual([]);
-      }
-    });
-
-    it("应该处理空 body", () => {
-      const body = null;
-      const schemas = [z.string().optional()];
-      const result = parseAndValidateParams(body, schemas);
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data[0]).toBeUndefined();
-      }
-    });
-
-    it("应该验证参数类型", () => {
-      const body = { "0": "Alice", "1": "invalid" };
-      const schemas = [z.string(), z.number()];
-      const result = parseAndValidateParams(body, schemas);
-
-      expect(result.success).toBe(false);
-      if (!result.success) {
-        // Zod 4.x: 使用 issues 替代 errors
-        const errors = result.error.errors || result.error.issues || [];
-        expect(errors.length).toBeGreaterThan(0);
-        expect(errors[0].path).toContain("1");
-      }
-    });
-
-    it("应该支持可选参数", () => {
-      const body = { "0": "Alice" };
-      const schemas = [
-        z.string(),
-        z.number().optional(),
-        z.string().optional(),
-      ];
-      const result = parseAndValidateParams(body, schemas);
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data[0]).toBe("Alice");
-        expect(result.data[1]).toBeUndefined();
-        expect(result.data[2]).toBeUndefined();
-      }
-    });
-
-    it("应该支持参数对齐（跳过中间参数）", () => {
-      const body = { "0": "Alice", "3": true };
-      const schemas = [
-        z.string(),
-        z.number().optional(),
-        z.string().optional(),
-        z.boolean(),
-      ];
-      const result = parseAndValidateParams(body, schemas);
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data[0]).toBe("Alice");
-        expect(result.data[1]).toBeUndefined();
-        expect(result.data[2]).toBeUndefined();
-        expect(result.data[3]).toBe(true);
-      }
-    });
-
-    it("应该正确处理缺失的必需参数", () => {
-      const body = { "0": "Alice" };
-      const schemas = [z.string(), z.number()];
-      const result = parseAndValidateParams(body, schemas);
-
-      expect(result.success).toBe(false);
-      if (!result.success) {
-        // Zod 4.x: 使用 issues 替代 errors
-        const errors = result.error.errors || result.error.issues || [];
-        expect(errors.length).toBeGreaterThan(0);
-        // 应该报告缺少 "1" 参数
-        const hasMissingError = errors.some((err) =>
-          err.path?.includes("1")
-        );
-        expect(hasMissingError).toBe(true);
-      }
-    });
-  });
-
-  describe("buildActionPath", () => {
-    it("应该能够构建带 prefix 的路由路径", () => {
-      const path = buildActionPath("/api", "user-service", "createUser");
-      expect(path).toBe("/api/user-service/createUser");
-    });
-
-    it("应该能够构建不带 prefix 的路由路径", () => {
-      const path = buildActionPath("", "user-service", "createUser");
-      expect(path).toBe("/user-service/createUser");
-    });
-
-    it("应该处理 prefix 末尾的斜杠", () => {
-      const path = buildActionPath("/api/", "user-service", "createUser");
-      expect(path).toBe("/api/user-service/createUser");
-    });
-
-    it("应该处理多个连续的斜杠", () => {
-      const path = buildActionPath("//api//", "user-service", "createUser");
-      expect(path).toBe("/api/user-service/createUser");
-    });
-
-    it("应该处理 prefix 为空字符串的情况", () => {
-      const path = buildActionPath("", "test-service", "testMethod");
-      expect(path).toBe("/test-service/testMethod");
-    });
-
-    it("应该处理只有斜杠的 prefix", () => {
-      const path = buildActionPath("/", "test-service", "testMethod");
-      expect(path).toBe("/test-service/testMethod");
-    });
-  });
-});

package/src/plugins/action/utils.ts

@@ -1,111 +0,0 @@
-import { z } from "zod";
-
-/**
- * 构建参数验证 Schema
- * 将参数数组转换为对象格式：{"0": schema0, "1": schema1, ...}
- *
- * @param schemas 参数校验 Schema 数组
- * @returns ZodObject Schema
- *
- * @example
- * ```ts
- * const schemas = [z.string(), z.number()];
- * const paramsSchema = buildParamsSchema(schemas);
- * // 等价于 z.object({ "0": z.string(), "1": z.number() })
- * ```
- */
-export function buildParamsSchema(
-  schemas: z.ZodTypeAny[]
-): z.ZodObject<Record<string, z.ZodTypeAny>> {
-  const shape: Record<string, z.ZodTypeAny> = {};
-  for (let i = 0; i < schemas.length; i++) {
-    shape[String(i)] = schemas[i];
-  }
-  return z.object(shape);
-}
-
-/**
- * 解析并验证请求体中的下标参数
- * 请求格式：{"0":"value1","1":"value2",...}
- * 根据 metadata 中的 params 数组定义来确定参数数量和类型
- *
- * @param body 请求体对象
- * @param schemas 参数校验 Schema 数组
- * @returns 验证结果，成功时返回参数数组，失败时返回 ZodError
- *
- * @example
- * ```ts
- * const body = { "0": "Alice", "1": 25 };
- * const schemas = [z.string(), z.number()];
- * const result = parseAndValidateParams(body, schemas);
- * // result.success === true
- * // result.data === ["Alice", 25]
- * ```
- */
-export function parseAndValidateParams(
-  body: any,
-  schemas: z.ZodTypeAny[]
-): { success: true; data: any[] } | { success: false; error: z.ZodError } {
-  if (!body || typeof body !== "object") {
-    body = {};
-  }
-
-  // 如果没有定义参数，直接返回空数组
-  if (schemas.length === 0) {
-    return { success: true, data: [] };
-  }
-
-  // 构建对象格式的验证 Schema：{"0": schema0, "1": schema1, ...}
-  const paramsSchema = buildParamsSchema(schemas);
-
-  // 一次性验证所有参数
-  const validation = paramsSchema.safeParse(body);
-  if (!validation.success) {
-    return {
-      success: false,
-      error: validation.error,
-    };
-  }
-
-  // 将验证后的对象转换为数组，按索引顺序提取值
-  const validatedData: any[] = [];
-  for (let i = 0; i < schemas.length; i++) {
-    validatedData[i] = validation.data[String(i)];
-  }
-
-  return {
-    success: true,
-    data: validatedData,
-  };
-}
-
-/**
- * 构建 Action 路由路径
- * 格式：引擎prefix + 模块名 + Handler名
- *
- * @param enginePrefix 引擎路由前缀（可选）
- * @param moduleName 模块名
- * @param handlerName Handler 方法名
- * @returns 规范化后的路由路径
- *
- * @example
- * ```ts
- * buildActionPath("/api", "user-service", "createUser")
- * // => "/api/user-service/createUser"
- *
- * buildActionPath("", "user-service", "createUser")
- * // => "/user-service/createUser"
- * ```
- */
-export function buildActionPath(
-  enginePrefix: string,
-  moduleName: string,
-  handlerName: string
-): string {
-  // 移除prefix末尾的斜杠，然后拼接路径，最后清理多余的斜杠
-  const normalizedPrefix = enginePrefix.replace(/\/+$/, "");
-  return `/${normalizedPrefix}/${moduleName}/${handlerName}`
-    .replace(/\/+/g, "/")
-    .replace(/^\/\//, "/"); // 处理prefix为空时产生的双斜杠
-}
-