@mindbase/express-common 1.0.7 → 1.0.9

package/utils/RouteRegistry.ts

@@ -0,0 +1,92 @@
+import { Express, Router } from "express";
+import { ScanResult } from "../types/Index";
+import logger from "./Logger";
+import { routeParser } from "./RouteParser";
+import { docManager } from "./DocManager";
+import path from "path";
+
+/**
+ * 递归提取 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);
+      });
+    }
+
+    // ===== 支持从子目录生成嵌套 URL =====
+    // 例如：d:/packages/auth/routes/auth/user.route.ts → /api/auth/user
+
+    // 正确找到 routes 目录位置
+    const filePathParts = filePath.split(path.sep);
+    const routesIndex = filePathParts.lastIndexOf("routes");
+    if (routesIndex === -1) {
+      throw new Error(`路由文件必须在 routes 目录下: ${filePath}`);
+    }
+    const routesDir = filePathParts.slice(0, routesIndex + 1).join(path.sep);
+
+    // 获取相对于 routes 目录的路径
+    const fileDir = path.dirname(filePath);
+    const relativePath = path.relative(routesDir, fileDir);
+
+    // 构建路径部分
+    let pathParts: string[] = [];
+    if (relativePath && relativePath !== ".") {
+      pathParts = relativePath.split(path.sep).map(p => p.toLowerCase());
+    }
+    // 添加文件名作为最后一部分
+    pathParts.push(lowercaseModuleName);
+
+    const baseRoutePath = `${apiPrefix}/${pathParts.join("/")}`.replace(/\/+/g, "/");
+    // ===== 嵌套 URL 支持结束 =====
+
+    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/TSTypeParser.ts

@@ -0,0 +1,456 @@
+import {
+  Node,
+  SyntaxKind,
+  SourceFile,
+  InterfaceDeclaration,
+  TypeAliasDeclaration,
+  PropertySignature,
+  TypeReferenceNode,
+  ArrayTypeNode,
+  UnionTypeNode,
+  IntersectionTypeNode,
+  LiteralTypeNode,
+  Identifier,
+} from "ts-morph";
+import { FieldValidation, ResponseSchema } from "../types/DocTypes";
+import logger from "./Logger";
+
+/**
+ * 类型引用解析结果
+ */
+interface TypeRef {
+  typeName: string;
+  typeArgs: string[]; // 泛型参数
+}
+
+/**
+ * TypeScript 类型解析器
+ * 从 interface/type 定义中提取字段结构
+ */
+export class TSTypeParser {
+  /**
+   * 解析类型引用字符串
+   * 例如: "ApiResponse<User[]>" -> { typeName: "ApiResponse", typeArgs: ["User[]"] }
+   */
+  public parseTypeRef(typeString: string): TypeRef | null {
+    // 移除花括号内的内容（如果有）
+    typeString = typeString.trim();
+
+    // 匹配泛型: TypeName<Arg1, Arg2>
+    const genericMatch = typeString.match(/^(\w+)<(.+)>$/);
+    if (genericMatch) {
+      const typeName = genericMatch[1];
+      const argsStr = genericMatch[2];
+      // 简单分割泛型参数（不支持嵌套泛型）
+      const typeArgs = argsStr.split(",").map((s) => s.trim());
+      return { typeName, typeArgs };
+    }
+
+    // 简单类型引用
+    if (/^\w+$/.test(typeString)) {
+      return { typeName: typeString, typeArgs: [] };
+    }
+
+    // 数组类型: User[]
+    const arrayMatch = typeString.match(/^(\w+)\[\]$/);
+    if (arrayMatch) {
+      return { typeName: "Array", typeArgs: [arrayMatch[1]] };
+    }
+
+    return null;
+  }
+
+  /**
+   * 解析响应类型
+   * @param sourceFile 源文件
+   * @param typeString 类型字符串如 "ApiResponse<User[]>"
+   * @param imports 导入映射 (类型名 -> 文件路径)
+   */
+  public parseResponseType(
+    sourceFile: SourceFile,
+    typeString: string,
+    imports: Map<string, string>
+  ): ResponseSchema | null {
+    const typeRef = this.parseTypeRef(typeString);
+    if (!typeRef) {
+      logger.debug(`无法解析类型引用: ${typeString}`);
+      return null;
+    }
+
+    // 内置类型处理: ApiResponse<T>
+    if (typeRef.typeName === "ApiResponse") {
+      return this.parseApiResponse(sourceFile, typeRef.typeArgs, imports);
+    }
+
+    // 查找类型定义
+    const typeDecl = this.findTypeDeclaration(sourceFile, typeRef.typeName, imports);
+    if (!typeDecl) {
+      logger.debug(`未找到类型定义: ${typeRef.typeName}`);
+      return null;
+    }
+
+    // 解析字段
+    const fields = this.extractFieldsFromType(typeDecl, typeRef.typeArgs, imports);
+
+    return { fields };
+  }
+
+  /**
+   * 解析 ApiResponse<T> 类型
+   * ApiResponse 是标准的 API 响应包装器，包含 code, data, msg 字段
+   */
+  private parseApiResponse(
+    sourceFile: SourceFile,
+    typeArgs: string[],
+    imports: Map<string, string>
+  ): ResponseSchema {
+    const fields: Record<string, FieldValidation> = {
+      code: { type: "number", required: true },
+      msg: { type: "string", required: true },
+    };
+
+    // 解析 data 字段的类型
+    if (typeArgs.length > 0) {
+      const dataType = typeArgs[0];
+      const dataField = this.parseDataType(sourceFile, dataType, imports);
+      fields.data = dataField;
+    } else {
+      fields.data = { type: "any", required: true };
+    }
+
+    return { fields };
+  }
+
+  /**
+   * 解析 data 字段的类型
+   */
+  private parseDataType(
+    sourceFile: SourceFile,
+    typeString: string,
+    imports: Map<string, string>
+  ): FieldValidation {
+    // 基础类型
+    if (typeString === "string") {
+      return { type: "string", required: true };
+    } else if (typeString === "number") {
+      return { type: "number", required: true };
+    } else if (typeString === "boolean") {
+      return { type: "boolean", required: true };
+    } else if (typeString === "any") {
+      return { type: "any", required: true };
+    }
+
+    // 数组类型: User[]
+    const arrayMatch = typeString.match(/^(\w+)\[\]$/);
+    if (arrayMatch) {
+      const elementType = arrayMatch[1];
+      const elementField = this.parseDataType(sourceFile, elementType, imports);
+      return {
+        type: "array",
+        required: true,
+        items: elementField,
+      };
+    }
+
+    // 类型引用: LoginResult
+    const typeDecl = this.findTypeDeclaration(sourceFile, typeString, imports);
+    if (typeDecl) {
+      const fields = this.extractFieldsFromType(typeDecl, [], imports);
+      return {
+        type: "object",
+        required: true,
+        properties: fields,
+      };
+    }
+
+    // 默认返回 any
+    return { type: "any", required: true };
+  }
+
+  /**
+   * 查找类型声明
+   */
+  private findTypeDeclaration(
+    sourceFile: SourceFile,
+    typeName: string,
+    imports: Map<string, string>
+  ): InterfaceDeclaration | TypeAliasDeclaration | null {
+    // 先在当前文件中查找
+    const interfaceDecl = sourceFile.getInterface(typeName);
+    if (interfaceDecl) return interfaceDecl;
+
+    const typeAlias = sourceFile.getTypeAlias(typeName);
+    if (typeAlias) return typeAlias;
+
+    // 在导入的文件中查找
+    const importPath = imports.get(typeName);
+    if (importPath) {
+      try {
+        const importedFile = sourceFile.getProject().addSourceFileAtPath(importPath);
+
+        const importedInterface = importedFile.getInterface(typeName);
+        if (importedInterface) return importedInterface;
+
+        const importedTypeAlias = importedFile.getTypeAlias(typeName);
+        if (importedTypeAlias) return importedTypeAlias;
+      } catch (error) {
+        logger.warn(`无法加载导入文件: ${importPath}`);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 从类型声明中提取字段
+   */
+  private extractFieldsFromType(
+    typeDecl: InterfaceDeclaration | TypeAliasDeclaration,
+    typeArgs: string[],
+    imports: Map<string, string>
+  ): Record<string, FieldValidation> {
+    const fields: Record<string, FieldValidation> = {};
+
+    // 获取类型节点
+    let typeNode: Node | undefined;
+
+    if (Node.isInterfaceDeclaration(typeDecl)) {
+      // 接口: 直接遍历属性
+      for (const prop of typeDecl.getProperties()) {
+        const fieldName = prop.getName();
+        const fieldType = prop.getType();
+        fields[fieldName] = this.parsePropertyType(prop, typeArgs, imports);
+      }
+      return fields;
+    } else if (Node.isTypeAliasDeclaration(typeDecl)) {
+      typeNode = typeDecl.getTypeNode();
+    }
+
+    if (!typeNode) return fields;
+
+    // 处理类型别名 - 使用 getKind() 检查节点类型
+    if (typeNode.getKind() === SyntaxKind.TypeReference) {
+      // 如果是类型引用，可能需要展开
+      return this.extractFieldsFromTypeReference(typeNode as TypeReferenceNode, typeArgs, imports);
+    } else if (typeNode.getKind() === SyntaxKind.IntersectionType) {
+      // 交叉类型: 合并所有类型的字段
+      for (const child of (typeNode as IntersectionTypeNode).getTypeNodes()) {
+        const childFields = this.extractFieldsFromTypeNode(child, typeArgs, imports);
+        Object.assign(fields, childFields);
+      }
+    } else if (typeNode.getKind() === SyntaxKind.UnionType) {
+      // 联合类型: 取第一个类型的字段（简化处理）
+      const firstType = (typeNode as UnionTypeNode).getTypeNodes()[0];
+      if (firstType) {
+        return this.extractFieldsFromTypeNode(firstType, typeArgs, imports);
+      }
+    } else {
+      return this.extractFieldsFromTypeNode(typeNode, typeArgs, imports);
+    }
+
+    return fields;
+  }
+
+  /**
+   * 从类型节点提取字段
+   */
+  private extractFieldsFromTypeNode(
+    typeNode: Node,
+    typeArgs: string[],
+    imports: Map<string, string>
+  ): Record<string, FieldValidation> {
+    const fields: Record<string, FieldValidation> = {};
+
+    if (typeNode.getKind() === SyntaxKind.TypeReference) {
+      return this.extractFieldsFromTypeReference(typeNode as TypeReferenceNode, typeArgs, imports);
+    } else if (typeNode.getKind() === SyntaxKind.IntersectionType) {
+      for (const child of (typeNode as IntersectionTypeNode).getTypeNodes()) {
+        const childFields = this.extractFieldsFromTypeNode(child, typeArgs, imports);
+        Object.assign(fields, childFields);
+      }
+    }
+
+    return fields;
+  }
+
+  /**
+   * 从类型引用提取字段
+   */
+  private extractFieldsFromTypeReference(
+    typeRefNode: TypeReferenceNode,
+    typeArgs: string[],
+    imports: Map<string, string>
+  ): Record<string, FieldValidation> {
+    const fields: Record<string, FieldValidation> = {};
+    const typeName = typeRefNode.getTypeName().getText();
+
+    // 特殊处理泛型参数
+    if (typeName === "Array" || typeName === "ReadonlyArray") {
+      // 数组类型，返回 items 信息
+      const typeArgsNodes = typeRefNode.getTypeArguments();
+      if (typeArgsNodes.length > 0) {
+        const elementType = typeArgsNodes[0];
+        fields["[]"] = {
+          type: "array",
+          required: true,
+          items: this.parseTypeNodeToFieldValidation(elementType, typeArgs, imports),
+        };
+      }
+      return fields;
+    }
+
+    // 处理 Promise<T> - 提取 T
+    if (typeName === "Promise") {
+      const typeArgsNodes = typeRefNode.getTypeArguments();
+      if (typeArgsNodes.length > 0) {
+        return this.extractFieldsFromTypeNode(typeArgsNodes[0], typeArgs, imports);
+      }
+    }
+
+    // 处理泛型参数 T, K 等
+    if (typeArgs.includes(typeName) && typeArgs.length > 0) {
+      // 使用实际类型参数
+      const actualType = typeArgs[0]; // 简化处理，取第一个
+      // 这里可以递归解析实际类型
+    }
+
+    // 解析类型定义
+    const sourceFile = typeRefNode.getSourceFile();
+    const typeDecl = this.findTypeDeclarationInFile(sourceFile, typeName);
+
+    if (typeDecl) {
+      return this.extractFieldsFromType(typeDecl, typeArgs, imports);
+    }
+
+    return fields;
+  }
+
+  /**
+   * 在文件中查找类型声明
+   */
+  private findTypeDeclarationInFile(
+    sourceFile: SourceFile,
+    typeName: string
+  ): InterfaceDeclaration | TypeAliasDeclaration | null {
+    const interfaceDecl = sourceFile.getInterface(typeName);
+    if (interfaceDecl) return interfaceDecl;
+
+    const typeAlias = sourceFile.getTypeAlias(typeName);
+    if (typeAlias) return typeAlias;
+
+    return null;
+  }
+
+  /**
+   * 解析属性类型
+   */
+  private parsePropertyType(
+    prop: PropertySignature,
+    typeArgs: string[],
+    imports: Map<string, string>
+  ): FieldValidation {
+    const type = prop.getType();
+    const isOptional = prop.hasQuestionToken();
+
+    // 获取类型文本
+    const typeText = type.getText();
+
+    // 基础类型判断
+    if (type.isString()) {
+      return { type: "string", required: !isOptional };
+    } else if (type.isNumber()) {
+      return { type: "number", required: !isOptional };
+    } else if (type.isBoolean()) {
+      return { type: "boolean", required: !isOptional };
+    } else if (type.isArray()) {
+      const elementType = type.getArrayElementType();
+      let items: FieldValidation | undefined;
+      if (elementType) {
+        items = {
+          type: this.mapTypeToString(elementType),
+          required: !elementType.isUndefined() && !elementType.isNull(),
+        };
+      }
+      return { type: "array", required: !isOptional, items };
+    } else if (type.isObject()) {
+      // 尝试获取对象属性
+      const properties = type.getProperties();
+      if (properties.length > 0) {
+        const props: Record<string, FieldValidation> = {};
+        for (const prop of properties) {
+          const propName = prop.getName();
+          const propType = prop.getTypeAtLocation(prop.getValueDeclaration() || prop.getDeclarations()[0]);
+          props[propName] = {
+            type: this.mapTypeToString(propType),
+            required: !prop.isOptional(),
+          };
+        }
+        return { type: "object", required: !isOptional, properties: props };
+      }
+      return { type: "object", required: !isOptional };
+    } else if (type.isNull()) {
+      return { type: "any", required: false, nullable: true };
+    } else if (type.isUndefined()) {
+      return { type: "any", required: false, optional: true };
+    } else if (type.isAny()) {
+      return { type: "any", required: !isOptional };
+    }
+
+    // 其他类型，使用类型文本
+    return { type: "any", required: !isOptional };
+  }
+
+  /**
+   * 将类型映射为字符串
+   */
+  private mapTypeToString(type: any): FieldValidation["type"] {
+    if (type.isString()) return "string";
+    if (type.isNumber()) return "number";
+    if (type.isBoolean()) return "boolean";
+    if (type.isArray()) return "array";
+    if (type.isObject()) return "object";
+    if (type.isDate()) return "date";
+    return "any";
+  }
+
+  /**
+   * 从类型节点创建 FieldValidation
+   */
+  private parseTypeNodeToFieldValidation(
+    typeNode: Node,
+    typeArgs: string[],
+    imports: Map<string, string>
+  ): FieldValidation {
+    if (Node.isStringKeyword(typeNode)) {
+      return { type: "string", required: true };
+    } else if (Node.isNumberKeyword(typeNode)) {
+      return { type: "number", required: true };
+    } else if (Node.isBooleanKeyword(typeNode)) {
+      return { type: "boolean", required: true };
+    } else if (Node.isArrayTypeNode(typeNode)) {
+      const elementType = (typeNode as ArrayTypeNode).getElementTypeNode();
+      return {
+        type: "array",
+        required: true,
+        items: this.parseTypeNodeToFieldValidation(elementType, typeArgs, imports),
+      };
+    } else if (typeNode.getKind() === SyntaxKind.TypeReference) {
+      const refNode = typeNode as TypeReferenceNode;
+      const typeName = refNode.getTypeName().getText();
+      const sourceFile = refNode.getSourceFile();
+      const typeDecl = this.findTypeDeclarationInFile(sourceFile, typeName);
+
+      if (typeDecl) {
+        const fields = this.extractFieldsFromType(typeDecl, typeArgs, imports);
+        return { type: "object", required: true, properties: fields };
+      }
+
+      return { type: "any", required: true };
+    }
+
+    return { type: "any", required: true };
+  }
+}
+
+// 导出单例实例
+export const tsTypeParser = new TSTypeParser();

package/utils/Validate.ts

@@ -0,0 +1,25 @@
+import { Request, Response, NextFunction } from "express";
+import { AnyZodObject, ZodError, ZodSchema } from "zod";
+
+/**
+ * 验证位置类型
+ */
+export type ValidationTarget = "body" | "query" | "params";
+
+/**
+ * Zod 验证中间件
+ * @param schema Zod Schema
+ * @param target 验证目标 (默认 body)
+ */
+export const validate = (schema: ZodSchema, target: ValidationTarget = "body") => {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await schema.parseAsync(req[target]);
+      // 注意: req.query 和 req.params 是只读的，无法赋值
+      // 只有 req.body 可以赋值，但通常 parse 验证后类型转换已生效
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+};