chanjs 2.1.1 → 2.3.0

package/App.js

@@ -0,0 +1,387 @@
+import express from "express";
+import fs from "fs";
+import path from "path";
+
+import AppContext from "./base/Context.js";
+import Controller from "./base/Controller.js";
+import DatabaseManager from "./base/Database.js";
+
+import Service from "./base/Service.js";
+
+import { Paths } from "./config/index.js";
+import { getChildrenId, filterBody, filterImgFromStr, CODE as commonCode, sendMail, genRegEmailHtml, genResetPasswordEmail, pages, getHtmlFilesSync } from "./common/index.js";
+import { db, loadConfig, loadController, loaderSort, prefixDbConfig, formatDateFields, request, delImg, getIp, setToken, getToken, verifyToken, generateToken, getFileTree, readFileContent, saveFileContent, isPathSafe, arrToObj, htmlDecode } from "./helper/index.js";
+import { Cors, setBody, setCookie, setFavicon, setHeader, setStatic, setTemplate, waf } from "./middleware/index.js";
+import { errorResponse, notFoundResponse, parseDatabaseError } from "./utils/error-handler.js";
+import { error as responseError, fail, success } from "./utils/response.js";
+
+import "./global/index.js";
+
+/**
+ * Chan 应用核心类
+ * @class Chan
+ * @description 管理应用程序的路由、中间件、数据库连接和服务
+ * @example
+ * const app = new Chan({ port: 3000, env: "production" });
+ * await app.start();
+ */
+class Chan {
+  static helper = {
+    loadController,
+    db,
+    prefixDbConfig,
+    loaderSort,
+    loadConfig,
+    formatDateFields,
+    request,
+    delImg,
+    getIp,
+    setToken,
+    getToken,
+    verifyToken,
+    generateToken,
+    getFileTree,
+    readFileContent,
+    saveFileContent,
+    isPathSafe,
+    arrToObj,
+    htmlDecode,
+  };
+  static common = {
+    success,
+    fail,
+    error: responseError,
+    getChildrenId,
+    CODE: commonCode,
+    sendMail,
+    genRegEmailHtml,
+    genResetPasswordEmail,
+    pages,
+    getHtmlFilesSync,
+    filterBody,
+    filterImgFromStr,
+  };
+  static config = {};
+  static Service = Service;
+  static Controller = Controller;
+  static paths = Paths;
+
+  /**
+   * 构造函数
+   * @constructor
+   * @param {Object} options - 应用配置选项
+   * @param {number} [options.port=3000] - 服务器端口
+   * @param {string} [options.env] - 运行环境
+   * @description 初始化 Express 应用和核心组件
+   */
+  constructor(options = {}) {
+    this.app = express();
+    this.context = new AppContext();
+    this.dbManager = new DatabaseManager();
+
+    this.options = {
+      port: options.port || 3000,
+      env: options.env || process.env.NODE_ENV || "development",
+      ...options,
+    };
+
+    this._isStarted = false;
+    this.router = express.Router();
+  }
+
+  /**
+   * 启动应用程序
+   * @async
+   * @description 执行完整的启动流程
+   * 包括：初始化配置、数据库、扩展、中间件、路由、错误处理
+   * @returns {Promise<void>}
+   */
+  async start() {
+    if (this._isStarted) {
+      console.warn("App already started");
+      return;
+    }
+
+    global.appContext = this.context;
+    global.Chan = Chan;
+
+    await this.initConfig();
+    await this.initDB();
+    await this.initExtend();
+    await this.initMiddleware();
+
+    this._applyConfig();
+
+    await this.loadRouter();
+    await this.loadCommonRouter();
+
+    this._applyRoutes();
+    this._applyErrorHandling();
+
+    await this._listen();
+
+    this._isStarted = true;
+  }
+
+  /**
+   * 初始化配置
+   * @async
+   * @returns {Promise<void>}
+   * @description 加载应用配置并设置到上下文
+   */
+  async initConfig() {
+    let config = await loadConfig();
+    Chan.config = config;
+    this.context.set("config", config);
+  }
+
+  /**
+   * 初始化数据库
+   * @async
+   * @returns {Promise<void>}
+   * @description 根据配置初始化所有数据库连接
+   */
+  async initDB() {
+    const dbList = Chan.config?.db || [];
+    const connections = this.dbManager.getConnections();
+
+    for (const [index, item] of dbList.entries()) {
+      const key = item.key || String(index);
+      try {
+        const dbConfig = prefixDbConfig(key) || item;
+        if (!dbConfig) throw new Error("未找到配置");
+
+        const connection = this.dbManager.add(key, dbConfig, { isDefault: index === 0 });
+        this.context.set(`db:${key}`, connection);
+        
+        if (index === 0) {
+          Chan.db = connection;
+        }
+      } catch (error) {
+        console.error(`[DB] 数据库 ${key} 初始化失败: ${error.message}`);
+      }
+    }
+
+    console.log(
+      `[DB] 初始化完成，已加载 ${dbList.length} 个数据库，成功 ${Object.keys(connections).length} 个`,
+    );
+  }
+
+  /**
+   * 初始化扩展模块
+   * @async
+   * @returns {Promise<void>}
+   * @description 加载 common、helper、extend 目录下的扩展模块
+   */
+  async initExtend() {
+    const extensions = [
+      { _path: Paths.commonPath, key: "common" },
+      { _path: Paths.helperPath, key: "helper" },
+      { _path: Paths.extendPath, key: "extend" },
+    ];
+
+    for (const { _path, key } of extensions) {
+      await this.loadFn(_path, key);
+    }
+  }
+
+  /**
+   * 加载模块文件
+   * @async
+   * @param {string} _path - 模块目录路径
+   * @param {string} key - 模块键名
+   * @returns {Promise<void>}
+   * @description 从指定目录加载所有 JS 模块并合并到 Chan 静态属性
+   */
+  async loadFn(_path, key) {
+    if (fs.existsSync(_path)) {
+      const files = fs.readdirSync(_path).filter((file) => file.endsWith(".js"));
+      for (const file of files) {
+        const filePath = path.join(_path, file);
+        let helperModule = await importFile(filePath);
+        Object.assign(Chan[key], helperModule);
+      }
+    }
+  }
+
+  /**
+   * 初始化中间件
+   * @async
+   * @returns {Promise<void>}
+   * @description 配置并注册所有应用中间件
+   */
+  async initMiddleware() {
+    const config = Chan.config;
+    const { views = [], env = "development", APP_NAME = "ChanCMS", APP_VERSION = "1.0.0", cookieKey, BODY_LIMIT = "10mb", statics = [], cors = {}, PROXY = "false", waf: wafConfig = { enabled: false } } = config;
+
+    await waf(this.app, wafConfig);
+    setFavicon(this.app);
+    setStatic(this.app, statics);
+    setCookie(this.app, cookieKey);
+    setBody(this.app, BODY_LIMIT);
+    Cors(this.app, cors);
+    setTemplate(this.app, { views, NODE_ENV: env });
+    setHeader(this.app, { APP_NAME, APP_VERSION });
+  }
+
+  /**
+   * 应用配置
+   * @private
+   * @description 设置 Express 应用配置
+   */
+  _applyConfig() {
+    this.app.set("trust proxy", Chan.config.PROXY === "true");
+    this.app.set("env", this.options.env);
+    this.app.disable("x-powered-by");
+  }
+
+  /**
+   * 应用路由
+   * @private
+   * @description 将所有路由应用到 Express 应用
+   */
+  _applyRoutes() {
+    this.app.use(this.router);
+  }
+
+  /**
+   * 应用错误处理
+   * @private
+   * @description 配置全局错误处理中间件
+   */
+  _applyErrorHandling() {
+    this.app.use((req, res) => {
+      res.status(404).json(notFoundResponse(req));
+    });
+
+    this.app.use((err, req, res, next) => {
+      if (res.headersSent) return next(err);
+
+      const errorInfo = err?.stack ? this._parseErrorStack(err.stack) : { message: err?.message || err };
+      const requestInfo = `${req.method} ${req.originalUrl}`;
+      console.error(`[Global Error] ${requestInfo} - ${errorInfo.file}:${errorInfo.line || "?"} - ${errorInfo.message}`);
+
+      if (err?.isError && err.message) {
+        const statusCode = err.statusCode >= 500 ? 500 : 400;
+        console.error(`[Global Error Details] Code: ${err.code || 500}, Status: ${statusCode}`);
+        return res.status(statusCode).json({
+          success: false,
+          msg: err.message,
+          code: err.code || 500,
+          data: process.env.NODE_ENV === "development" ? { 
+            stack: err.stack,
+            file: errorInfo.file,
+            line: errorInfo.line,
+            column: errorInfo.column,
+            url: req.originalUrl,
+            method: req.method
+          } : {},
+        });
+      }
+
+      const parsedError = parseDatabaseError(err);
+      console.error(`[Global Error Details] Database Error - ${parsedError.msg}`);
+      res.status(parsedError.statusCode).json(errorResponse(err, req));
+    });
+  }
+
+  /**
+   * 解析错误堆栈
+   * @private
+   * @param {string} stack - 错误堆栈字符串
+   * @returns {Object} 解析后的错误信息
+   * @description 从错误堆栈中提取文件名、行号、列号等信息
+   */
+  _parseErrorStack(stack) {
+    if (!stack) return { message: '未知错误' };
+
+    const stackLines = stack.split('\n');
+    if (stackLines.length < 2) {
+      return { message: stackLines[0] || '未知错误' };
+    }
+
+    const errorLine = stackLines[1].trim();
+    const match = errorLine.match(/at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/);
+    
+    if (match) {
+      return {
+        message: stackLines[0] || '未知错误',
+        function: match[1],
+        file: match[2],
+        line: match[3],
+        column: match[4]
+      };
+    }
+
+    const fileMatch = errorLine.match(/at\s+(.+?):(\d+):(\d+)/);
+    if (fileMatch) {
+      return {
+        message: stackLines[0] || '未知错误',
+        file: fileMatch[1],
+        line: fileMatch[2],
+        column: fileMatch[3]
+      };
+    }
+
+    return { message: stackLines[0] || '未知错误', file: errorLine };
+  }
+
+  /**
+   * 启动服务器监听
+   * @async
+   * @private
+   * @returns {Promise<void>}
+   * @description 启动 HTTP 服务器监听指定端口
+   */
+  async _listen() {
+    return new Promise((resolve, reject) => {
+      const server = this.app.listen(this.options.port, () => {
+        console.log(`Server running on port ${this.options.port}`);
+        resolve(server);
+      });
+
+      server.on("error", reject);
+    });
+  }
+
+  /**
+   * 加载模块路由
+   * @async
+   * @returns {Promise<void>}
+   * @description 从 app/modules 目录加载所有模块的路由
+   */
+  async loadRouter() {
+    const configPath = path.join(Paths.appPath, "modules");
+    if (fs.existsSync(configPath)) {
+      const dirs = loaderSort(Chan.config.modules);
+      for (const item of dirs) {
+        let router = await importFile(`app/modules/${item}/router.js`);
+        router(this.app, this.router, Chan.config);
+      }
+    }
+  }
+
+  /**
+   * 加载公共路由
+   * @async
+   * @returns {Promise<void>}
+   * @description 加载 app/router.js 中的公共路由
+   */
+  async loadCommonRouter() {
+    let router = await importFile("app/router.js");
+    if (router) {
+      router(this.app, this.router, Chan.config);
+    }
+  }
+
+  /**
+   * 准备启动
+   * @param {Function} [cb] - 回调函数
+   * @description 在启动前执行回调，传递端口号
+   */
+  ready(cb) {
+    cb?.(this.options.port);
+  }
+}
+
+export default Chan;

package/base/Context.js

@@ -0,0 +1,78 @@
+/**
+ * 应用上下文类
+ * 用于存储和管理应用的配置和模型实例
+ */
+class AppContext {
+  /**
+   * 构造函数
+   * 初始化配置和模型的Map存储
+   */
+  constructor() {
+    this._config = new Map();
+    this._models = new Map();
+  }
+
+  /**
+   * 设置配置项
+   * @param {string} key - 配置键名
+   * @param {*} value - 配置值
+   */
+  set(key, value) {
+    this._config.set(key, value);
+  }
+
+  /**
+   * 获取配置项
+   * @param {string} key - 配置键名
+   * @param {*} defaultValue - 默认值
+   * @returns {*} 配置值或默认值
+   */
+  get(key, defaultValue) {
+    return this._config.get(key) ?? defaultValue;
+  }
+
+  /**
+   * 检查配置项是否存在
+   * @param {string} key - 配置键名
+   * @returns {boolean} 是否存在
+   */
+  has(key) {
+    return this._config.has(key);
+  }
+
+  /**
+   * 设置模型实例
+   * @param {string} name - 模型名称
+   * @param {Object} instance - 模型实例
+   */
+  setModel(name, instance) {
+    this._models.set(name, instance);
+  }
+
+  /**
+   * 获取模型实例
+   * @param {string} name - 模型名称
+   * @returns {Object|undefined} 模型实例
+   */
+  getModel(name) {
+    return this._models.get(name);
+  }
+
+  /**
+   * 获取所有模型实例
+   * @returns {Object} 包含所有模型的对象
+   */
+  getAllModels() {
+    return Object.fromEntries(this._models.entries());
+  }
+
+  /**
+   * 清空所有配置和模型
+   */
+  clear() {
+    this._config.clear();
+    this._models.clear();
+  }
+}
+
+export default AppContext;

package/base/Controller.js

@@ -0,0 +1,137 @@
+import { success, fail, error as responseError } from "../utils/response.js";
+
+/**
+ * 控制器基类
+ * 提供统一的响应格式和常用方法
+ */
+export default class Controller {
+  /**
+   * 构造函数
+   * @param {Object} context - 应用上下文实例
+   */
+  constructor(context = null) {
+    if (context) {
+      this.context = context;
+    } else if (global.appContext) {
+      this.context = global.appContext;
+    } else {
+      this.context = { get: () => null, set: () => null };
+    }
+  }
+
+  /**
+   * 标准化返回结果
+   * @private
+   * @param {*} result - 原始结果
+   * @param {string} defaultMsg - 默认消息
+   * @returns {Object} 标准化的结果对象
+   */
+  _normalizeResult(result, defaultMsg = "操作成功") {
+    if (result === null || result === undefined) {
+      return { success: false, code: 5001, msg: "Service 返回空值", data: {} };
+    }
+
+    if (typeof result === 'object' && 'success' in result) {
+      return result;
+    }
+
+    if (typeof result === 'object' || Array.isArray(result)) {
+      return { success: true, code: 200, msg: defaultMsg, data: result };
+    }
+
+    return { success: true, code: 200, msg: defaultMsg, data: result };
+  }
+
+  /**
+   * 返回成功响应
+   * @param {*} options - 响应选项或数据
+   * @param {*} options.data - 响应数据
+   * @param {string} options.msg - 响应消息，默认"操作成功"
+   * @returns {Object} 标准成功响应
+   */
+  success(options, msg = "操作成功") {
+    let data, message = msg, extra = {};
+
+    if (options === null || options === undefined) {
+      data = undefined;
+    } else if (typeof options === 'object' && options !== null && !Array.isArray(options)) {
+      if ('data' in options) {
+        data = options.data;
+        message = options.msg || msg;
+        extra = { ...options };
+        delete extra.data;
+        delete extra.msg;
+      } else if ('success' in options && 'code' in options) {
+        return options;
+      } else {
+        data = options;
+      }
+    } else {
+      data = options;
+    }
+
+    if (data instanceof Error) {
+      return this.error({ err: data });
+    }
+
+    const normalized = this._normalizeResult(data, message);
+    
+    if (!normalized.success) {
+      return this.fail({ msg: normalized.msg, data: normalized.data, code: normalized.code });
+    }
+
+    return {
+      success: true,
+      code: 200,
+      msg: normalized.msg,
+      data: normalized.data,
+      ...extra
+    };
+  }
+
+  /**
+   * 返回失败响应
+   * @param {Object} options - 响应选项
+   * @param {string} options.msg - 失败消息，默认"操作失败"
+   * @param {*} options.data - 响应数据
+   * @param {number} options.code - 错误码，默认201
+   * @returns {Object} 标准失败响应
+   */
+  fail({ msg = "操作失败", data = {}, code = 201 } = {}) {
+    return fail({ msg, data, code });
+  }
+
+  /**
+   * 返回错误响应
+   * @param {Object} options - 响应选项
+   * @param {Error} options.err - 错误对象
+   * @param {*} options.data - 响应数据
+   * @param {number} options.code - 错误码，默认500
+   * @returns {Object} 标准错误响应
+   */
+  error({ err, data = {}, code = 500 } = {}) {
+    return responseError({ err, data, code });
+  }
+
+  /**
+   * 返回分页响应
+   * @param {Array} list - 数据列表
+   * @param {number} total - 总记录数
+   * @param {number} current - 当前页码
+   * @param {number} pageSize - 每页大小
+   * @returns {Object} 标准分页响应
+   */
+  paginate(list, total, current, pageSize) {
+    return success({
+      data: {
+        list,
+        pagination: {
+          total,
+          current,
+          pageSize,
+          totalPages: Math.ceil(total / pageSize),
+        },
+      },
+    });
+  }
+}