@mindbase/express-common 1.0.7 → 1.0.8

package/utils/RouteParser.ts

@@ -0,0 +1,655 @@
+import {
+  Project,
+  SyntaxKind,
+  Node,
+  SourceFile,
+  StringLiteral,
+  ModuleKind,
+  ScriptTarget,
+  JSDoc,
+} from "ts-morph";
+import * as path from "path";
+import { RouteInfo, RequestSchema, ResponseSchema, FieldValidation } from "../types/DocTypes";
+import logger from "./Logger";
+import { ZodSchemaParser } from "./ZodSchemaParser";
+import { TSTypeParser } from "./TSTypeParser";
+
+/**
+ * apidoc 标签解析结果
+ */
+interface ApiDocTags {
+  params: Array<{
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+    enumValues?: string[];
+  }>;
+  success: Array<{
+    name: string;
+    type: string;
+    description: string;
+    parent?: string;
+  }>;
+}
+
+/**
+ * 路由解析器
+ * 使用 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 requestSchema: RequestSchema | undefined;
+                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;
+                  }
+
+                  // 解析 apidoc 格式的注释标签
+                  try {
+                    const fullCommentText = jsDoc.getFullText?.() || commentText || "";
+                    const apiDocTags = this.parseApiDocTags(fullCommentText);
+
+                    // 从 @apiParam 构建请求 Schema（优先级高于 validate 中间件）
+                    if (apiDocTags.params.length > 0) {
+                      requestSchema = this.buildRequestSchemaFromTags(apiDocTags.params);
+                    }
+
+                    // 从 @apiSuccess 构建响应 Schema
+                    if (apiDocTags.success.length > 0) {
+                      responseSchema = this.buildResponseSchemaFromTags(apiDocTags.success);
+                    }
+                  } catch (error) {
+                    logger.warn(`解析 apidoc 注释失败: ${filePath}:${routePath}`, error);
+                  }
+
+                  // 如果没有 @apiSuccess，尝试提取 @returns 标签（降级方案）
+                  if (!responseSchema) {
+                    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 中间件获取（降级方案）
+                if (!requestSchema) {
+                  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;
+  }
+
+  /**
+   * 解析 apidoc 格式的注释标签
+   * @param commentText JSDoc 注释文本
+   * @returns 解析出的标签信息
+   */
+  private parseApiDocTags(commentText: string): ApiDocTags {
+    const tags: ApiDocTags = { params: [], success: [] };
+
+    // 解析 @apiParam 标签
+    // 格式: @apiParam {type} [name] description
+    const paramRegex = /@apiParam\s+\{([^}]+)\}\s*(?:\[([^\]]+)\]|(\S+))\s*(.*)/g;
+    let match;
+    while ((match = paramRegex.exec(commentText)) !== null) {
+      const [, typeStr, optionalName, requiredName, description] = match;
+      const name = optionalName || requiredName;
+      const required = !optionalName;
+
+      // 解析类型字符串
+      const typeInfo = this.parseParamType(typeStr);
+
+      tags.params.push({
+        name,
+        type: typeInfo.type,
+        description: description.trim(),
+        required,
+        enumValues: typeInfo.enumValues,
+      });
+    }
+
+    // 解析 @apiSuccess 标签
+    // 格式: @apiSuccess {type} field 或 @apiSuccess {type} parent.field
+    const successRegex = /@apiSuccess\s+\{([^}]+)\}\s+([^\s]+)\s*(.*)/g;
+    while ((match = successRegex.exec(commentText)) !== null) {
+      const [, typeStr, fieldPath, description] = match;
+
+      // 解析字段路径 (如 "data.user.id")
+      const parts = fieldPath.split(".");
+      const name = parts[parts.length - 1];
+      const parent = parts.length > 1 ? parts.slice(0, -1).join(".") : undefined;
+
+      // 解析类型字符串
+      const typeInfo = this.parseParamType(typeStr);
+
+      tags.success.push({
+        name,
+        type: typeInfo.type,
+        description: description.trim(),
+        parent,
+      });
+    }
+
+    return tags;
+  }
+
+  /**
+   * 解析 apidoc 类型字符串
+   * @param typeStr 类型字符串，如 "string", "string=", "number[]", {string="a","b"}
+   * @returns 解析后的类型信息
+   */
+  private parseParamType(typeStr: string): {
+    type: FieldValidation["type"];
+    array?: boolean;
+    enumValues?: string[];
+  } {
+    typeStr = typeStr.trim();
+
+    // 处理枚举类型: {string="a","b"}
+    const enumMatch = typeStr.match(/^(\w+)=(.+)$/);
+    if (enumMatch) {
+      const baseType = enumMatch[1];
+      const enumValues = enumMatch[2]
+        .split(",")
+        .map((v) => v.trim().replace(/^["']|["']$/g, ""));
+
+      return {
+        type: this.mapTypeName(baseType),
+        enumValues,
+      };
+    }
+
+    // 处理数组类型: number[]
+    if (typeStr.endsWith("[]")) {
+      const baseType = typeStr.slice(0, -2);
+      return {
+        type: this.mapTypeName(baseType),
+        array: true,
+      };
+    }
+
+    // 处理可空类型: string?
+    if (typeStr.endsWith("?")) {
+      const baseType = typeStr.slice(0, -1);
+      return {
+        type: this.mapTypeName(baseType),
+      };
+    }
+
+    // 基础类型
+    return {
+      type: this.mapTypeName(typeStr),
+    };
+  }
+
+  /**
+   * 映射类型名称到 FieldValidation 类型
+   */
+  private mapTypeName(typeName: string): FieldValidation["type"] {
+    const typeMap: Record<string, FieldValidation["type"]> = {
+      string: "string",
+      number: "number",
+      integer: "number",
+      boolean: "boolean",
+      array: "array",
+      object: "object",
+      file: "file",
+      date: "date",
+    };
+
+    return typeMap[typeName.toLowerCase()] || "any";
+  }
+
+  /**
+   * 从 @apiParam 标签构建请求 Schema
+   */
+  private buildRequestSchemaFromTags(
+    params: ApiDocTags["params"]
+  ): RequestSchema {
+    const fields: Record<string, FieldValidation> = {};
+
+    for (const param of params) {
+      fields[param.name] = {
+        type: param.type as FieldValidation["type"],
+        required: param.required,
+        constraints: param.enumValues
+          ? { custom: [`可选值: ${param.enumValues.join(", ")}`] }
+          : undefined,
+      };
+    }
+
+    return { target: "body", fields };
+  }
+
+  /**
+   * 从 @apiSuccess 标签构建响应 Schema
+   */
+  private buildResponseSchemaFromTags(
+    success: ApiDocTags["success"]
+  ): ResponseSchema {
+    const fields: Record<string, FieldValidation> = {};
+
+    // 先处理所有顶级字段，为嵌套字段做准备
+    for (const field of success) {
+      if (!field.parent && !fields[field.name]) {
+        // 顶级字段，如果是 object 类型，添加 properties 属性
+        if (field.type === "object") {
+          fields[field.name] = {
+            type: "object",
+            required: true,
+            properties: {},
+          };
+        } else {
+          fields[field.name] = {
+            type: field.type as FieldValidation["type"],
+            required: true,
+          };
+        }
+      }
+    }
+
+    // 处理嵌套字段
+    for (const field of success) {
+      if (field.parent) {
+        // 处理嵌套字段 (如 data.user.id)
+        const parts = field.parent.split(".");
+        let current = fields;
+
+        // 创建/获取父级对象链
+        for (let i = 0; i < parts.length; i++) {
+          const part = parts[i];
+          if (!current[part]) {
+            // 如果父级字段不存在，创建它
+            current[part] = {
+              type: "object",
+              required: true,
+              properties: {},
+            };
+          } else if (!current[part].properties) {
+            // 如果父级字段存在但没有 properties（作为顶级字段创建的），添加 properties
+            current[part].properties = {};
+          }
+          // 进入到下一级的 properties
+          current = current[part].properties!;
+        }
+
+        // 添加叶子节点到最内层对象的 properties
+        current[field.name] = {
+          type: field.type as FieldValidation["type"],
+          required: true,
+        };
+      }
+    }
+
+    return { fields };
+  }
+}
+
+// 导出单例实例
+export const routeParser = new RouteParser();