@mindbase/express-common 1.0.7 → 1.0.9

package/types/DocTypes.ts

@@ -0,0 +1,111 @@
+import { Request, Response } from "express";
+
+/**
+ * 标准 API 响应结构
+ */
+export interface ApiResponse<T = any> {
+  code: number;
+  data: T;
+  msg: string;
+}
+
+/**
+ * 字段约束规则
+ */
+export interface FieldConstraints {
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  email?: boolean;
+  url?: boolean;
+  uuid?: boolean;
+  int?: boolean;
+  positive?: boolean;
+  nonnegative?: boolean;
+  custom?: string[];  // 自定义错误消息
+}
+
+/**
+ * 字段验证规则
+ */
+export interface FieldValidation {
+  type: "string" | "number" | "boolean" | "array" | "object" | "date" | "file" | "any";
+  required: boolean;
+  optional?: boolean;
+  nullable?: boolean;
+  defaultValue?: any;
+  constraints?: FieldConstraints;
+  items?: FieldValidation;  // 数组元素类型
+  properties?: Record<string, FieldValidation>;  // 对象属性
+}
+
+/**
+ * 请求 Schema 结构
+ */
+export interface RequestSchema {
+  target: "body" | "query" | "params";
+  fields: Record<string, FieldValidation>;
+}
+
+/**
+ * 响应 Schema 结构
+ */
+export interface ResponseSchema {
+  description?: string;
+  fields: Record<string, FieldValidation>;
+}
+
+/**
+ * 路由文档配置
+ */
+export interface RouteDocConfig<TRequest = any, TResponse = any> {
+  summary?: string;
+  description?: string;
+  request?: TRequest;
+  response?: TResponse;
+}
+
+/**
+ * 路由信息接口
+ */
+export interface RouteInfo {
+  id?: number;
+  module: string;
+  method: string;
+  path: string;
+  fullPath: string;
+  summary: string;
+  description: string;
+  requestSchema?: RequestSchema;
+  responseSchema?: ResponseSchema;
+  middlewares?: string[];
+  filePath: string;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+/**
+ * 标记路由文档配置
+ */
+export function RouteDoc<TRequest = any, TResponse = any>(config: RouteDocConfig<TRequest, TResponse>) {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    // 运行时不做任何处理，仅用于类型定义和静态分析
+  };
+}
+
+/**
+ * 模块列表项接口
+ */
+export interface ModuleItem {
+  name: string;
+  count: number;
+}
+
+/**
+ * 文档数据库配置接口
+ */
+export interface DocDatabaseConfig {
+  path: string;
+}

package/types/express.d.ts

@@ -0,0 +1,12 @@
+import { AppState, MindBaseAppOptions } from ".";
+
+declare global {
+  namespace Express {
+    interface Application {
+      getDB: () => AppState["db"];
+      configs: MindBaseAppOptions;
+    }
+  }
+}
+
+export {};

package/types/index.ts

@@ -0,0 +1,19 @@
+export { AppState, MindBaseAppOptions } from "../core/state";
+export { MindBaseApp } from "../core/app";
+export { LogLevel } from "../utils/Logger";
+export { IpInfo } from "../middleware/IpParser";
+export { UaInfo } from "../middleware/UaParser";
+export { ScanResult } from "../feature/scanner/FileScanner";
+export { CronConfig } from "../feature/cron/CronManager";
+export {
+  RouteDoc,
+  ApiResponse,
+  RouteInfo,
+  ModuleItem,
+  DocDatabaseConfig,
+  FieldValidation,
+  FieldConstraints,
+  RequestSchema,
+  ResponseSchema,
+  RouteDocConfig
+} from "./DocTypes";

package/utils/AppError.ts

@@ -0,0 +1,21 @@
+/**
+ * 创建业务错误
+ * @param code HTTP 状态码
+ * @param msg 错误消息
+ */
+export function createAppError(code: number, msg: string): Error {
+  const err = new Error(msg);
+  (err as any).statusCode = code;
+  (err as any).isAppError = true;
+  return err;
+}
+
+/**
+ * 便捷工厂函数
+ */
+export const Errors = {
+  badRequest: (msg: string) => createAppError(400, msg),
+  unauthorized: (msg: string) => createAppError(401, msg),
+  forbidden: (msg: string) => createAppError(403, msg),
+  notFound: (msg: string) => createAppError(404, msg),
+};

package/utils/ComponentRegistry.ts

@@ -0,0 +1,34 @@
+import { AppState } from "../core/state";
+import { ScanResult } from "../types/Index";
+import { registerMiddleware } from "./MiddlewareRegistry";
+import { registerRoute } from "./RouteRegistry";
+import logger from "./Logger";
+
+/**
+ * 封装细节：遍历扫描结果并注册所有组件（中间件和路由）
+ */
+export async function registerComponents(state: AppState, scannedResults: ScanResult[]) {
+  // 1. 先注册所有中间件
+  for (const item of scannedResults) {
+    if (item.type === "middleware") {
+      registerMiddleware(state.express, item);
+    }
+  }
+
+  // 2. 再注册所有路由
+  for (const item of scannedResults) {
+    if (item.type === "route") {
+      registerRoute(state.express, item, state.options.apiPrefix);
+    }
+  }
+
+  // 3. 所有组件注册完成后，触发路由资源同步（如果有）
+  const syncAppRoutes = state.express.get("syncAppRoutes");
+  if (syncAppRoutes && typeof syncAppRoutes === "function") {
+    try {
+      await syncAppRoutes();
+    } catch (error) {
+      logger.error("[ComponentRegistry] 路由资源同步失败:", error);
+    }
+  }
+}

package/utils/DatabaseMigration.ts

@@ -0,0 +1,121 @@
+import { AppState } from "../core/state";
+import logger from "./Logger";
+
+/**
+ * 通过代码调用的方式执行数据库迁移
+ * @param db 数据库实例
+ * @param schemas 数据库 schema 定义
+ * @returns 迁移是否成功
+ */
+export async function executeDatabaseMigration(db: any, schemas: Record<string, any>): Promise<boolean> {
+  try {
+    if (!db) {
+      logger.error("数据库实例不能为空");
+      return false;
+    }
+
+    if (!schemas) {
+      logger.error("数据库 schema 定义不能为空");
+      return false;
+    }
+
+    logger.startup("数据库", "开始执行数据库表结构同步...");
+
+    // 方案：调用 drizzle-kit push 命令
+    try {
+      const { spawn } = await import("child_process");
+
+      logger.startup("数据库", "正在调用 drizzle-kit push 同步表结构...");
+
+      // 使用 drizzle-kit push 命令，捕获输出以判断错误类型
+      const result = await new Promise<boolean>((resolve) => {
+        let output = "";
+        let errorOutput = "";
+
+        const push = spawn("npx", ["drizzle-kit", "push"], {
+          shell: true,
+        });
+
+        push.stdout?.on("data", (data) => {
+          const text = data.toString();
+          output += text;
+        });
+
+        push.stderr?.on("data", (data) => {
+          const text = data.toString();
+          errorOutput += text;
+        });
+
+        push.on("close", (code) => {
+          if (code === 0) {
+            logger.startup("数据库", "✅ drizzle-kit push 执行成功");
+            resolve(true);
+          } else {
+            // 检查是否是已存在对象的良性错误
+            const errorMsg = errorOutput || output;
+            const benignErrors = [
+              "already exists",
+              "索引.*已存在",
+              "index.*already exists",
+              "table.*already exists",
+            ];
+
+            const isBenign = benignErrors.some((pattern) =>
+              new RegExp(pattern, "i").test(errorMsg)
+            );
+
+            if (isBenign) {
+              logger.startup("数据库", "✅ 数据库结构已同步（索引/表已存在）");
+              resolve(true);
+            } else {
+              logger.error(`❌ drizzle-kit push 执行失败，退出码: ${code}`);
+              if (errorMsg) {
+                logger.error(errorMsg);
+              }
+              resolve(false);
+            }
+          }
+        });
+
+        push.on("error", (error) => {
+          logger.error("执行 drizzle-kit push 时出错:", error);
+          resolve(false);
+        });
+      });
+
+      return result;
+    } catch (pushError) {
+      logger.error("调用 drizzle-kit push 失败:", pushError);
+      logger.info("💡 提示：请手动运行 'npx drizzle-kit push' 来同步表结构");
+      return false;
+    }
+  } catch (error) {
+    logger.error("数据库迁移执行失败:", error);
+    return false;
+  }
+}
+
+/**
+ * 检查并执行数据库迁移（如果需要）
+ * @param state 应用状态
+ * @returns 迁移是否成功
+ */
+export async function checkAndMigrateDatabase(state: AppState): Promise<boolean> {
+  try {
+    if (!state || !state.db || !state.schemas) {
+      logger.error("应用状态、数据库实例或 schema 定义不能为空");
+      return false;
+    }
+
+    // 检查 schema 是否有定义
+    if (Object.keys(state.schemas).length === 0) {
+      return true;
+    }
+
+    // 执行数据库迁移
+    return await executeDatabaseMigration(state.db, state.schemas);
+  } catch (error) {
+    logger.error("检查并执行数据库迁移失败:", error);
+    return false;
+  }
+}

package/utils/Dayjs.ts

@@ -0,0 +1,16 @@
+import dayjs from "dayjs";
+import "dayjs/locale/zh-cn";
+import duration from "dayjs/plugin/duration";
+import relativeTime from "dayjs/plugin/relativeTime";
+import utc from "dayjs/plugin/utc";
+
+// 设置中文语言包
+dayjs.locale("zh-cn");
+
+// 注册常用插件
+dayjs.extend(utc);
+dayjs.extend(duration);
+dayjs.extend(relativeTime);
+
+export default dayjs;
+export { dayjs };

package/utils/DocManager.ts

@@ -0,0 +1,279 @@
+import Database from "better-sqlite3";
+import { Database as DatabaseType } from "better-sqlite3";
+import * as path from "path";
+import * as fs from "fs";
+import { RouteInfo, ModuleItem, DocDatabaseConfig } from "../types/DocTypes";
+import logger from "./Logger";
+
+/**
+ * 文档管理器
+ * 管理文档数据，与独立的 SQLite 数据库交互
+ */
+export class DocManager {
+  private db: DatabaseType | null = null;
+  private config: DocDatabaseConfig;
+
+  constructor(config: DocDatabaseConfig) {
+    this.config = config;
+    this.init();
+  }
+
+  /**
+   * 初始化数据库
+   */
+  public init(): void {
+    try {
+      // 确保数据库目录存在
+      const dbDir = path.dirname(this.config.path);
+      if (!fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true });
+      }
+
+      // 连接数据库
+      this.db = new Database(this.config.path);
+
+      // 创建表结构
+      this.createTables();
+    } catch (error) {
+      logger.error("文档数据库初始化失败:", error);
+      this.db = null;
+    }
+  }
+
+  /**
+   * 创建表结构
+   */
+  private createTables(): void {
+    if (!this.db) return;
+
+    // 创建 doc_routes 表
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS doc_routes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        module TEXT NOT NULL,
+        method TEXT NOT NULL,
+        path TEXT NOT NULL,
+        full_path TEXT NOT NULL,
+        summary TEXT,
+        description TEXT,
+        request_schema TEXT,
+        response_schema TEXT,
+        middlewares TEXT,
+        file_path TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        UNIQUE(module, method, path)
+      );
+    `);
+
+    // 创建索引
+    this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_doc_routes_module ON doc_routes(module);
+      CREATE INDEX IF NOT EXISTS idx_doc_routes_full_path ON doc_routes(full_path);
+    `);
+  }
+
+  /**
+   * 保存路由信息
+   * @param routeInfo 路由信息
+   * @param apiPrefix API 前缀
+   * @param moduleName 模块名称
+   */
+  public saveRoute(routeInfo: RouteInfo, apiPrefix: string = "/api", moduleName: string): void {
+    if (!this.db) return;
+
+    try {
+      // 计算完整路径
+      const fullPath = `${apiPrefix}/${moduleName}${routeInfo.path}`.replace(/\/+/g, "/");
+
+      // 准备数据
+      const now = Date.now();
+      const data = {
+        module: moduleName,
+        method: routeInfo.method,
+        path: routeInfo.path,
+        full_path: fullPath,
+        summary: routeInfo.summary,
+        description: routeInfo.description,
+        request_schema: routeInfo.requestSchema ? JSON.stringify(routeInfo.requestSchema) : null,
+        response_schema: routeInfo.responseSchema ? JSON.stringify(routeInfo.responseSchema) : null,
+        middlewares: routeInfo.middlewares ? JSON.stringify(routeInfo.middlewares) : null,
+        file_path: routeInfo.filePath,
+        created_at: now,
+        updated_at: now,
+      };
+
+      // 插入或更新数据
+      const stmt = this.db.prepare(`
+        INSERT INTO doc_routes (
+          module, method, path, full_path, summary, description,
+          request_schema, response_schema, middlewares, file_path, created_at, updated_at
+        ) VALUES (
+          @module, @method, @path, @full_path, @summary, @description,
+          @request_schema, @response_schema, @middlewares, @file_path, @created_at, @updated_at
+        ) ON CONFLICT(module, method, path) DO UPDATE SET
+          full_path = @full_path,
+          summary = @summary,
+          description = @description,
+          request_schema = @request_schema,
+          response_schema = @response_schema,
+          middlewares = @middlewares,
+          file_path = @file_path,
+          updated_at = @updated_at
+      `);
+
+      stmt.run(data);
+    } catch (error) {
+      logger.error("保存路由信息失败:", error);
+    }
+  }
+
+  /**
+   * 获取模块列表
+   * @returns 模块列表
+   */
+  public getModules(): ModuleItem[] {
+    if (!this.db) return [];
+
+    try {
+      const stmt = this.db.prepare(`
+        SELECT module, COUNT(*) as count 
+        FROM doc_routes 
+        GROUP BY module 
+        ORDER BY module
+      `);
+
+      return stmt.all() as ModuleItem[];
+    } catch (error) {
+      logger.error("获取模块列表失败:", error);
+      return [];
+    }
+  }
+
+  /**
+   * 获取路由列表
+   * @param module 模块名称（可选）
+   * @returns 路由列表
+   */
+  public getRoutes(module?: string): RouteInfo[] {
+    if (!this.db) return [];
+
+    try {
+      let query = `
+        SELECT id, module, method, path, full_path, summary, description,
+               request_schema, response_schema, middlewares, file_path, created_at, updated_at
+        FROM doc_routes
+      `;
+
+      const params: any = {};
+
+      if (module) {
+        query += " WHERE module = @module";
+        params.module = module;
+      }
+
+      query += " ORDER BY module, method, path";
+
+      const stmt = this.db.prepare(query);
+      const rows = stmt.all(params) as any[];
+
+      // 转换数据格式
+      return rows.map((row) => ({
+        id: row.id,
+        module: row.module,
+        method: row.method,
+        path: row.path,
+        fullPath: row.full_path,
+        summary: row.summary,
+        description: row.description,
+        requestSchema: row.request_schema ? JSON.parse(row.request_schema) : undefined,
+        responseSchema: row.response_schema ? JSON.parse(row.response_schema) : undefined,
+        middlewares: row.middlewares ? JSON.parse(row.middlewares) : undefined,
+        filePath: row.file_path,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+      }));
+    } catch (error) {
+      logger.error("获取路由列表失败:", error);
+      return [];
+    }
+  }
+
+  /**
+   * 获取路由详情
+   * @param id 路由 ID
+   * @returns 路由详情
+   */
+  public getRouteById(id: number): RouteInfo | null {
+    if (!this.db) return null;
+
+    try {
+      const stmt = this.db.prepare(`
+        SELECT id, module, method, path, full_path, summary, description,
+               request_schema, response_schema, middlewares, file_path, created_at, updated_at
+        FROM doc_routes
+        WHERE id = @id
+      `);
+
+      const row = stmt.get({ id }) as any;
+
+      if (!row) return null;
+
+      // 转换数据格式
+      return {
+        id: row.id,
+        module: row.module,
+        method: row.method,
+        path: row.path,
+        fullPath: row.full_path,
+        summary: row.summary,
+        description: row.description,
+        requestSchema: row.request_schema ? JSON.parse(row.request_schema) : undefined,
+        responseSchema: row.response_schema ? JSON.parse(row.response_schema) : undefined,
+        middlewares: row.middlewares ? JSON.parse(row.middlewares) : undefined,
+        filePath: row.file_path,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+      };
+    } catch (error) {
+      logger.error("获取路由详情失败:", error);
+      return null;
+    }
+  }
+
+  /**
+   * 清空所有路由数据
+   */
+  public clearAllRoutes(): void {
+    if (!this.db) return;
+
+    try {
+      this.db.exec("DELETE FROM doc_routes");
+    } catch (error) {
+      logger.error("清空路由数据失败:", error);
+    }
+  }
+
+  /**
+   * 关闭数据库连接
+   */
+  public close(): void {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+      logger.info("文档数据库连接已关闭");
+    }
+  }
+}
+
+// 导出单例实例
+export let docManager: DocManager;
+
+/**
+ * 初始化文档管理器
+ * @param config 配置
+ */
+export function initDocManager(config: DocDatabaseConfig): DocManager {
+  docManager = new DocManager(config);
+  return docManager;
+}

package/utils/HttpServer.ts

@@ -0,0 +1,41 @@
+import { Express } from "express";
+import logger from "./Logger";
+
+/**
+ * 启动 HTTP 服务
+ * @param app Express 实例
+ * @param port 监听端口
+ * @returns Promise<void>
+ * @throws 如果服务器启动失败
+ */
+export async function startServer(app: Express, port: number): Promise<void> {
+  if (!app) {
+    throw new Error("Express 实例不能为空");
+  }
+
+  if (!port || typeof port !== "number" || port <= 0 || port > 65535) {
+    throw new Error(`无效的端口号: ${port}`);
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    try {
+      const server = app.listen(port, () => {
+        resolve();
+      });
+
+      // 处理服务器错误
+      server.on("error", (error) => {
+        logger.error("服务器启动失败：", error);
+        reject(new Error(`服务器启动失败：${error instanceof Error ? error.message : String(error)}`));
+      });
+
+      // 处理服务器关闭
+      server.on("close", () => {
+        logger.info("服务器已关闭");
+      });
+    } catch (error) {
+      logger.error("服务器启动异常：", error);
+      reject(new Error(`服务器启动异常：${error instanceof Error ? error.message : String(error)}`));
+    }
+  });
+}