@mindbase/express-common 1.0.0

package/feature/scanner/FileScanner.ts

@@ -0,0 +1,288 @@
+import { glob } from "glob";
+import path from "path";
+import fs from "fs";
+import logger from "../../utils/Logger";
+
+const CACHE_VERSION = "2.0";
+const CACHE_DIR = path.join(process.cwd(), "node_modules/.cache/mindbase");
+const CACHE_FILE = path.join(CACHE_DIR, "startup-cache.json");
+
+/**
+ * 缓存条目接口
+ */
+interface CacheEntry {
+  filePath: string;
+  mtime: number;
+}
+
+/**
+ * 缓存数据接口
+ */
+interface CacheData {
+  version: string;
+  entries: Map<string, CacheEntry>;
+}
+
+// 全局缓存数据
+let cacheData: CacheData | null = null;
+
+/**
+ * 扫描结果接口
+ */
+export interface ScanResult {
+  fileName: string;
+  defaultExport: any;
+  allExports?: any;
+  type: "route" | "middleware" | "schema";
+  filePath: string;
+  /** 缓存命中标志（文档已在数据库） */
+  cacheHit?: boolean;
+}
+
+/**
+ * 扫描器状态接口
+ */
+interface ScannerState {
+  scanPaths: string[]; // 要扫描的目录数组
+  baseDir: string; // 基础目录（最后扫描）
+}
+
+// 初始化扫描器状态
+const state: ScannerState = {
+  scanPaths: [],
+  baseDir: "",
+};
+
+/**
+ * 设置基础目录
+ * @param baseDir 基础目录路径
+ */
+export function setBaseDir(baseDir: string): void {
+  state.baseDir = baseDir;
+}
+
+/**
+ * 添加扫描目录
+ * @param dirPath 要添加的目录绝对路径
+ * @throws 如果路径不是目录或不存在
+ */
+export function addScanPath(dirPath: string): void {
+  // 验证路径是否为绝对路径
+  if (!path.isAbsolute(dirPath)) {
+    throw new Error(`路径必须是绝对路径: ${dirPath}`);
+  }
+
+  // 验证路径是否存在且为目录
+  if (!fs.existsSync(dirPath)) {
+    throw new Error(`目录不存在: ${dirPath}`);
+  }
+
+  if (!fs.statSync(dirPath).isDirectory()) {
+    throw new Error(`路径不是目录: ${dirPath}`);
+  }
+
+  // 去重：检查路径是否已经存在
+  if (state.scanPaths.includes(dirPath)) {
+    return;
+  }
+
+  // 检查是否是基础目录的子目录，如果是则跳过
+  if (state.baseDir && dirPath.startsWith(state.baseDir)) {
+    return;
+  }
+
+  // 检查是否是其他已添加路径的子目录，如果是则跳过
+  for (const existingPath of state.scanPaths) {
+    if (dirPath.startsWith(existingPath)) {
+      return;
+    }
+  }
+
+  // 添加到扫描路径数组
+  state.scanPaths.push(dirPath);
+}
+
+/**
+ * 验证路径是否为有效目录
+ * @param dirPath 目录路径
+ * @returns 是否为有效目录
+ */
+function isValidDirectory(dirPath: string): boolean {
+  try {
+    return fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 从文件路径提取文件名（不含扩展名）
+ * @param filePath 文件路径
+ * @returns 文件名（不含扩展名）
+ */
+function extractFileName(filePath: string): string {
+  const fileName = path.basename(filePath);
+  // 移除 .route.ts, .middleware.ts 或 .schema.ts 扩展名
+  return fileName.replace(/\.(route|middleware|schema)\.ts$/, "");
+}
+
+/**
+ * 加载缓存数据
+ * @returns 缓存数据对象，加载失败返回 null
+ */
+async function loadCache(): Promise<void> {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) {
+      cacheData = { version: CACHE_VERSION, entries: new Map() };
+      return;
+    }
+
+    const json = fs.readFileSync(CACHE_FILE, "utf-8");
+    const data = JSON.parse(json);
+
+    // 检查缓存版本
+    if (data.version !== CACHE_VERSION) {
+      logger.debug(`缓存版本不匹配 (${data.version} vs ${CACHE_VERSION})，将重新构建`);
+      cacheData = { version: CACHE_VERSION, entries: new Map() };
+      return;
+    }
+
+    // 重建 Map
+    cacheData = {
+      version: data.version,
+      entries: new Map(Object.entries(data.entries).map(([k, v]: [string, any]) => [k, v])),
+    };
+
+    logger.debug(`已加载缓存，包含 ${cacheData.entries.size} 个文件条目`);
+  } catch (error) {
+    logger.warn(`加载缓存失败，将重新构建: ${error}`);
+    cacheData = { version: CACHE_VERSION, entries: new Map() };
+  }
+}
+
+/**
+ * 保存缓存数据
+ */
+async function saveCache(): Promise<void> {
+  try {
+    if (!cacheData) return;
+
+    // 确保目录存在
+    if (!fs.existsSync(CACHE_DIR)) {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+
+    // 序列化 Map 为普通对象
+    const data = {
+      version: cacheData.version,
+      entries: Object.fromEntries(cacheData.entries),
+    };
+
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2), "utf-8");
+    logger.debug(`缓存已保存，包含 ${cacheData.entries.size} 个文件条目`);
+  } catch (error) {
+    logger.warn(`保存缓存失败: ${error}`);
+  }
+}
+
+/**
+ * 启动扫描目录
+ * @param onlyPaths 是否仅返回路径，不导入模块
+ * @returns 扫描结果数组
+ */
+export async function scan(onlyPaths: boolean = false): Promise<ScanResult[]> {
+  // 加载缓存
+  await loadCache();
+
+  const results: ScanResult[] = [];
+  const allScanPaths = [...state.scanPaths];
+  const processedFiles = new Set<string>();
+
+  // 如果设置了基础目录，将其添加到最后扫描
+  if (state.baseDir) {
+    allScanPaths.push(state.baseDir);
+  }
+
+  // 循环扫描所有目录
+  for (const dirPath of allScanPaths) {
+    if (!isValidDirectory(dirPath)) {
+      logger.warn(`跳过无效目录: ${dirPath}`);
+      continue;
+    }
+
+    // 构建 glob 模式
+    const patterns = [
+      { type: "middleware" as const, pattern: "**/*.middleware.ts" },
+      { type: "route" as const, pattern: "**/*.route.ts" },
+      { type: "schema" as const, pattern: "**/*.schema.ts" },
+    ];
+
+    for (const { type, pattern } of patterns) {
+      const globPattern = path.join(dirPath, pattern).replace(/\\/g, "/");
+      try {
+        const files = await glob(globPattern, { absolute: true });
+        for (const file of files) {
+          // 去重：跳过已处理的文件
+          if (processedFiles.has(file)) {
+            continue;
+          }
+          processedFiles.add(file);
+
+          try {
+            const fileName = extractFileName(file);
+
+            if (onlyPaths) {
+              results.push({
+                fileName,
+                type,
+                filePath: file,
+                defaultExport: null,
+                allExports: null,
+              });
+              continue;
+            }
+
+            // 检查文件修改时间
+            const stats = await fs.promises.stat(file);
+            const mtime = stats.mtimeMs;
+
+            // 检查缓存命中
+            const cached = cacheData?.entries.get(file);
+            const cacheHit = cached && cached.mtime === mtime;
+
+            if (cacheHit) {
+              // 缓存命中，文档已在数据库
+              logger.debug(`缓存命中: ${file}`);
+            }
+
+            // 导入模块（必须执行，获取 handler 用于 app.use）
+            const module = await import(file);
+            const scanResult: ScanResult = {
+              fileName,
+              defaultExport: module.default,
+              allExports: module,
+              type,
+              filePath: file,
+              cacheHit,
+            };
+            results.push(scanResult);
+
+            // 更新缓存（无论是否命中，都更新 mtime）
+            if (cacheData) {
+              cacheData.entries.set(file, { filePath: file, mtime });
+            }
+          } catch (error) {
+            logger.warn(`处理文件失败: ${file}`, error);
+          }
+        }
+      } catch (error) {
+        logger.warn(`扫描目录失败: ${dirPath} (Pattern: ${pattern})`, error);
+      }
+    }
+  }
+
+  // 保存缓存
+  await saveCache();
+
+  return results;
+}

package/index.ts

@@ -0,0 +1,10 @@
+export { createApp } from "./core/app";
+export { addCron, stopCron, stopAllCron } from "./feature/cron/CronManager";
+export { createModule } from "./core/module/CreateModule";
+export { logger } from "./utils/Logger";
+export { dayjs } from "./utils/Dayjs";
+export { validate } from "./utils/Validate";
+export { initDatabase } from "./utils/InitDatabase";
+export { handleSchemaMigrate } from "./utils/SchemaMigrate";
+
+export type * from "./types/Index";

package/middleware/Cors.ts

@@ -0,0 +1,17 @@
+import { NextFunction, Request, Response } from "express";
+
+/**
+ * 跨域处理
+ * @description 为API请求添加处理跨域请求头，并处理Options 预请求
+ */
+export default function (req: Request, res: Response, next: NextFunction) {
+  res.header("Access-Control-Allow-Origin", "*");
+  res.header("Access-Control-Allow-Credentials", "true");
+  res.header("Access-Control-Allow-Methods", "POST,GET,OPTIONS");
+  res.header("Access-Control-Allow-Headers", "Content-Type,Content-Length, Authorization, Accept,X-Requested-With");
+  if (req.method == "OPTIONS") {
+    res.sendStatus(200);
+  } else {
+    next();
+  }
+}

package/middleware/IpParser.ts

@@ -0,0 +1,81 @@
+import { NextFunction, Request, Response } from "express";
+import ipdb from "ipip-ipdb";
+import { join } from "path";
+import logger from "../utils/Logger";
+
+/**
+ * IP 解析结果数据结构
+ */
+export interface IpInfo {
+  address: string; // 原始 IP 地址
+  location: string; // 格式化后的地理位置 (国家 省份 城市)
+  country: string; // 国家
+  province: string; // 省份/直辖市
+  city: string; // 城市
+  isp: string; // 运营商
+  latitude: string; // 纬度
+  longitude: string; // 经度
+  isLocal: boolean; // 是否为本地/回环地址
+}
+
+// 预初始化数据库实例
+const dbPath = join(process.cwd(), "ipipfree.ipdb");
+let cityInstance: any;
+
+try {
+  cityInstance = new ipdb.City(dbPath);
+} catch (error) {
+  logger.error(`[IpParser] Failed to load IP database at: ${dbPath}`);
+}
+
+/**
+ * IP 解析中间件
+ * 纯净实现：仅解析 IP 信息并打平数据结构，不包含冗余的向后兼容字段。
+ */
+export default function (req: Request, res: Response, next: NextFunction) {
+  const ip = (req.headers["real-ip"] || req.headers["x-real-ip"] || req.ip) as string;
+
+  const info: IpInfo = {
+    address: ip,
+    location: "未知",
+    country: "",
+    province: "",
+    city: "",
+    isp: "",
+    latitude: "",
+    longitude: "",
+    isLocal: false,
+  };
+
+  // 处理本地回环地址
+  const localIdentifiers = ["127.0.0.1", "::1", "::ffff:127.0.0.1", "localhost"];
+  if (localIdentifiers.includes(ip)) {
+    info.location = "本机";
+    info.isLocal = true;
+    res.locals.ip = info;
+    return next();
+  }
+
+  // 数据库查询
+  if (cityInstance) {
+    try {
+      const data = cityInstance.findMap(ip, "CN");
+      if (data) {
+        info.country = data.country_name || "";
+        info.province = data.region_name || "";
+        info.city = data.city_name || "";
+        info.isp = data.isp_domain || "";
+        info.latitude = data.latitude || "";
+        info.longitude = data.longitude || "";
+
+        const parts = [info.country, info.province, info.city].filter(Boolean);
+        info.location = parts.join(" ") || "未知位置";
+      }
+    } catch (err) {
+      // 查询失败保持默认 info
+    }
+  }
+
+  res.locals.ip = info;
+  next();
+}

package/middleware/UaParser.ts

@@ -0,0 +1,50 @@
+import { NextFunction, Request, Response } from "express";
+import { UAParser } from "ua-parser-js";
+
+export interface UaInfo {
+  ua: string;
+  browser: {
+    name?: string;
+    version?: string;
+    major?: string;
+  };
+  engine: {
+    name?: string;
+    version?: string;
+  };
+  os: {
+    name?: string;
+    version?: string;
+  };
+  device: {
+    model?: string;
+    type?: string;
+    vendor?: string;
+  };
+  cpu: {
+    architecture?: string;
+  };
+  isMobile: boolean;
+}
+
+/**
+ * UA 解析中间件
+ * 纯净实现：仅解析 User-Agent 信息并存入 res.locals.UA
+ */
+export default function (req: Request, res: Response, next: NextFunction) {
+  const parser = new UAParser(req.headers["user-agent"] as string);
+  const result = parser.getResult();
+
+  const ua: UaInfo = {
+    ua: result.ua,
+    browser: result.browser,
+    engine: result.engine,
+    os: result.os,
+    device: result.device,
+    cpu: result.cpu,
+    isMobile: result.device.type === "mobile",
+  };
+
+  res.locals.UA = ua;
+  next();
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mindbase/express-common",
+  "version": "1.0.0",
+  "main": "./index.ts",
+  "bin": {
+    "mindbase": "./bin/mindbase.ts"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "volta": {
+    "node": "20.20.0"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.10.0",
+    "cli-table3": "^0.6.3",
+    "drizzle-orm": "^0.44.7",
+    "drizzle-zod": "^0.5.0",
+    "glob": "^10.0.0",
+    "prompts": "^2.4.2",
+    "radash": "12.1.1",
+    "ts-morph": "^27.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/prompts": "^2.4.9",
+    "@vitest/coverage-v8": "^2.1.0",
+    "@vitest/ui": "^2.1.0",
+    "typescript": "^5.1.3",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:cov": "vitest run --coverage"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/routes/Doc.route.ts

@@ -0,0 +1,118 @@
+import { Router, Request, Response } from "express";
+import { docManager } from "../utils/DocManager";
+import { validate } from "../utils/Validate";
+import { routeIdParamsSchema } from "../zod/Doc.schema";
+import { ApiResponse, ModuleItem, RouteInfo } from "../types/DocTypes";
+
+const router = Router();
+
+/**
+ * 获取模块列表
+ * GET /api/doc/modules
+ * @returns {ApiResponse<ModuleItem[]>} 返回模块列表
+ */
+router.get("/modules", (req: Request, res: Response) => {
+  try {
+    const modules = docManager.getModules();
+    const response: ApiResponse = {
+      code: 200,
+      data: modules,
+      msg: "success",
+    };
+    res.json(response);
+  } catch (error) {
+    const response: ApiResponse = {
+      code: 500,
+      data: null,
+      msg: "获取模块列表失败",
+    };
+    res.json(response);
+  }
+});
+
+/**
+ * 获取路由列表
+ * GET /api/doc/routes
+ * 查询参数: module (可选)
+ * @returns {ApiResponse<RouteInfo[]>} 返回路由列表
+ */
+router.get("/routes", (req: Request, res: Response) => {
+  try {
+    const module = req.query.module as string;
+    const routes = docManager.getRoutes(module);
+    const response: ApiResponse = {
+      code: 200,
+      data: routes,
+      msg: "success",
+    };
+    res.json(response);
+  } catch (error) {
+    const response: ApiResponse = {
+      code: 500,
+      data: null,
+      msg: "获取路由列表失败",
+    };
+    res.json(response);
+  }
+});
+
+/**
+ * 获取路由详情
+ * GET /api/doc/routes/:id
+ * @returns {ApiResponse<RouteInfo>} 返回路由详情
+ */
+router.get("/routes/:id", validate(routeIdParamsSchema as any, "params"), (req: Request, res: Response) => {
+  try {
+    const { id } = req.params as any;
+    const route = docManager.getRouteById(id);
+    if (!route) {
+      const response: ApiResponse = {
+        code: 404,
+        data: null,
+        msg: "路由不存在",
+      };
+      return res.json(response);
+    }
+
+    const response: ApiResponse = {
+      code: 200,
+      data: route,
+      msg: "success",
+    };
+    res.json(response);
+  } catch (error) {
+    const response: ApiResponse = {
+      code: 500,
+      data: null,
+      msg: "获取路由详情失败",
+    };
+    res.json(response);
+  }
+});
+
+/**
+ * 手动同步文档数据
+ * POST /api/doc/sync
+ * @returns {ApiResponse<boolean>} 同步成功返回true
+ */
+router.post("/sync", (req: Request, res: Response) => {
+  try {
+    // 这里可以实现手动同步逻辑
+    // 例如：重新扫描所有路由文件并更新文档数据
+    const response: ApiResponse = {
+      code: 200,
+      data: true,
+      msg: "同步成功",
+    };
+    res.json(response);
+  } catch (error) {
+    const response: ApiResponse = {
+      code: 500,
+      data: null,
+      msg: "同步失败",
+    };
+    res.json(response);
+  }
+});
+
+export default router;

package/tests/Cors.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi } from "vitest";
+import cors from "../middleware/Cors";
+import { Request, Response } from "express";
+
+describe("Cors 中间件", () => {
+  it("应该设置 CORS 响应头", () => {
+    const req = { method: "GET" } as Request;
+    const res = {
+      header: vi.fn(),
+      sendStatus: vi.fn(),
+    } as unknown as Response;
+    const next = vi.fn();
+
+    cors(req, res, next);
+
+    expect(res.header).toHaveBeenCalledWith("Access-Control-Allow-Origin", "*");
+    expect(res.header).toHaveBeenCalledWith("Access-Control-Allow-Methods", "POST,GET,OPTIONS");
+    expect(next).toHaveBeenCalled();
+  });
+
+  it("应该处理 OPTIONS 请求", () => {
+    const req = { method: "OPTIONS" } as Request;
+    const res = {
+      header: vi.fn(),
+      sendStatus: vi.fn(),
+    } as unknown as Response;
+    const next = vi.fn();
+
+    cors(req, res, next);
+
+    expect(res.sendStatus).toHaveBeenCalledWith(200);
+    expect(next).not.toHaveBeenCalled();
+  });
+});

package/tests/Dayjs.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import dayjs from "../utils/Dayjs";
+
+describe("Dayjs Utility", () => {
+  it("should have zh-cn locale", () => {
+    expect(dayjs.locale()).toBe("zh-cn");
+  });
+
+  it("应该具有 duration 插件", () => {
+    expect(dayjs.duration).toBeDefined();
+    const dur = dayjs.duration(1, "hour");
+    expect(dur.asMinutes()).toBe(60);
+  });
+
+  it("应该具有 relativeTime 插件", () => {
+    expect(dayjs().fromNow).toBeDefined();
+  });
+
+  it("should have utc plugin", () => {
+    expect(dayjs.utc).toBeDefined();
+    const now = dayjs.utc();
+    expect(now.isUTC()).toBe(true);
+  });
+});