chanjs 2.7.2 → 2.7.4

package/App.js

@@ -7,9 +7,13 @@ import DatabaseManager from "./base/Database.js";
 
 // 引入配置和工具
 import { Paths } from "./config/index.js";
-import { loadConfig, loaderSort, loadController } from "./helper/index.js";
-import { Cors, setBody, setCookie, setFavicon, setHeader, setStatic, setTemplate, waf, log } from "./middleware/index.js";
-import { notFoundResponse, parseDatabaseError, errorResponse } from "./helper/index.js";
+import { loadConfig, loaderSort, loadController } from "./loader/index.js";
+import { Cors, setBody, setCookie, setFavicon, setHeader, setStatic, setTemplate, waf, compress, log } from "./middleware/index.js";
+import { notFoundResponse, parseDatabaseError, errorResponse } from "./response/index.js";
+import { store } from "./storage/index.js";
+import { schedule } from "./schedule/schedule.js";
+import { sse } from "./realtime/sse.js";
+import { websocket } from "./realtime/websocket.js";
 import { importFile } from "./global/import.js";
 
 import "./global/index.js";
@@ -47,6 +51,10 @@ class Chan {
   async start() {
     //加载配置
     await this.config();
+    //暴露 Paths 到 Chan 静态属性（DI：业务侧通过 Chan.paths 或 this.paths 访问）
+    Chan.paths = Paths;
+    //初始化 Redis 适配器（WAF 封禁 / Rate Limit 共享存储）
+    await this.loadRedis();
     //加载数据库
     await this.loadDB();
     //加载扩展方法
@@ -59,8 +67,140 @@ class Chan {
     await this.loadRouter();
     await this.loadCommonRouter();
     this.useRouter();
-    //404 500 处理
+    //404 500 处理（放在最后，确保所有路由都已注册）
     this.setErrorHandler();
+    //执行 beforeStart 钩子（用户自定义的初始化逻辑）
+    await this._runBeforeStart();
+  }
+
+  /**
+   * 注册 beforeStart 钩子
+   * @param {Function} fn - 钩子函数（支持 async）
+   * @description 在 start() 流程末尾、run() 之前执行
+   * 适合做：缓存预热、定时任务注册、健康检查初始化等
+   * @example
+   * chan.beforeStart(async () => {
+   *   schedule.every('clean-log', 60000, cleanLogs);
+   * });
+   */
+  beforeStart(fn) {
+    if (typeof fn !== 'function') {
+      throw new Error('beforeStart 参数必须是函数');
+    }
+    if (!this._beforeStartHooks) this._beforeStartHooks = [];
+    this._beforeStartHooks.push(fn);
+  }
+
+  /**
+   * 执行 beforeStart 钩子
+   * @private
+   */
+  async _runBeforeStart() {
+    if (!this._beforeStartHooks || !this._beforeStartHooks.length) return;
+    for (const fn of this._beforeStartHooks) {
+      try {
+        await fn();
+      } catch (err) {
+        console.error('[Chan] beforeStart 钩子执行失败:', err.message);
+      }
+    }
+  }
+
+  /**
+   * 优雅停机
+   * @async
+   * @description 关闭 HTTP 服务、定时任务、数据库连接、Redis
+   * 监听 SIGTERM / SIGINT 信号自动触发
+   * @returns {Promise<void>}
+   */
+  async shutdown() {
+    if (this._shuttingDown) return;
+    this._shuttingDown = true;
+    console.log('[Chan] 开始优雅停机...');
+
+    // 5 秒强制退出兜底（原 30s 过长，连接已主动销毁，5s 足够收尾）
+    const forceExitTimer = setTimeout(() => {
+      console.error('[Chan] 优雅停机超时（5s），强制退出');
+      process.exit(1);
+    }, 5000);
+    forceExitTimer.unref?.();
+
+    try {
+      // 1. 停止接收新请求 + 主动销毁所有 keep-alive 连接
+      //    说明：server.close() 只停止 listen，会等所有现有连接关闭才回调，
+      //    浏览器默认 keep-alive 会导致 30s 超时，所以必须主动 destroy。
+      if (this.server) {
+        if (this._sockets && this._sockets.size > 0) {
+          for (const socket of this._sockets) {
+            try { socket.destroy(); } catch (e) { /* 忽略已关闭的 socket */ }
+          }
+          this._sockets.clear();
+        }
+        await new Promise(resolve => this.server.close(resolve));
+        console.log('[Chan] HTTP 服务已关闭');
+      }
+
+      // 2. 关闭实时通信（SSE / WebSocket，先于定时任务关闭，避免推送失败）
+      try {
+        sse.shutdown();
+      } catch (e) {
+        console.error('[Chan] 关闭 SSE 失败:', e.message);
+      }
+      try {
+        websocket.shutdown();
+      } catch (e) {
+        console.error('[Chan] 关闭 WebSocket 失败:', e.message);
+      }
+
+      // 3. 停止所有定时任务
+      try {
+        schedule.shutdown();
+      } catch (e) {
+        console.error('[Chan] 停止定时任务失败:', e.message);
+      }
+
+      // 4. 关闭数据库连接
+      try {
+        await this.dbManager.closeAll();
+      } catch (e) {
+        console.error('[Chan] 关闭数据库失败:', e.message);
+      }
+
+      // 5. 关闭 Redis / 存储适配层
+      try {
+        await store.close();
+      } catch (e) {
+        console.error('[Chan] 关闭存储适配层失败:', e.message);
+      }
+
+      console.log('[Chan] 优雅停机完成');
+    } finally {
+      clearTimeout(forceExitTimer);
+      process.exit(0);
+    }
+  }
+
+  /**
+   * 注册进程信号监听器（自动触发优雅停机）
+   * @private
+   */
+  _registerSignalHandlers() {
+    if (this._signalRegistered) return;
+    this._signalRegistered = true;
+
+    const handler = async (signal) => {
+      // 幂等守卫：首次信号触发停机，后续信号直接忽略，避免日志噪音
+      if (this._shuttingDown) {
+        // 第二次 ctrl+c：直接强制退出，让用户能快速中断
+        console.error(`[Chan] 再次收到 ${signal}，强制退出`);
+        process.exit(1);
+      }
+      console.log(`[Chan] 收到 ${signal} 信号`);
+      await this.shutdown();
+    };
+
+    process.on('SIGTERM', () => handler('SIGTERM'));
+    process.on('SIGINT', () => handler('SIGINT'));
   }
 
   /**
@@ -74,6 +214,27 @@ class Chan {
     Chan.config = config;
   }
 
+  /**
+   * 初始化存储适配层
+   * @async
+   * @description
+   * 根据 config.REDIS_ENABLED 决定使用 Redis 还是内存模式
+   * - Redis 启用且连接成功 → 使用 Redis 后端
+   * - Redis 未启用或连接失败 → 降级到内存模式（Map+TTL，上限 10 万条）
+   * WAF 封禁状态、Rate Limit 计数都依赖此适配层
+   */
+  async loadRedis() {
+    const config = Chan.config || {};
+    try {
+      await store.init({
+        REDIS_ENABLED: config.REDIS_ENABLED,
+        REDIS: config.REDIS,
+      });
+    } catch (err) {
+      console.warn(`[Chan] 存储适配层初始化失败，使用内存模式: ${err.message}`);
+    }
+  }
+
   /**
    * 加载数据库
    * @async
@@ -85,12 +246,8 @@ class Chan {
     for (const [index, item] of dbList.entries()) {
       const key = item.key || String(index);
       try {
-        const dbConfig = item;
-        if (!dbConfig) {
-          console.error(`[DB] 数据库 ${key} 未找到数据库配置`);
-          return;
-        };
-        const connection = this.dbManager.add(key, dbConfig, { isDefault: index === 0 });
+        // 已通过 dbList.entries() 拿到 item，无需再做 if (!dbConfig) return 死代码判断
+        const connection = this.dbManager.add(key, item, { isDefault: index === 0 });
         if (index === 0) {
           Chan.db = this.dbManager.get();
         }
@@ -172,6 +329,9 @@ class Chan {
     await waf(this.app, wafConfig);
     setFavicon(this.app);
     setStatic(this.app, statics);
+    // 响应压缩中间件：放在 setStatic 之后（静态资源已由 express.static 处理流式响应）、Cors 之前
+    // 跳过 SSE / WebSocket 升级请求，仅对可压缩文本类型且 > 1KB 的响应体压缩
+    this.app.use(compress());
     setCookie(this.app, cookieKey);
     setBody(this.app, BODY_LIMIT);
     Cors(this.app, cors);
@@ -184,9 +344,20 @@ class Chan {
    * 应用配置
    * @private
    * @description 设置 Express 应用配置
+   * trust proxy 根据 config.PROXY 动态设置，避免默认 true 导致 X-Forwarded-For 伪造
    */
   setApp() {
-    this.app.set("trust proxy", true);
+    const proxyConfig = Chan.config?.PROXY;
+    if (proxyConfig === 'true' || proxyConfig === true) {
+      // 信任所有代理（仅在反代可信时使用）
+      this.app.set("trust proxy", true);
+    } else if (proxyConfig === 'loopback' || !proxyConfig) {
+      // 默认仅信任本机回环代理
+      this.app.set("trust proxy", "loopback");
+    } else {
+      // 其他值按字面传入（IP / CIDR / 跳数）
+      this.app.set("trust proxy", proxyConfig);
+    }
   }
 
   /**
@@ -204,8 +375,8 @@ class Chan {
    * @description 配置全局错误处理中间件
    */
   setErrorHandler() {
-    //404
-    this.app.use((req, res) => {
+    //404（标准 Express 中间件签名，保留 next 参数）
+    this.app.use((req, res, next) => {
       res.status(404).json(notFoundResponse(req));
     });
 
@@ -302,16 +473,61 @@ class Chan {
   /**
    * 准备启动
    * @param {Function} [cb] - 回调函数
-   * @description 在启动前执行回调，传递端口号
+   * @description 启动 HTTP 服务，并按配置挂载 WebSocket（SSE 由业务侧通过 sse.middleware() 注册路由）
    */
   run(cb) {
-    this.app.listen(Chan.config.PORT, () => {
+    this.server = this.app.listen(Chan.config.PORT, () => {
         console.log(`Server running on port ${Chan.config.PORT}`);
         cb?.(Chan.config.PORT);
       });
+
+    // 跟踪所有 HTTP socket，用于优雅停机时主动销毁（避免 keep-alive 卡住 server.close）
+    this._sockets = new Set();
+    this.server.on('connection', (socket) => {
+      this._sockets.add(socket);
+      socket.on('close', () => this._sockets.delete(socket));
+    });
+
+    // 按配置挂载 WebSocket（config.WEBSOCKET.enabled = true 时启用）
+    this._attachWebSocket();
+    // 注册 SIGTERM / SIGINT 信号处理，支持优雅停机
+    this._registerSignalHandlers();
+  }
+
+  /**
+   * 挂载 WebSocket 服务到 HTTP server
+   * @private
+   * @description 根据 config.WEBSOCKET 配置自动挂载，业务侧通过 Chan.websocket 使用
+   * @example
+   * // config.js
+   * module.exports = {
+   *   WEBSOCKET: { enabled: true, path: '/ws', heartbeatInterval: 30000 }
+   * };
+   * // 业务侧
+   * import { websocket } from 'chanjs';
+   * websocket.on('chat', (socket, payload) => { ... });
+   */
+  _attachWebSocket() {
+    const wsConfig = Chan.config?.WEBSOCKET || {};
+    if (!wsConfig.enabled) return;
+
+    try {
+      websocket.attach(this.server, {
+        path: wsConfig.path || '/ws',
+        heartbeatInterval: wsConfig.heartbeatInterval,
+        verifyClient: wsConfig.verifyClient,
+        onConnection: wsConfig.onConnection,
+      });
+      // 暴露到 Chan 静态属性，便于业务侧通过 import Chan 访问
+      Chan.websocket = websocket;
+    } catch (err) {
+      console.error('[Chan] WebSocket 挂载失败:', err.message);
+    }
   }
 }
 
-global.Chan = Chan;
+// 不再使用 global.Chan 全局污染
+// 业务侧通过 `import Chan from 'chanjs'` 获取同一个类引用（ESM 模块缓存保证单例）
+// 框架内部直接使用类名 Chan（同一模块作用域）
 
 export default Chan;

package/base/Aop.js

@@ -9,6 +9,8 @@ export class Aop {
   static TYPES = new Set(['type', 'enabled']);
   // 支持的切面类型（仅保留常用的3种）
   static SUPPORTED_TYPES = new Set(['before', 'after', 'error']);
+  // 幂等标记 Symbol，避免 wrap 多次嵌套包装
+  static WRAP_FLAG = Symbol('aop.wrapped');
 
   constructor() {
     this.aspects = new Map();
@@ -66,6 +68,9 @@ export class Aop {
    * @param {object} config - 切面配置 { methodName: [{ type: 'before', enabled: true, log: true }] }
    * @returns {object} - 绑定后的实例对象
    * @throws {TypeError} - 入参类型错误时抛出
+   * @description
+   * 幂等性：用 Symbol 标记已包装的方法，避免多次调用 wrap 导致嵌套
+   * 同一方法第二次 wrap 会跳过，防止切面函数被重复执行
    */
   wrap(instance, config) {
     if (typeof instance !== 'object' || instance === null) {
@@ -82,6 +87,12 @@ export class Aop {
         return;
       }
 
+      // 幂等检查：已包装过的方法直接跳过，避免多次 wrap 嵌套
+      if (originalMethod[Aop.WRAP_FLAG]) {
+        console.warn(`[AOP警告] 方法 ${methodName} 已包装过切面，跳过重复绑定`);
+        return;
+      }
+
       // 统一规则为数组 + 过滤禁用规则 + 过滤不支持的类型
       const ruleList = Array.isArray(rules) ? rules : [rules];
       const validRules = ruleList.filter(rule => {
@@ -92,17 +103,17 @@ export class Aop {
       if (validRules.length === 0) return;
 
       // 包装原方法（仅保留 before/after/error 逻辑）
-      instance[methodName] = async (...args) => {
+      const wrapped = async (...args) => {
         const ctx = instance;
         let result;
 
         try {
           // 执行前置切面
           await this._executeAspectByType(ctx, validRules, 'before', args, originalMethod);
-          
+
           // 执行原方法
           result = await Reflect.apply(originalMethod, ctx, args);
-          
+
           // 执行后置切面（仅无异常时执行）
           await this._executeAspectByType(ctx, validRules, 'after', args, originalMethod, result);
         } catch (error) {
@@ -113,6 +124,12 @@ export class Aop {
 
         return result;
       };
+
+      // 打幂等标记，防止重复 wrap
+      wrapped[Aop.WRAP_FLAG] = true;
+      // 保留原方法名，便于调试
+      Object.defineProperty(wrapped, 'name', { value: originalMethod.name, configurable: true });
+      instance[methodName] = wrapped;
     });
 
     return instance;

package/base/Container.js

@@ -1,7 +1,31 @@
 import fs from 'fs';
 import path from 'path';
 import { Paths } from '../config/paths.js';
+import Chan from '../App.js';
 
+/**
+ * 容器基类（依赖注入容器）
+ *
+ * ============================================================
+ * 设计说明
+ * ============================================================
+ * 不再使用 global.Chan 全局污染。
+ * 通过 import Chan 获取应用类引用，所有资源（config/db/paths 等）
+ * 都通过 Chan 类的静态属性动态访问，避免构造时快照导致的不同步问题。
+ *
+ * 子类（Controller/Repository）可通过以下方式获取应用资源：
+ * - this.app           → Chan 类本身（静态属性容器）
+ * - this.app.config    → 应用配置
+ * - this.app.db        → 默认数据库连接
+ * - this.app.dbManager → 数据库连接管理器
+ * - this.app.paths     → 路径配置（兼容 Chan.paths）
+ *
+ * ============================================================
+ * DI 方法
+ * ============================================================
+ * - get(moduleName, fileName)  → 加载业务模块组件（service/controller）
+ * - getResource(name)           → 获取应用级资源（config/db/dbManager/paths）
+ */
 export class Container {
   constructor(type = 'service') {
     this.map = new Map();
@@ -9,8 +33,41 @@ export class Container {
     this.type = type;
     // modules 目录路径
     this.baseDir = Paths.modulesPath;
-    // 只添加 config 属性，全局默认的配置
-    this.config = Chan.config;
+    // 应用类引用（DI 核心：通过它访问 config/db 等静态资源）
+    this.app = Chan;
+  }
+
+  /**
+   * 获取应用级资源（显式 DI）
+   * @param {string} name - 资源名：'config' | 'db' | 'dbManager' | 'paths'
+   * @returns {*} 对应的资源
+   * @example
+   * const config = this.getResource('config');
+   * const db = this.getResource('db');
+   */
+  getResource(name) {
+    return Chan[name];
+  }
+
+  /**
+   * config 快捷访问（getter 动态读取，避免快照不同步）
+   */
+  get config() {
+    return Chan.config;
+  }
+
+  /**
+   * db 快捷访问（getter 动态读取）
+   */
+  get db() {
+    return Chan.db;
+  }
+
+  /**
+   * paths 快捷访问（getter 动态读取）
+   */
+  get paths() {
+    return Chan.paths || Paths;
   }
 
   /**
@@ -58,8 +115,19 @@ export class Container {
    * @param {string} moduleName - 模块名 ，例如：'web','api'
    * @param {string} fileName - 文件名
    * @returns {Promise<any>} - 组件实例
+   * @description
+   * 安全改进：
+   * - 名称白名单校验（仅允许字母开头、字母数字下划线/横线），拒绝路径注入
+   * - 解析后路径必须仍在 baseDir 内，防止路径越界
+   * - 用 fs.promises.access 替代 existsSync，避免同步 IO 阻塞事件循环
    */
   async loadFile(moduleName, fileName) {
+    // 模块/文件名白名单：字母开头，允许字母数字下划线横线
+    const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+    if (!NAME_REGEX.test(moduleName) || !NAME_REGEX.test(fileName)) {
+      throw new Error(`非法模块/文件名: ${moduleName}/${fileName}`);
+    }
+
     const filePath = path.resolve(
       this.baseDir,
       moduleName,
@@ -67,7 +135,16 @@ export class Container {
       `${fileName}.js`
     );
 
-    if (!fs.existsSync(filePath)) {
+    // 路径越界检查：解析后必须仍在 baseDir 内
+    const rel = path.relative(this.baseDir, filePath);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`路径越界: ${filePath}`);
+    }
+
+    // 异步检查文件存在性，避免同步 IO
+    try {
+      await fs.promises.access(filePath, fs.constants.R_OK);
+    } catch (e) {
       console.log(`模块 ${moduleName} 下 ${this.type} 目录中未找到文件：${fileName}.js`);
       return null;
     }

package/base/Controller.js

@@ -1,9 +1,23 @@
-import { success, fail } from "../helper/response.js";
+import { success, fail } from "../response/response.js";
 import Container from "./Container.js";
 
 /**
  * 控制器基类
  * 提供统一的响应格式和常用方法
+ *
+ * ============================================================
+ * 响应格式（三层 code 体系）
+ * ============================================================
+ * 所有响应都遵循：{ success, code, msg, data }
+ * - code: 0 成功 / 1xxx 业务 / 5xxx 系统 / 6xxx 数据库
+ * - HTTP Status 由网关/Express 控制，与业务 code 解耦
+ *
+ * 使用示例：
+ * this.success(data)                       // → code: 0
+ * this.success({ data, msg: '创建成功' })   // → code: 0
+ * this.fail({ msg: '栏目下存在文章' })     // → code: 1008 业务失败
+ * this.fail({ msg: '参数缺失', code: 1007 }) // → code: 1007
+ * this.fail('密码错误')                    // 字符串简写，→ code: 1008
  */
 export default class Controller extends Container {
   constructor() {
@@ -15,8 +29,8 @@ export default class Controller extends Container {
    * 返回成功响应
    * @param {Object} options - 响应选项
    * @param {*} options.data - 响应数据
-   * @param {string} options.msg - 响应消息，默认"操作成功"
-   * @returns {Object} 标准成功响应
+   * @param {string} [options.msg="操作成功"] - 响应消息
+   * @returns {Object} 标准成功响应，code = 0
    */
   success({ data, msg = "操作成功" } = {}) {
     return success({ data, msg });
@@ -24,13 +38,28 @@ export default class Controller extends Container {
 
   /**
    * 返回失败响应
-   * @param {Object} options - 响应选项
-   * @param {string} options.msg - 失败消息，默认"操作失败"
-   * @param {*} options.data - 响应数据
-   * @param {number} options.code - 错误码，默认201
+   * @param {Object|string} options - 响应选项，或失败消息字符串（简写）
+   * @param {string} [options.msg="操作失败"] - 失败消息
+   * @param {*} [options.data={}] - 响应数据
+   * @param {number} [options.code=1008] - 业务 code，默认 1008（业务处理失败）
    * @returns {Object} 标准失败响应
+   * @description
+   * 兼容两种调用方式：
+   * - 对象：this.fail({ msg: '...', code: 1007 })
+   * - 字符串简写：this.fail('密码错误')  // 等价于 this.fail({ msg: '密码错误' })
+   *
+   * 默认 code = 1008（业务处理失败）
+   * 业务方可指定 code：
+   * - 1001 认证失败 / 1002 token 过期 / 1003 权限不足
+   * - 1004 资源不存在 / 1005 资源已存在
+   * - 1006 参数无效 / 1007 参数缺失
+   * - 1008 业务处理失败（通用兜底）
    */
-  fail({ msg = "操作失败", data = {}, code = 201 } = {}) {
-    return fail({ msg, data, code });
+  fail(options = {}) {
+    // 字符串简写：this.fail('错误消息') → this.fail({ msg: '错误消息' })
+    if (typeof options === 'string') {
+      return fail({ msg: options });
+    }
+    return fail(options);
   }
 }

package/base/Database.js

@@ -78,6 +78,56 @@ class DatabaseManager {
     }
   }
 
+  /**
+   * 关闭所有数据库连接（优雅停机使用）
+   * 单个连接关闭失败不影响其他连接
+   * @returns {Promise<Array<{name:string, success:boolean, error?:string}>>} 每个连接的关闭结果
+   */
+  async closeAll() {
+    const results = [];
+    for (const [name, conn] of this._connections) {
+      try {
+        await conn.destroy();
+        results.push({ name, success: true });
+      } catch (err) {
+        results.push({ name, success: false, error: err.message });
+        console.error(`[Database] 关闭连接 ${name} 失败:`, err.message);
+      }
+    }
+    this._connections.clear();
+    console.log(`[Database] 已关闭所有连接（共 ${results.length} 个）`);
+    return results;
+  }
+
+  /**
+   * 心跳检查（单个连接）
+   * @param {string} [name] - 连接名称，默认检查默认连接
+   * @returns {Promise<boolean>} 是否健康
+   */
+  async ping(name = this._defaultName) {
+    const conn = this._connections.get(name);
+    if (!conn) return false;
+    try {
+      // 用最简 SELECT 1 触发一次实际查询，验证连接可用
+      await conn.raw('SELECT 1');
+      return true;
+    } catch (err) {
+      console.error(`[Database] ping ${name} 失败:`, err.message);
+      return false;
+    }
+  }
+
+  /**
+   * 获取所有连接状态（健康检查 / 监控使用）
+   * @returns {Array<{name:string, isDefault:boolean}>} 连接列表
+   */
+  getStatus() {
+    return Array.from(this._connections.keys()).map(name => ({
+      name,
+      isDefault: name === this._defaultName,
+    }));
+  }
+
 }
 
 export default DatabaseManager;

package/base/Event.js

@@ -1,8 +1,20 @@
 import { EventEmitter } from 'events';
 
+/**
+ * 默认最大监听器数量上限，防止业务侧泄漏过多监听器导致内存警告
+ */
+const DEFAULT_MAX_LISTENERS = 50;
+
 export class Event extends EventEmitter {
   constructor() {
     super();
+    // 设置最大监听器数量，避免业务侧泄漏导致 process 警告
+    this.setMaxListeners(DEFAULT_MAX_LISTENERS);
+    // 兜底 error 监听器：未注册 error 监听时 EventEmitter 默认会抛出并崩溃进程
+    // 这里注册一个仅打印日志的 error 处理器，确保 unhandled error 不会让进程退出
+    this.on('error', (err) => {
+      console.error('[Event] 未处理的 error 事件:', err?.message || err);
+    });
   }
 
   /**