@mindbase/express-common 1.0.0

package/utils/DocManager.ts

@@ -0,0 +1,274 @@
+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,
+        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,
+        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, middlewares, file_path, created_at, updated_at
+        ) VALUES (
+          @module, @method, @path, @full_path, @summary, @description, 
+          @request_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,
+          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, 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,
+        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, 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,
+        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)}`));
+    }
+  });
+}

package/utils/InitDatabase.ts

@@ -0,0 +1,149 @@
+import path from "path";
+import fs from "fs";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import Database from "better-sqlite3";
+import { AppState } from "../core/state";
+import { ScanResult } from "../types/Index";
+import logger from "./Logger";
+
+/**
+ * 封装细节：从扫描结果中提取 Schema 并初始化数据库
+ * @param state 应用状态
+ * @param scannedResults 扫描结果
+ * @returns 数据库实例
+ * @throws 如果数据库设置失败
+ */
+export function setupDatabase(state: AppState, scannedResults: ScanResult[]) {
+  try {
+    if (!state) {
+      throw new Error("应用状态对象不能为空");
+    }
+
+    if (!Array.isArray(scannedResults)) {
+      throw new Error("扫描结果必须是一个数组");
+    }
+
+    const schemas: Record<string, any> = {};
+    for (const item of scannedResults) {
+      if (item.type === "schema" && item.allExports) {
+        try {
+          Object.assign(schemas, item.allExports);
+        } catch (e) {
+          logger.warn(`处理 Schema 文件失败: ${item.filePath}`, e);
+        }
+      }
+    }
+    state.schemas = schemas;
+
+    logger.startup("扫描", `提取到 ${Object.keys(schemas).length} 个 Schema 定义`);
+
+    return initDatabase({
+      schemas,
+      state,
+    });
+  } catch (error) {
+    logger.error("数据库设置失败：", error);
+    throw new Error(`数据库设置失败：${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * 初始化 SQLite 数据库
+ * @param options 配置选项
+ * @returns 数据库实例
+ * @throws 如果数据库初始化失败
+ */
+export function initDatabase(options: { schemas: Record<string, any>; dbPath?: string; state?: AppState }): any {
+  if (!options) {
+    throw new Error("初始化选项不能为空");
+  }
+
+  try {
+    const currentDir = process.cwd();
+    const dbPath = options.dbPath || options.state?.options?.database?.path || "./data/app.db";
+    const absoluteDbPath = path.resolve(currentDir, dbPath);
+    const dbDir = path.dirname(absoluteDbPath);
+
+    logger.startup("数据库", `初始化：路径=${absoluteDbPath}`);
+
+    // 确保目录存在
+    try {
+      if (!fs.existsSync(dbDir)) {
+        logger.startup("数据库", `创建目录：${dbDir}`);
+        fs.mkdirSync(dbDir, { recursive: true });
+      }
+    } catch (e) {
+      throw new Error(`创建数据库目录失败：${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    // 初始化 SQLite 数据库
+    let sqlite: Database.Database;
+    try {
+      sqlite = new Database(absoluteDbPath);
+    } catch (e) {
+      throw new Error(`连接数据库失败：${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    // 推荐的 SQLite 性能设置
+    try {
+      sqlite.pragma("journal_mode = WAL");
+      sqlite.pragma("synchronous = NORMAL");
+    } catch (e) {
+      logger.warn("设置 SQLite 性能参数失败：", e);
+      // 继续执行，不中断初始化
+    }
+
+    // 初始化 Drizzle
+    let db: any;
+    try {
+      db = drizzle(sqlite, { schema: options.schemas || {} });
+    } catch (e) {
+      // 关闭 SQLite 连接
+      try {
+        sqlite.close();
+      } catch (closeError) {
+        logger.warn("关闭数据库连接失败：", closeError);
+      }
+      throw new Error(`初始化 Drizzle ORM 失败：${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    // 如果提供了状态对象，更新它
+    if (options.state) {
+      options.state.db = db;
+    }
+
+    return db;
+  } catch (error) {
+    logger.error("数据库初始化失败：", error);
+    throw new Error(`数据库初始化失败：${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * 处理数据库表结构迁移
+ * @param db 数据库实例
+ * @param schemas 数据库 schema 定义
+ * @throws 如果迁移失败
+ */
+export async function handleDatabaseMigration(db: any, schemas: Record<string, any>) {
+  try {
+    if (!db) {
+      throw new Error("数据库实例不能为空");
+    }
+
+    if (!schemas) {
+      throw new Error("数据库 schema 定义不能为空");
+    }
+
+    // 只提醒，不自动执行
+    logger.info("🔔 数据库表结构检查完成");
+    logger.info("   如需同步数据库结构，请执行:");
+    logger.info("   npx drizzle-kit push");
+
+    logger.debug("数据库迁移提醒已显示");
+  } catch (error) {
+    logger.error("数据库迁移提醒失败：", error);
+    throw new Error(`数据库迁移提醒失败：${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/utils/InitErrorHandler.ts

@@ -0,0 +1,71 @@
+import { Request, Response, NextFunction, Express } from "express";
+import { ZodError } from "zod";
+import logger from "./Logger";
+
+/**
+ * 检测是否为 SQL 相关错误（表/字段不存在）
+ */
+function isSQLError(err: any): boolean {
+  if (!err) return false;
+  const msg = err.message || err.toString() || "";
+  return /no such table|table.*does not exist|column.*does not exist|database schema has changed/i.test(msg);
+}
+
+/**
+ * 封装细节：初始化错误处理和 404 中间件
+ */
+export function setupErrorHandlers(app: Express, logging?: boolean) {
+  // 404 处理
+  app.use((req: Request, res: Response) => {
+    res.status(404).json({
+      code: 404,
+      data: null,
+      msg: "接口不存在",
+      error: "Not Found",
+      fields: {},
+    });
+  });
+
+  // 错误处理
+  app.use((err: any, req: Request, res: Response, next: NextFunction) => {
+    // 处理 Zod 校验错误
+    if (err instanceof ZodError) {
+      const fields: Record<string, string> = {};
+      err.errors.forEach((e) => {
+        const path = e.path.join(".");
+        fields[path] = e.message;
+      });
+
+      return res.status(400).json({
+        code: 400,
+        data: null,
+        msg: "参数校验失败",
+        error: "ZodValidationError",
+        fields,
+      });
+    }
+
+    // 处理 SQL 错误（给出友好提示）
+    if (isSQLError(err)) {
+      logger.error("");
+      logger.error("❌ 数据库结构可能已变化，请运行以下命令同步：");
+      logger.error("");
+      logger.error("   npm run db:migrate");
+      logger.error("");
+    }
+
+    // 处理普通错误
+    const statusCode = err.status || err.statusCode || 500;
+    if (!isSQLError(err)) {
+      logger.error("系统错误:", err);
+    }
+
+    res.status(statusCode).json({
+      code: statusCode,
+      data: null,
+      msg: err.message || "服务器内部错误",
+      error: logging ? err.stack : "InternalServerError",
+      fields: {},
+    });
+  });
+}

package/utils/InitExpress.ts

@@ -0,0 +1,35 @@
+import express, { Express } from "express";
+import fs from "fs";
+import cookieParser from "cookie-parser";
+import cors from "../middleware/Cors";
+import ipParser from "../middleware/IpParser";
+import uaParser from "../middleware/UaParser";
+import { LightUpAppOptions } from "../types/Index";
+import logger from "./Logger";
+
+export default function initExpress(app: Express, options: LightUpAppOptions): void {
+  app.set("config", options);
+  app.disable("x-powered-by");
+  app.use(express.urlencoded({ extended: false, limit: "10mb" }));
+  app.use(express.json({ limit: "10mb" }));
+  app.use(cookieParser());
+  if (options.staticPath) {
+    if (!fs.existsSync(options.staticPath)) {
+      fs.mkdirSync(options.staticPath, { recursive: true });
+    }
+    app.use(express.static(options.staticPath));
+    logger.startup("设置", `静态目录: ${options.staticPath}`);
+  }
+  if (options.cors) {
+    app.use(cors);
+    logger.startup("设置", "跨域请求头");
+  }
+  if (options.ip) {
+    logger.startup("设置", "IP地址解析");
+    app.use(ipParser);
+  }
+  if (options.userAgent) {
+    logger.startup("设置", "用户代理解析");
+    app.use(uaParser);
+  }
+}