imean-service-engine 2.0.0 → 2.0.2

package/src/plugins/client-code/generator.ts

@@ -1,263 +0,0 @@
-import { type z } from "zod";
-import { formatCode } from "./format";
-import type { ModuleInfo } from "./types";
-
-/**
- * 获取 Zod 类型的 TypeScript 类型字符串
- */
-export function getZodTypeString(
-  schema: z.ZodType<any>,
-  defaultOptional: boolean = false
-): string {
-  // 递归处理可空和可选类型
-  function processType(type: z.ZodType<any>): string {
-    if (!type) {
-      return "unknown";
-    }
-    // Zod 4.x: 使用 _def 访问内部定义，使用 as any 避免类型错误
-    const def = (type as any)._def as any;
-
-    // Zod 4.x: 使用 def.type 替代 def.typeName
-    const typeName = def.type;
-
-    // 处理可空类型
-    if (typeName === "nullable") {
-      return `${processType(def.innerType)} | null`;
-    }
-
-    // 处理可选类型
-    if (typeName === "optional") {
-      return processType(def.innerType);
-    }
-
-    // 处理 transform 类型 (ZodEffects/ZodPipe)
-    // Zod 4.x: transform 变成了 pipe 类型，使用 def.in
-    if (typeName === "pipe" && def.in) {
-      return processType(def.in);
-    }
-    // Zod 3.x: 使用 def.schema (兼容旧版本)
-    if (typeName === "effects" && def.schema) {
-      return processType(def.schema);
-    }
-
-    // 处理基础类型
-    // Zod 4.x: 只使用新的类型名称（如 "string", "number" 等）
-    switch (typeName) {
-      case "string": {
-        return "string";
-      }
-      case "number": {
-        return "number";
-      }
-      case "bigint": {
-        return "bigint";
-      }
-      case "boolean": {
-        return "boolean";
-      }
-      case "array": {
-        // Zod 4.x: 使用 def.element
-        const elementType = processType(def.element);
-        return `${elementType}[]`;
-      }
-      case "date": {
-        return "Date";
-      }
-      case "object": {
-        // Zod 4.x: shape 是一个对象，不再是函数
-        const shape = typeof def.shape === "function" ? def.shape() : def.shape;
-        const props = Object.entries(shape)
-          .map(([key, value]) => {
-            if (key.includes("-")) {
-              key = `'${key}'`;
-            }
-            const fieldDef = (value as any)._def as any;
-            const fieldTypeName = fieldDef.type;
-            const isOptional = fieldTypeName === "optional";
-            const isDefault = defaultOptional && fieldTypeName === "default";
-            const fieldType = processType(
-              isOptional ? fieldDef.innerType : value
-            );
-            return `${key}${isOptional || isDefault ? "?" : ""}: ${fieldType}`;
-          })
-          .join("; ");
-        return `{ ${props} }`;
-      }
-
-      case "union": {
-        return def.options
-          .map((opt: z.ZodType<any>) => processType(opt))
-          .join(" | ");
-      }
-      case "null": {
-        return "null";
-      }
-      case "promise": {
-        return `Promise<${processType(def.type)}>`;
-      }
-      case "void": {
-        return "void";
-      }
-      case "record": {
-        // Zod 4.x: z.record(valueType) 时，只有 keyType（实际上是 valueType），keyType 默认为 string
-        // z.record(keyType, valueType) 时，keyType 和 valueType 都存在
-        if (def.valueType) {
-          const keyType = def.keyType ? processType(def.keyType) : "string";
-          return `Record<${keyType}, ${processType(def.valueType)}>`;
-        } else if (def.keyType) {
-          // z.record(valueType) 的情况，keyType 实际上是 valueType
-          return `Record<string, ${processType(def.keyType)}>`;
-        }
-        return "Record<string, any>";
-      }
-      case "map": {
-        return `Map<${processType(def.keyType)}, ${processType(
-          def.valueType
-        )}>`;
-      }
-      case "any": {
-        return "any";
-      }
-      case "unknown": {
-        return "unknown";
-      }
-      case "enum": {
-        // Zod 4.x: 使用 def.entries，entries 是一个对象
-        const values = def.entries ? Object.values(def.entries) : [];
-        return (
-          "(" +
-          values.map((opt: unknown) => `"${String(opt)}"`).join(" | ") +
-          ")"
-        );
-      }
-      case "default": {
-        return processType(def.innerType);
-      }
-      default: {
-        if (type.safeParse(new Uint8Array()).success) {
-          return "Uint8Array";
-        }
-        return "unknown";
-      }
-    }
-  }
-
-  return processType(schema);
-}
-
-/**
- * 生成客户端代码
- * @param modules 模块信息
- * @returns 生成的客户端代码
- */
-export async function generateClientCode(
-  modules: Record<string, ModuleInfo>
-): Promise<string> {
-  const imports = [
-    "// 这个文件是自动生成的，请不要手动修改",
-    "",
-    'import { MicroserviceClient as BaseMicroserviceClient } from "imean-service-client";',
-    'export * from "imean-service-client";',
-    "",
-  ].join("\n");
-
-  /**
-   * 将模块名转换为有效的 TypeScript 标识符
-   * 例如: "user-service" -> "UserService"
-   */
-  function toPascalCase(moduleName: string): string {
-    return moduleName
-      .split("-")
-      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-      .join("");
-  }
-
-  /**
-   * 将模块名转换为有效的 TypeScript 属性名（驼峰命名）
-   * 例如: "user-service" -> "userService"
-   */
-  function toCamelCase(moduleName: string): string {
-    const parts = moduleName.split("-");
-    return (
-      parts[0] +
-      parts
-        .slice(1)
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join("")
-    );
-  }
-
-  const interfaces = Object.entries(modules)
-    .map(([name, module]) => {
-      const methods = Object.entries(module.actions)
-        .map(([actionName, action]) => {
-          if (!action.params) {
-            throw new Error(`Missing params for action ${actionName}`);
-          }
-
-          // 使用 getZodTypeString 提取参数和返回值类型
-          // 优先使用 paramNames，如果没有则使用 param.description，最后使用 arg${index}
-          const paramNames = action.paramNames || [];
-          const params = action.params
-            .map((param: z.ZodType<any>, index: any) => {
-              const paramName =
-                paramNames[index] ||
-                param.description ||
-                `arg${index}`;
-              // 检查参数是否可选或有默认值
-              const paramDef = (param as any)._def as any;
-              const isOptional = param.isOptional();
-              const hasDefault = paramDef?.type === "default";
-              return `${paramName}${isOptional || hasDefault ? "?" : ""}: ${getZodTypeString(
-                param,
-                true
-              )}`;
-            })
-            .join(", ");
-
-          const returnType = action.returns
-            ? getZodTypeString(action.returns)
-            : "void";
-
-          return `
-        /**
-         * ${action.description || ""}
-         */
-        ${actionName}: (${params}) => Promise<${
-          action.stream ? `AsyncIterable<${returnType}>` : returnType
-        }>;`;
-        })
-        .join("\n    ");
-
-      const interfaceName = `${toPascalCase(name)}Module`;
-      return `export interface ${interfaceName} {
-    ${methods}
-}`;
-    })
-    .join("\n\n");
-
-  const clientClass = `export class MicroserviceClient extends BaseMicroserviceClient {
-  constructor(options: any) {
-    super(options);
-  }
-
-  ${Object.entries(modules)
-    .map(([name, module]) => {
-      const methods = Object.entries(module.actions)
-        .map(([actionName, action]) => {
-          return `${actionName}: { idempotent: ${!!action.idempotence}, stream: ${!!action.stream} }`;
-        })
-        .join(",\n      ");
-
-      const propertyName = toCamelCase(name);
-      const interfaceName = `${toPascalCase(name)}Module`;
-
-      return `public readonly ${propertyName} = this.registerModule<${interfaceName}>("${name}", {
-      ${methods}
-    });`;
-    })
-    .join("\n\n  ")}
-}`;
-
-  return await formatCode([imports, interfaces, clientClass].join("\n\n"));
-}

package/src/plugins/client-code/index.ts

@@ -1,15 +0,0 @@
-/**
- * Client Code Plugin - 客户端代码生成插件
- * 
- * 提供自动生成类型化客户端代码的功能，支持服务间互调
- */
-
-export { ClientCodePlugin } from "./plugin";
-export type { ClientCodePluginOptions } from "./plugin";
-export type { ModuleInfo, ActionInfo } from "./types";
-export { generateClientCode, getZodTypeString } from "./generator";
-export {
-  convertHandlersToModuleInfo,
-  convertHandlersToModuleInfoWithMetadata,
-} from "./utils";
-

package/src/plugins/client-code/plugin.ts

@@ -1,158 +0,0 @@
-import { Context } from "hono";
-import { promises as fs } from "fs";
-import { dirname } from "path";
-import {
-  HandlerMetadata,
-  Microservice,
-  Plugin,
-  PluginPriority,
-} from "../../core/types";
-import logger from "../../core/logger";
-import { convertHandlersToModuleInfoWithMetadata } from "./utils";
-import { generateClientCode } from "./generator";
-
-/**
- * ClientCodePlugin 配置选项
- */
-export interface ClientCodePluginOptions {
-  /**
-   * 客户端代码保存路径（可选）
-   * 如果设置，将在生成代码后自动保存到该路径
-   * 通常用于开发阶段自动生成客户端代码用于调试或测试
-   * 
-   * @example
-   * ```ts
-   * new ClientCodePlugin({ clientSavePath: "./generated/client.ts" })
-   * ```
-   */
-  clientSavePath?: string;
-}
-
-/**
- * ClientCodePlugin - 客户端代码生成插件
- * 收集所有 Action handlers，生成类型化的客户端代码，
- * 并提供 /client.ts 路由供远程下载
- */
-export class ClientCodePlugin implements Plugin {
-  public readonly name = "client-code-plugin";
-  public readonly priority = PluginPriority.ROUTE; // 路由插件优先级，在 ActionPlugin 之后
-
-  private engine!: Microservice;
-  private actionHandlers: HandlerMetadata[] = [];
-  private generatedCode: string | null = null;
-  private readonly clientSavePath?: string;
-
-  constructor(options?: ClientCodePluginOptions) {
-    this.clientSavePath = options?.clientSavePath;
-  }
-
-  /**
-   * 引擎初始化钩子
-   */
-  onInit(engine: Microservice): void {
-    this.engine = engine;
-    logger.info("ClientCodePlugin initialized");
-  }
-
-  /**
-   * Handler加载钩子：收集所有 Action handlers
-   */
-  onHandlerLoad(handlers: HandlerMetadata[]): void {
-    // 筛选出所有 type="action" 的 Handler
-    const actionHandlers = handlers.filter(
-      (handler) => handler.type === "action"
-    );
-
-    this.actionHandlers = actionHandlers;
-    logger.info(
-      `ClientCodePlugin collected ${actionHandlers.length} action handler(s)`
-    );
-  }
-
-  /**
-   * 引擎启动后钩子：注册客户端代码下载路由
-   */
-  async onAfterStart(engine: Microservice): Promise<void> {
-    // 生成客户端代码
-    await this.generateCode();
-
-    // 注册路由：{prefix}/client.ts
-    const prefix = engine.options.prefix || "";
-    const clientPath = prefix ? `${prefix}/client.ts` : "/client.ts";
-
-    // 获取 Hono 实例
-    const hono = engine.getHono();
-
-    // 注册路由
-    hono.get(clientPath, async (ctx: Context) => {
-      // 如果代码还未生成，重新生成
-      if (!this.generatedCode) {
-        await this.generateCode();
-      }
-
-      // 返回 TypeScript 代码
-      return ctx.text(this.generatedCode || "", 200, {
-        "Content-Type": "text/typescript; charset=utf-8",
-        "Content-Disposition": `attachment; filename="client.ts"`,
-      });
-    });
-
-    logger.info(`Client code available at ${clientPath}`);
-  }
-
-  /**
-   * 生成客户端代码
-   */
-  private async generateCode(): Promise<void> {
-    try {
-      // 获取模块元数据映射函数
-      const getModuleMetadata = (moduleClass: any) => {
-        const modules = this.engine.getModules();
-        const moduleMetadata = modules.find((m) => m.clazz === moduleClass);
-        return moduleMetadata
-          ? { name: moduleMetadata.name }
-          : undefined;
-      };
-
-      // 将 handlers 转换为 ModuleInfo 格式
-      const modules = convertHandlersToModuleInfoWithMetadata(
-        this.actionHandlers,
-        getModuleMetadata
-      );
-
-      // 生成代码
-      this.generatedCode = await generateClientCode(modules);
-
-      logger.debug(
-        `Generated client code for ${Object.keys(modules).length} module(s)`
-      );
-
-      // 如果设置了保存路径，保存代码到文件
-      if (this.clientSavePath && this.generatedCode) {
-        await this.saveCodeToFile(this.clientSavePath, this.generatedCode);
-      }
-    } catch (error) {
-      logger.error("Failed to generate client code", error);
-      this.generatedCode = "// Error: Failed to generate client code";
-    }
-  }
-
-  /**
-   * 保存代码到文件
-   */
-  private async saveCodeToFile(path: string, code: string): Promise<void> {
-    try {
-      // 确保目录存在
-      const dir = dirname(path);
-      await fs.mkdir(dir, { recursive: true });
-
-      // 写入文件
-      await fs.writeFile(path, code, "utf-8");
-      logger.info(`Client code saved to ${path}`);
-    } catch (error) {
-      logger.error(`Failed to save client code to ${path}`, error);
-      // 不抛出错误，避免影响主流程
-    }
-  }
-}
-

package/src/plugins/client-code/types.ts

@@ -1,52 +0,0 @@
-import { z } from "zod";
-
-/**
- * Action 信息（用于生成客户端代码）
- */
-export interface ActionInfo {
-  /**
-   * 动作描述
-   */
-  description?: string;
-
-  /**
-   * 参数校验 Schema（使用 zod）
-   */
-  params: z.ZodTypeAny[];
-
-  /**
-   * 返回值校验 Schema（使用 zod）
-   */
-  returns?: z.ZodTypeAny;
-
-  /**
-   * 是否流式返回（默认 false）
-   */
-  stream?: boolean;
-
-  /**
-   * 是否幂等（默认 false）
-   */
-  idempotence?: boolean;
-
-  /**
-   * 参数名称数组（从方法定义中提取）
-   */
-  paramNames?: string[];
-}
-
-/**
- * 模块信息（用于生成客户端代码）
- */
-export interface ModuleInfo {
-  /**
-   * 模块名称
-   */
-  name: string;
-
-  /**
-   * 模块的所有 actions
-   */
-  actions: Record<string, ActionInfo>;
-}
-

package/src/plugins/client-code/utils.ts

@@ -1,164 +0,0 @@
-import { HandlerMetadata } from "../../core/types";
-import { ActionOptions } from "../action/types";
-import { ModuleInfo, ActionInfo } from "./types";
-
-/**
- * 从函数中提取参数名称
- * @param func 函数对象
- * @returns 参数名称数组
- */
-function extractParamNames(func: Function): string[] {
-  if (!func || typeof func !== "function") {
-    return [];
-  }
-
-  try {
-    // 获取函数的字符串表示
-    const funcStr = func.toString();
-
-    // 匹配函数参数部分
-    // 支持以下格式：
-    // function name(arg1, arg2) { ... }
-    // (arg1, arg2) => { ... }
-    // async function name(arg1, arg2) { ... }
-    // async (arg1, arg2) => { ... }
-    const match = funcStr.match(
-      /(?:async\s+)?(?:function\s+\w*\s*)?\(([^)]*)\)|(?:async\s+)?\(([^)]*)\)\s*=>/
-    );
-
-    if (!match) {
-      return [];
-    }
-
-    // 获取参数部分（可能是 match[1] 或 match[2]）
-    const paramsStr = match[1] || match[2] || "";
-
-    if (!paramsStr.trim()) {
-      return [];
-    }
-
-    // 分割参数并清理
-    return paramsStr
-      .split(",")
-      .map((param) => {
-        // 移除注释、默认值、类型注解等
-        // 例如: "arg1: string = 'default'" -> "arg1"
-        // 例如: "arg2 /* comment */" -> "arg2"
-        return param
-          .replace(/\/\*.*?\*\//g, "") // 移除块注释
-          .replace(/\/\/.*$/g, "") // 移除行注释
-          .replace(/:\s*[^=,]+/g, "") // 移除类型注解
-          .replace(/\s*=\s*[^,]+/g, "") // 移除默认值
-          .trim();
-      })
-      .filter((name) => name.length > 0);
-  } catch (error) {
-    // 如果解析失败，返回空数组
-    return [];
-  }
-}
-
-/**
- * 将 HandlerMetadata 数组转换为 ModuleInfo 格式
- * @param handlers Action handlers
- * @returns 模块信息映射
- */
-export function convertHandlersToModuleInfo(
-  handlers: HandlerMetadata[]
-): Record<string, ModuleInfo> {
-  const modules: Record<string, ModuleInfo> = {};
-
-  // 筛选出所有 type="action" 的 handlers
-  const actionHandlers = handlers.filter(
-    (handler) => handler.type === "action"
-  );
-
-  for (const handler of actionHandlers) {
-    const actionOptions = handler.options as ActionOptions;
-    const moduleClass = handler.module;
-    const methodName = handler.methodName;
-
-    // 获取模块名称（从模块元数据中获取，这里需要从引擎获取）
-    // 暂时使用类名作为模块名（后续会从引擎获取真实模块名）
-    const moduleName = moduleClass.name.toLowerCase().replace(/service$/, "");
-
-    // 初始化模块信息
-    if (!modules[moduleName]) {
-      modules[moduleName] = {
-        name: moduleName,
-        actions: {},
-      };
-    }
-
-    // 解析方法参数名称
-    const paramNames = extractParamNames(handler.method);
-
-    // 添加 action 信息
-    modules[moduleName].actions[methodName] = {
-      description: actionOptions.description,
-      params: actionOptions.params || [],
-      returns: actionOptions.returns,
-      stream: actionOptions.stream || false,
-      idempotence: actionOptions.idempotence || false,
-      paramNames,
-    };
-  }
-
-  return modules;
-}
-
-/**
- * 从引擎获取模块信息并转换为 ModuleInfo 格式
- * @param handlers Action handlers
- * @param getModuleMetadata 获取模块元数据的函数
- * @returns 模块信息映射
- */
-export function convertHandlersToModuleInfoWithMetadata(
-  handlers: HandlerMetadata[],
-  getModuleMetadata: (moduleClass: any) => { name: string } | undefined
-): Record<string, ModuleInfo> {
-  const modules: Record<string, ModuleInfo> = {};
-
-  // 筛选出所有 type="action" 的 handlers
-  const actionHandlers = handlers.filter(
-    (handler) => handler.type === "action"
-  );
-
-  for (const handler of actionHandlers) {
-    const actionOptions = handler.options as ActionOptions;
-    const moduleClass = handler.module;
-    const methodName = handler.methodName;
-
-    // 从引擎获取模块元数据
-    const moduleMetadata = getModuleMetadata(moduleClass);
-    if (!moduleMetadata) {
-      continue; // 跳过没有元数据的模块
-    }
-
-    const moduleName = moduleMetadata.name;
-
-    // 初始化模块信息
-    if (!modules[moduleName]) {
-      modules[moduleName] = {
-        name: moduleName,
-        actions: {},
-      };
-    }
-
-    // 解析方法参数名称
-    const paramNames = extractParamNames(handler.method);
-
-    // 添加 action 信息
-    modules[moduleName].actions[methodName] = {
-      description: actionOptions.description,
-      params: actionOptions.params || [],
-      returns: actionOptions.returns,
-      stream: actionOptions.stream || false,
-      idempotence: actionOptions.idempotence || false,
-      paramNames,
-    };
-  }
-
-  return modules;
-}
-