@mindbase/express-common 1.0.0 → 1.0.1

package/utils/RouteParser.ts

@@ -1,408 +0,0 @@
-import {
-  Project,
-  SyntaxKind,
-  Node,
-  SourceFile,
-  StringLiteral,
-  ModuleKind,
-  ScriptTarget,
-  JSDoc,
-} from "ts-morph";
-import * as path from "path";
-import { RouteInfo, RequestSchema, ResponseSchema } from "../types/DocTypes";
-import logger from "./Logger";
-import { ZodSchemaParser } from "./ZodSchemaParser";
-import { TSTypeParser } from "./TSTypeParser";
-
-/**
- * 路由解析器
- * 使用 ts-morph 解析路由文件，提取路由信息
- */
-export class RouteParser {
-  private project: Project;
-  private schemaParser: ZodSchemaParser;
-  private tsTypeParser: TSTypeParser;
-
-  constructor() {
-    this.project = new Project({
-      compilerOptions: {
-        module: ModuleKind.CommonJS,
-        target: ScriptTarget.ES2018,
-        allowJs: true,
-      },
-    });
-    this.schemaParser = new ZodSchemaParser();
-    this.tsTypeParser = new TSTypeParser();
-  }
-
-  /**
-   * 解析单个路由文件
-   * @param filePath 路由文件路径
-   * @returns 路由信息数组
-   */
-  public parseRouteFile(filePath: string): RouteInfo[] {
-    try {
-      const sourceFile = this.project.addSourceFileAtPath(filePath);
-      const routes: RouteInfo[] = [];
-
-      // 获取所有导入的 schema 文件映射
-      const schemaFiles = this.getImportedSchemaFiles(sourceFile, filePath);
-
-      // 获取所有类型导入映射（用于响应类型解析）
-      const typeImports = this.getTypeImports(sourceFile, filePath);
-
-      // 查找所有路由调用
-      sourceFile.forEachDescendant((node) => {
-        const callExpr = node as any;
-        if (callExpr.isKind && callExpr.isKind(SyntaxKind.CallExpression) && callExpr.getExpression && callExpr.getExpression().isKind(SyntaxKind.PropertyAccessExpression)) {
-          const propAccess = callExpr.getExpression();
-          const object = propAccess.getExpression && propAccess.getExpression().getText();
-          const method = propAccess.getName && propAccess.getName();
-
-          // 检查是否是 router 的 HTTP 方法调用
-          if (object === "router" && ["get", "post", "put", "delete", "patch"].includes(method)) {
-            // 提取路由路径
-            const args = callExpr.getArguments && callExpr.getArguments();
-            if (args && args.length > 0) {
-              const pathArg = args[0];
-              if (pathArg.isKind && pathArg.isKind(SyntaxKind.StringLiteral)) {
-                const routePath = pathArg.getText && pathArg.getText().replace(/['"]/g, "");
-
-                // 提取 JSDoc 注释
-                const jsDoc = callExpr.getPreviousSiblingIfKind && callExpr.getPreviousSiblingIfKind(SyntaxKind.JSDocComment);
-                let summary = "";
-                let description = "";
-                let responseSchema: ResponseSchema | undefined;
-
-                if (jsDoc) {
-                  const commentText = jsDoc.getCommentText && jsDoc.getCommentText();
-                  if (commentText) {
-                    const lines = commentText.split("\n").map((line) => line.trim());
-                    summary = lines[0] || "";
-                    description = lines.slice(1).join("\n").trim() || summary;
-                  }
-
-                  // 提取 @returns 标签中的响应类型
-                  responseSchema = this.extractResponseSchema(jsDoc, sourceFile, typeImports);
-                }
-
-                // 提取中间件信息
-                const middlewares: string[] = [];
-                for (let i = 1; i < args.length - 1; i++) {
-                  const arg = args[i];
-                  if (arg.isKind(SyntaxKind.CallExpression)) {
-                    const mwCallExpr = arg as any;
-                    const expr = mwCallExpr.getExpression();
-                    if (expr.isKind(SyntaxKind.Identifier)) {
-                      middlewares.push(expr.getText());
-                    } else if (expr.isKind(SyntaxKind.PropertyAccessExpression)) {
-                      middlewares.push(expr.getText());
-                    }
-                  }
-                }
-
-                // 提取请求参数 schema (通过 validate 中间件)
-                const requestSchema = this.extractRequestSchema(args, schemaFiles);
-
-                const routeInfo: RouteInfo = {
-                  module: path.basename(path.dirname(filePath)).toLowerCase(),
-                  method: method.toUpperCase(),
-                  path: routePath,
-                  fullPath: "", // 完整路径会在注册时填充
-                  summary,
-                  description,
-                  requestSchema,
-                  responseSchema,
-                  middlewares,
-                  filePath,
-                };
-
-                routes.push(routeInfo);
-              }
-            }
-          }
-        }
-      });
-
-      return routes;
-    } catch (error) {
-      logger.error(`解析路由文件失败: ${filePath}`, error);
-      return [];
-    }
-  }
-
-  /**
-   * 获取导入的 schema 文件映射
-   * @returns Map<变量名, 文件绝对路径>
-   */
-  private getImportedSchemaFiles(
-    sourceFile: SourceFile,
-    currentFilePath: string
-  ): Map<string, string> {
-    const schemaFiles = new Map<string, string>();
-
-    for (const importDecl of sourceFile.getImportDeclarations()) {
-      const source = importDecl.getModuleSpecifierValue();
-
-      // 检查是否是 schema 相关的导入
-      if (source.includes(".schema") || source.includes("/zod/") || source.includes("\\zod\\")) {
-        // 解析相对路径为绝对路径
-        const absolutePath = this.resolveImportPath(
-          currentFilePath,
-          source
-        );
-        if (absolutePath) {
-          // 记录导入的变量名 -> 文件路径映射
-          for (const specifier of importDecl.getNamedImports()) {
-            logger.debug(`发现 schema 导入: ${specifier.getName()} -> ${absolutePath}`);
-            schemaFiles.set(specifier.getName(), absolutePath);
-          }
-        } else {
-          logger.debug(`无法解析 schema 导入路径: ${source}`);
-        }
-      }
-    }
-
-    return schemaFiles;
-  }
-
-  /**
-   * 获取所有类型导入映射（用于响应类型解析）
-   * @returns Map<类型名, 文件绝对路径>
-   */
-  private getTypeImports(
-    sourceFile: SourceFile,
-    currentFilePath: string
-  ): Map<string, string> {
-    const typeImports = new Map<string, string>();
-
-    for (const importDecl of sourceFile.getImportDeclarations()) {
-      const source = importDecl.getModuleSpecifierValue();
-
-      // 解析相对路径为绝对路径
-      const absolutePath = this.resolveImportPath(currentFilePath, source);
-      if (absolutePath) {
-        // 记录所有命名导入
-        for (const specifier of importDecl.getNamedImports()) {
-          typeImports.set(specifier.getName(), absolutePath);
-        }
-      }
-    }
-
-    return typeImports;
-  }
-
-  /**
-   * 从 JSDoc 中提取响应 Schema
-   */
-  private extractResponseSchema(
-    jsDoc: JSDoc,
-    sourceFile: SourceFile,
-    typeImports: Map<string, string>
-  ): ResponseSchema | undefined {
-    // 获取所有 JSDoc 标签
-    const tags = jsDoc.getTags();
-
-    for (const tag of tags) {
-      const tagName = tag.getTagName();
-
-      // 检查 @returns 或 @return 标签
-      if (tagName === "returns" || tagName === "return") {
-        // 获取标签的完整文本
-        const tagText = tag.getText?.() || "";
-        logger.debug(`@returns 标签文本: ${tagText}`);
-
-        // 尝试从标签文本中提取类型 {TypeName}
-        const typeMatch = tagText.match(/@\s*returns?\s*\{([^}]+)\}/i);
-        if (typeMatch) {
-          const typeString = typeMatch[1].trim();
-          logger.debug(`从标签文本提取类型: ${typeString}`);
-
-          const responseSchema = this.tsTypeParser.parseResponseType(
-            sourceFile,
-            typeString,
-            typeImports
-          );
-
-          if (responseSchema) {
-            return responseSchema;
-          }
-        }
-
-        // 尝试从注释中提取类型
-        const comment = tag.getCommentText?.();
-        if (comment) {
-          const commentMatch = comment.match(/^\{([^}]+)\}/);
-          if (commentMatch) {
-            const typeString = commentMatch[1].trim();
-            logger.debug(`从注释提取类型: ${typeString}`);
-
-            const responseSchema = this.tsTypeParser.parseResponseType(
-              sourceFile,
-              typeString,
-              typeImports
-            );
-
-            if (responseSchema) {
-              return responseSchema;
-            }
-          }
-        }
-
-        // 尝试使用 ts-morph 的类型表达式
-        const typeExpression = (tag as any).getTypeExpression?.();
-        if (typeExpression) {
-          const typeNode = typeExpression.getType?.();
-          if (typeNode) {
-            const typeString = typeNode.getText();
-            logger.debug(`从类型表达式提取类型: ${typeString}`);
-
-            if (typeString && typeString !== "any") {
-              const responseSchema = this.tsTypeParser.parseResponseType(
-                sourceFile,
-                typeString,
-                typeImports
-              );
-
-              if (responseSchema) {
-                return responseSchema;
-              }
-            }
-          }
-        }
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * 解析导入路径为绝对路径
-   */
-  private resolveImportPath(
-    currentFilePath: string,
-    importPath: string
-  ): string | null {
-    try {
-      // 处理相对路径
-      if (importPath.startsWith(".")) {
-        const currentDir = path.dirname(currentFilePath);
-        const absolutePath = path.resolve(currentDir, importPath);
-
-        // 尝试添加 .ts 扩展名
-        const tsPath = absolutePath.endsWith(".ts")
-          ? absolutePath
-          : `${absolutePath}.ts`;
-        return tsPath;
-      }
-
-      // 非相对路径暂不处理
-      return null;
-    } catch (error) {
-      logger.warn(`解析导入路径失败: ${importPath}`);
-      return null;
-    }
-  }
-
-  /**
-   * 提取请求 Schema
-   */
-  private extractRequestSchema(
-    args: any[],
-    schemaFiles: Map<string, string>
-  ): RequestSchema | undefined {
-    for (const arg of args) {
-      // 路由参数可能是 validate(...) 或 validate(...) as any
-      // 需要先处理 as any 类型断言
-      let targetArg = arg;
-      if (
-        arg.isKind &&
-        arg.isKind(SyntaxKind.AsExpression)
-      ) {
-        targetArg = arg.getExpression();
-      }
-
-      // 检查是否是 validate 调用
-      if (
-        targetArg.isKind &&
-        targetArg.isKind(SyntaxKind.CallExpression) &&
-        targetArg.getExpression &&
-        targetArg.getExpression().isKind &&
-        targetArg.getExpression().isKind(SyntaxKind.Identifier) &&
-        targetArg.getExpression().getText() === "validate"
-      ) {
-        const validateArgs = targetArg.getArguments();
-        if (validateArgs.length === 0) continue;
-
-        // 获取 schema 变量名
-        const schemaArg = validateArgs[0];
-        let schemaName: string;
-
-        // 处理 schema 参数中的 as any 类型断言
-        if (
-          schemaArg.isKind &&
-          schemaArg.isKind(SyntaxKind.AsExpression)
-        ) {
-          schemaName = schemaArg.getExpression().getText();
-        } else {
-          schemaName = schemaArg.getText();
-        }
-
-        // 获取 target 参数
-        let target: "body" | "query" | "params" = "body";
-        if (validateArgs.length > 1) {
-          const targetArgParam = validateArgs[1];
-          if (
-            targetArgParam.isKind &&
-            targetArgParam.isKind(SyntaxKind.StringLiteral)
-          ) {
-            target = (targetArgParam as StringLiteral).getLiteralValue() as
-              | "body"
-              | "query"
-              | "params";
-          }
-        }
-
-        // 解析 schema 文件
-        const schemaFilePath = schemaFiles.get(schemaName);
-        if (schemaFilePath) {
-          try {
-            const schemaSourceFile =
-              this.project.addSourceFileAtPath(schemaFilePath);
-            const fields = this.schemaParser.parseSchemaVariable(
-              schemaSourceFile,
-              schemaName
-            );
-
-            if (fields) {
-              return { target, fields };
-            }
-          } catch (error) {
-            logger.warn(`解析 schema 文件失败: ${schemaFilePath}`, error);
-          }
-        } else {
-          logger.debug(`未找到 schema 文件映射: ${schemaName}`);
-        }
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * 解析多个路由文件
-   * @param filePaths 路由文件路径数组
-   * @returns 路由信息数组
-   */
-  public parseRouteFiles(filePaths: string[]): RouteInfo[] {
-    const allRoutes: RouteInfo[] = [];
-    for (const filePath of filePaths) {
-      const routes = this.parseRouteFile(filePath);
-      allRoutes.push(...routes);
-    }
-    return allRoutes;
-  }
-}
-
-// 导出单例实例
-export const routeParser = new RouteParser();

package/utils/RouteRegistry.ts

@@ -1,66 +0,0 @@
-import { Express, Router } from "express";
-import { ScanResult } from "../types/Index";
-import logger from "./Logger";
-import { routeParser } from "./RouteParser";
-import { docManager } from "./DocManager";
-
-/**
- * 递归提取 Router 中注册的所有路由路径
- */
-function getRoutes(router: any, prefix: string = ""): { path: string; method: string }[] {
-  const routes: { path: string; method: string }[] = [];
-
-  if (router && router.stack) {
-    router.stack.forEach((layer: any) => {
-      if (layer.route) {
-        // 处理直接定义的路由 (如 router.get('/hello'))
-        const path = (prefix + layer.route.path).replace(/\/+/g, "/");
-        const methods = Object.keys(layer.route.methods).map((m) => m.toUpperCase());
-        methods.forEach((method) => {
-          routes.push({ path, method });
-        });
-      } else if (layer.name === "router" && layer.handle && layer.handle.stack) {
-        // 处理嵌套的 Router (如 router.use('/sub', subRouter))
-        const newPrefix = (prefix + (layer.regexp.source.replace("^\\/", "").replace("\\/?(?=\\/|$)", "") || "")).replace(/\/+/g, "/");
-        routes.push(...getRoutes(layer.handle, newPrefix));
-      }
-    });
-  }
-
-  return routes;
-}
-
-export async function registerRoute(app: Express, config: ScanResult, apiPrefix: string = "/api"): Promise<void> {
-  const { fileName, defaultExport: handler, filePath, cacheHit } = config;
-
-  try {
-    const lowercaseModuleName = fileName.toLowerCase();
-
-    // 缓存未命中时才解析和保存文档
-    if (!cacheHit) {
-      const routes = routeParser.parseRouteFile(filePath);
-      routes.forEach((route) => {
-        docManager.saveRoute(route, apiPrefix, lowercaseModuleName);
-      });
-    }
-
-    const baseRoutePath = `${apiPrefix}/${lowercaseModuleName}`.replace(/\/+/g, "/");
-    app.use(baseRoutePath, handler);
-
-    // 提取并打印所有子路由
-    const subRoutes = getRoutes(handler);
-    if (subRoutes.length > 0) {
-      logger.startup("路由", `${baseRoutePath} (${subRoutes.length} 个端点)`);
-      subRoutes.forEach((route) => {
-        const fullPath = `${baseRoutePath}${route.path}`.replace(/\/+/g, "/");
-        // Method 填充到 6 字符宽度，保证 path 对齐
-        const method = route.method.padEnd(6, " ");
-        logger.startup(`  └─ ${method} ${fullPath}`);
-      });
-    } else {
-      logger.startup("路由", `${baseRoutePath} (无端点)`);
-    }
-  } catch (error) {
-    logger.error(`注册路由失败[${fileName.toLowerCase()}]: ${error}`);
-  }
-}

package/utils/SchemaMigrate.ts

@@ -1,73 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { setBaseDir, scan } from "../feature/scanner/FileScanner";
-import { initDatabase } from "./InitDatabase";
-import { executeDatabaseMigration } from "./DatabaseMigration";
-import logger from "./Logger";
-
-/**
- * 处理数据库迁移（Schema 同步 + Drizzle Push）
- * 这是 migrate 模式的核心逻辑
- */
-export async function handleSchemaMigrate() {
-  logger.startup("迁移", "🚀 开始数据库迁移流程...");
-
-  try {
-    // 1. 执行扫描并收集 Schema 文件路径
-    try {
-      setBaseDir(process.cwd());
-      const scannedResults = await scan(true);
-
-      logger.startup("迁移", `扫描完成，发现 ${scannedResults.length} 个文件`);
-
-      const schemaFiles = scannedResults.filter((item) => item.type === "schema").map((item) => item.filePath);
-
-      logger.startup("迁移", `提取到 ${schemaFiles.length} 个 Schema 文件路径`);
-
-      // 2. 写入 .drizzle-schemas.json 清单文件（供 drizzle-kit 使用）
-      const schemaListPath = path.join(process.cwd(), ".drizzle-schemas.json");
-      try {
-        fs.writeFileSync(schemaListPath, JSON.stringify(schemaFiles, null, 2));
-        logger.startup("迁移", `已生成清单文件：${schemaListPath}`);
-      } catch (e) {
-        throw new Error(`写入清单文件失败：${e instanceof Error ? e.message : String(e)}`);
-      }
-
-      // 3. 动态导入 Schema 文件并加载到内存
-      const schemas: Record<string, any> = {};
-      for (const schemaPath of schemaFiles) {
-        try {
-          const module = await import(schemaPath);
-          Object.assign(schemas, module);
-        } catch (e) {
-          logger.warn(`加载 Schema 文件失败: ${schemaPath}`, e);
-        }
-      }
-
-      logger.startup("迁移", `已加载 ${Object.keys(schemas).length} 个 Schema 定义`);
-
-      // 4. 初始化数据库连接
-      const db = initDatabase({ schemas });
-      logger.startup("迁移", "数据库连接已建立");
-
-      // 5. 执行 drizzle-kit push
-      logger.startup("迁移", "正在执行数据库结构同步...");
-      const success = await executeDatabaseMigration(db, schemas);
-
-      if (success) {
-        logger.startup("迁移", "✅ 数据库迁移完成");
-        process.exit(0);
-      } else {
-        logger.error("❌ 数据库迁移失败");
-        logger.info("💡 提示：请检查数据库连接或手动运行 'npx drizzle-kit push'");
-        process.exit(1);
-      }
-    } catch (e) {
-      throw new Error(`Schema 扫描或数据库迁移失败：${e instanceof Error ? e.message : String(e)}`);
-    }
-  } catch (error) {
-    logger.error("数据库迁移失败：", error);
-    logger.error(`错误：${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
-  }
-}

package/utils/SchemaSync.ts

@@ -1,47 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { setBaseDir, scan } from "../feature/scanner/FileScanner";
-import logger from "./Logger";
-
-/**
- * 处理 Schema 同步逻辑
- * 扫描项目中的所有 Schema 文件并生成 .drizzle-schemas.json 清单
- * @throws 如果 Schema 同步失败
- */
-export async function handleSchemaSync() {
-  logger.info("🚀 检测到同步模式：正在收集 Schema 路径...");
-
-  try {
-    // 1. 执行静默扫描 (onlyPaths = true)
-    try {
-      setBaseDir(process.cwd());
-      const scannedResults = await scan(true);
-
-      logger.startup(`扫描完成，发现 ${scannedResults.length} 个文件`);
-
-      const schemas = scannedResults.filter((item) => item.type === "schema").map((item) => item.filePath);
-
-      logger.startup(`提取到 ${schemas.length} 个 Schema 文件路径`);
-
-      // 2. 写入清单文件
-      const outputPath = path.join(process.cwd(), ".drizzle-schemas.json");
-      try {
-        fs.writeFileSync(outputPath, JSON.stringify(schemas, null, 2));
-        logger.startup(`写入清单文件：${outputPath}`);
-      } catch (e) {
-        throw new Error(`写入清单文件失败：${e instanceof Error ? e.message : String(e)}`);
-      }
-
-      logger.startup(`✅ 已发现 ${schemas.length} 个 Schema，清单已更新至 .drizzle-schemas.json`);
-    } catch (e) {
-      throw new Error(`Schema 扫描失败：${e instanceof Error ? e.message : String(e)}`);
-    }
-
-    // 3. 同步模式下直接退出
-    process.exit(0);
-  } catch (error) {
-    logger.error("Schema 同步失败：", error);
-    logger.error(`错误：${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
-  }
-}