chanjs 2.7.7 → 2.7.10

package/core/App.js

@@ -12,12 +12,22 @@ import { loadModuleRouter, loadCommonRouter } from "./bootstrap/router-loader.js
 import { registerErrorHandler } from "./bootstrap/error-handler.js";
 import { runHooks } from "./bootstrap/hook-runner.js";
 import { loadDotEnv } from "../config/index.js";
+import { event } from "./EventBus.js";
+import { initLang } from "./Lang.js";
+import Task from "./Task.js";
 
 // 初始化环境变量
 loadDotEnv();
 
 /**
  * Chan 应用核心类
+ *
+ * 聚合框架基础设施：
+ * - app/router：Express 实例与路由
+ * - dbManager：多连接数据库管理
+ * - event：全局事件总线（EventBus 单例）
+ * - task：定时任务管理器
+ * - lang：i18next 实例（启动时初始化）
  */
 export default class Chan {
   constructor() {
@@ -29,6 +39,14 @@ export default class Chan {
     this.paths = Paths;
     this.db = null;
     this.hooks = [];
+
+    // 框架基础设施（全局共享）事件总线单例，任意模块 import { event } from "chanjs" 即同一实例
+    this.event = event; 
+    // 定时任务管理器，停机时由 signal.js 调用 stopAll()
+    this.task = new Task();      
+    // i18next 实例，启动流程中初始化
+    this.lang = null;            
+    // HTTP 服务实例，启动后赋值
     this.server = null;
   }
 
@@ -37,6 +55,9 @@ export default class Chan {
     await this.#loadConfig();
     logger.info("[Chan] 配置加载完成");
 
+    await this.#initLang();
+    logger.info("[Chan] i18n 初始化完成");
+
     await this.#initStore();
     logger.info("[Chan] 缓存初始化完成");
 
@@ -94,6 +115,20 @@ export default class Chan {
     this.config = await loadConfig();
   }
 
+  /**
+   * 初始化 i18n
+   * - 默认语言：优先配置 LOCALE，否则回退 zh-CN
+   * - 失败不阻断启动，降级为仅支持默认语言
+   */
+  async #initLang() {
+    const locale = this.config?.LOCALE || "zh-CN";
+    try {
+      this.lang = await initLang(locale);
+    } catch (err) {
+      logger.warn(`[Chan] i18n 初始化失败，降级默认语言：${err.message}`);
+    }
+  }
+
   async #initStore() {
     const cfg = this.config;
     try {

package/core/Container.js

@@ -1,7 +1,8 @@
-import fs from 'fs';
-import path from 'path';
-import { Paths } from '../utils/paths.js';
-import { BaseComponent } from './BaseComponent.js';
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+import { Paths } from "../utils/paths.js";
+import { BaseComponent } from "./BaseComponent.js";
 import logger from "../utils/logger.js";
 
 const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
@@ -11,7 +12,7 @@ const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
  * 继承 BaseComponent 获得 app/config/db 访问，额外提供组件加载能力
  */
 export class Container extends BaseComponent {
-  constructor(type = 'service') {
+  constructor(type = "service") {
     super();
     this._componentCache = new Map();
     this._type = type;
@@ -19,49 +20,75 @@ export class Container extends BaseComponent {
   }
 
   /**
-   * 按需获取组件实例，自动缓存
-   * @param {string} moduleName 模块名
-   * @param {string} fileName 组件文件名（不含 .js）
+   * 按需获取组件实例
+   * - 成功：永久缓存（进程生命周期内不失效）
+   * - 缺失：不缓存，每次实时探测，文件新增后立即感知
+   * - 跨模块/跨类型：默认取本容器类型（controller/service），可传 type 覆盖，
+   *   例如 Controller 里取其他模块的 Service：await this.get("book", "Book", "service")
+   * @param {string} moduleName - 模块名
+   * @param {string} fileName - 组件文件名（不含 .js）
+   * @param {("controller"|"service")} [type=this._type] - 组件类型，默认本容器类型
+   * @returns {Promise<object|null>}
    */
-  async get(moduleName, fileName) {
-    const cacheKey = `${moduleName}.${fileName}`;
-    if (this._componentCache.has(cacheKey)) return this._componentCache.get(cacheKey);
+  async get(moduleName, fileName, type = this._type) {
+    const cacheKey = `${type}.${moduleName}.${fileName}`;
+    const hit = this._componentCache.get(cacheKey);
 
+    // 命中成功缓存，直接返回
+    if (hit) return hit;
+
+    // 未命中，实时加载
+    let instance;
     try {
-      const instance = await this._loadFile(moduleName, fileName);
-      if (!instance) logger.info(`[Container] ${moduleName}/${this._type}/${fileName}.js 导出实例为空`);
-      return instance;
+      instance = await this._loadFile(moduleName, fileName, type);
     } catch (err) {
-      logger.error(`[Container] 加载组件失败 ${moduleName}/${fileName}：${err.message}`);
-      return null;
+      logger.error(`[Container] 加载组件失败 ${moduleName}/${fileName}: ${err.message}`);
+      instance = null;
+    }
+
+    if (instance) {
+      // 成功才缓存，永久有效
+      this._componentCache.set(cacheKey, instance);
+    } else {
+      logger.info(`[Container] ${moduleName}/${type}/${fileName}.js 不存在`);
     }
+    return instance;
   }
 
-  /** 物理加载文件、导入模块、安全校验 */
-  async _loadFile(moduleName, fileName) {
-    const cacheKey = `${moduleName}.${fileName}`;
+  /** 手动清除指定组件缓存 */
+  invalidate(moduleName, fileName, type = this._type) {
+    this._componentCache.delete(`${type}.${moduleName}.${fileName}`);
+  }
 
-    if (!NAME_REGEX.test(moduleName) || !NAME_REGEX.test(fileName)) {
+  /** 清除全部缓存 */
+  invalidateAll() {
+    this._componentCache.clear();
+  }
+
+  /**
+   * 物理加载文件、导入模块、安全校验
+   * @private
+   */
+  async _loadFile(moduleName, fileName, type = this._type) {
+    if (!NAME_REGEX.test(moduleName) || !NAME_REGEX.test(fileName) || !NAME_REGEX.test(type)) {
       throw new Error(`非法名称 ${moduleName}/${fileName}`);
     }
 
-    const filePath = path.resolve(this._baseDir, moduleName, this._type, `${fileName}.js`);
-    const relativePath = path.relative(this._baseDir, filePath);
-    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
-      throw new Error(`路径越界拦截：${filePath}`);
+    const filePath = path.resolve(this._baseDir, moduleName, type, `${fileName}.js`);
+    const rel = path.relative(this._baseDir, filePath);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+      throw new Error(`路径越界: ${filePath}`);
     }
 
     try {
       await fs.promises.access(filePath, fs.constants.R_OK);
     } catch {
-      logger.info(`[Container] 文件不存在：${moduleName}/${this._type}/${fileName}.js`);
       return null;
     }
 
-    const mod = await import(`file://${filePath}`);
-    const instance = mod.default;
-    this._componentCache.set(cacheKey, instance);
-    return instance;
+    // 统一 pathToFileURL（与 loader.js 一致，Windows/跨盘安全）
+    const mod = await import(pathToFileURL(filePath).href);
+    return mod.default;
   }
 }
 

package/core/Database.js

@@ -2,36 +2,87 @@ import knex from "knex";
 import logger from "../utils/logger.js";
 
 const DEFAULT_NAME = "default";
+const DEFAULT_SLOW_THRESHOLD = 200;  // 慢查询阈值（ms），可运行时调整
 
 /**
- * 多Knex连接管理器，统一管理连接、心跳、批量销毁
+ * 多 Knex 连接管理器：统一管理连接、心跳、批量销毁、慢查询监控。
+ *
+ * - 连接注册：首个连接或 isDefault=true 自动设为默认
+ * - 健康缓存：error-handler 实时更新，鉴权层廉价区分「未登录」与「库挂了」
+ * - 慢查询：监听 knex query 事件，超过阈值记 warn 日志（含 SQL 与耗时）
+ * - 错误监控：监听 query-error 事件，记录失败 SQL 便于排查
  */
 class DatabaseManager {
   constructor() {
+    /** @type {Map<string, import("knex").Knex>} */
     this._connections = new Map();
     this._defaultName = DEFAULT_NAME;
-    // 健康缓存：运行时由 error-handler 实时更新，用于鉴权层廉价区分「用户未登录」与「库挂了」
+    /** 健康缓存：运行时由 error-handler 实时更新 */
     this._health = new Map();
+    /** 慢查询阈值（ms），超过则记 warn 日志 */
+    this._slowThreshold = DEFAULT_SLOW_THRESHOLD;
+  }
+
+  /**
+   * 设置慢查询阈值（运行时动态调整）
+   * @param {number} ms - 阈值毫秒数
+   */
+  setSlowThreshold(ms) {
+    if (typeof ms === "number" && ms > 0) this._slowThreshold = ms;
   }
 
   /**
    * 添加数据库连接，首个连接 / isDefault=true 自动设为默认
-   * @param {string} name 连接标识
-   * @param {object} config Knex配置
-   * @param {{isDefault?: boolean}} opts
-   * @returns {knex.Knex}
+   * @param {string} name - 连接标识
+   * @param {object} config - Knex 配置
+   * @param {{isDefault?: boolean}} [opts]
+   * @returns {import("knex").Knex}
    */
   add(name, config, { isDefault = false } = {}) {
     const conn = knex(config);
     this._connections.set(name, conn);
     if (isDefault || this._connections.size === 1) this._defaultName = name;
+
+    // 挂载慢查询与错误监控（按连接隔离，互不影响）
+    this._attachMonitoring(name, conn);
     return conn;
   }
 
+  /**
+   * 挂载 knex 事件监控
+   * - query: 记录 SQL 执行起点
+   * - query-response: 计算耗时，超阈值记慢查询日志
+   * - query-error: 记录失败 SQL 与错误信息
+   * @private
+   */
+  _attachMonitoring(name, conn) {
+    const startTimes = new Map();
+
+    conn.on("query", (data) => {
+      startTimes.set(data.__knexUid, Date.now());
+    });
+
+    conn.on("query-response", (_response, data) => {
+      const startedAt = startTimes.get(data.__knexUid);
+      if (!startedAt) return;
+      startTimes.delete(data.__knexUid);
+
+      const elapsed = Date.now() - startedAt;
+      if (elapsed >= this._slowThreshold) {
+        logger.warn(`[Database] 慢查询 ${name} ${elapsed}ms: ${data.sql}`);
+      }
+    });
+
+    conn.on("query-error", (err, data) => {
+      startTimes.delete(data?.__knexUid);
+      logger.error(`[Database] 查询失败 ${name}: ${data?.sql || ""}`, err);
+    });
+  }
+
   /**
    * 获取指定连接，不存在抛异常
    * @param {string} [name=this._defaultName]
-   * @returns {knex.Knex}
+   * @returns {import("knex").Knex}
    */
   get(name = this._defaultName) {
     const conn = this._connections.get(name);
@@ -90,4 +141,3 @@ class DatabaseManager {
 }
 
 export default DatabaseManager;
-

package/core/EventBus.js

@@ -0,0 +1,88 @@
+import { EventEmitter } from "events";
+
+/**
+ * 事件总线：基于 Node 内置 EventEmitter 的轻量封装。
+ *
+ * 全局实例 event 供中间件/定时任务/工具函数使用；
+ * App 实例 this.event 指向同一全局实例；
+ * 需要隔离时 new EventBus() 创建独立实例。
+ *
+ * @example
+ * import { event } from "chanjs";
+ * const off = event.on("user.login", (uid) => { ... });
+ * event.emit("user.login", 1001);
+ * off(); // 取消监听
+ */
+export class EventBus {
+  constructor() {
+    this._emitter = new EventEmitter();
+    this._emitter.setMaxListeners(50);
+  }
+
+  /**
+   * 注册监听器，返回取消函数
+   * @param {string} event - 事件名
+   * @param {(...args: any[]) => void} listener - 监听回调
+   * @returns {() => void} 取消监听函数
+   */
+  on(event, listener) {
+    this._emitter.on(event, listener);
+    return () => this._emitter.off(event, listener);
+  }
+
+  /**
+   * 只监听一次，触发后自动移除
+   * @param {string} event - 事件名
+   * @param {(...args: any[]) => void} listener - 监听回调
+   */
+  once(event, listener) {
+    this._emitter.once(event, listener);
+  }
+
+  /**
+   * 触发事件（同步执行全部监听器）
+   * @param {string} event - 事件名
+   * @param {...any} args - 传递给监听器的参数
+   */
+  emit(event, ...args) {
+    this._emitter.emit(event, ...args);
+  }
+
+  /**
+   * 移除指定监听器
+   * @param {string} event - 事件名
+   * @param {Function} listener - 要移除的回调引用
+   */
+  off(event, listener) {
+    this._emitter.off(event, listener);
+  }
+
+  /**
+   * 移除某事件的全部监听器
+   * @param {string} event - 事件名
+   */
+  removeAll(event) {
+    this._emitter.removeAllListeners(event);
+  }
+
+  /**
+   * 获取某事件的监听器数量
+   * @param {string} event - 事件名
+   * @returns {number}
+   */
+  count(event) {
+    return this._emitter.listenerCount(event);
+  }
+
+  /**
+   * 移除所有事件的全部监听器（优雅停机时调用，防内存泄漏）
+   */
+  destroy() {
+    this._emitter.removeAllListeners();
+  }
+}
+
+/** 全局共享实例：任何模块 import { event } from "chanjs" 即可用 */
+export const event = new EventBus();
+
+export default event;

package/core/Lang.js

@@ -0,0 +1,56 @@
+import fs from "fs";
+import path from "path";
+import i18next from "i18next";
+import { Paths } from "../utils/paths.js";
+
+const FALLBACK = "zh-CN";
+const LOCALE_REGEX = /^[a-zA-Z_-]+$/;
+
+/**
+ * 初始化 i18n（基于 i18next）
+ *
+ * 启动时扫描 lang/ 目录，加载全部 locale 的 JSON 资源到内存。
+ * 运行时通过 i18next.t("key") 查找，O(1) 复杂度，零 I/O 开销。
+ *
+ * @param {string} [locale="zh-CN"] - 默认语言
+ * @returns {Promise<typeof i18next>} i18next 实例
+ *
+ * @example
+ * // lang/zh-CN/common.json: { "user.welcome": "欢迎，{{name}}" }
+ * i18next.t("user.welcome", { name: "张三" });  // → "欢迎，张三"
+ */
+export async function initLang(locale = FALLBACK) {
+  const langDir = path.join(Paths.rootPath, "lang");
+  /** @type {Record<string, Record<string, object>>} resources[locale][namespace] */
+  const resources = {};
+
+  if (fs.existsSync(langDir)) {
+    for (const loc of fs.readdirSync(langDir)) {
+      if (!LOCALE_REGEX.test(loc)) continue;
+      const locDir = path.join(langDir, loc);
+      if (!fs.statSync(locDir).isDirectory()) continue;
+
+      resources[loc] = {};
+      for (const file of fs.readdirSync(locDir).filter(f => f.endsWith(".json"))) {
+        const ns = file.replace(".json", "");
+        try {
+          resources[loc][ns] = JSON.parse(fs.readFileSync(path.join(locDir, file), "utf-8"));
+        } catch {
+          // 单文件解析失败跳过，不阻断启动
+        }
+      }
+    }
+  }
+
+  await i18next.init({
+    lng: locale,
+    fallbackLng: FALLBACK,
+    resources,
+    defaultNS: "common",
+    interpolation: { escapeValue: false },  // 后端不转义
+  });
+
+  return i18next;
+}
+
+export default initLang;

package/core/Repository.js

@@ -10,6 +10,22 @@ import {
 const SORT_FIELD_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 const OPERATORS = { $like:'like', $gt:'>', $gte:'>=', $lt:'<', $lte:'<=', $ne:'<>' };
 
+/** 查询条件是否存在至少一个合法字段 */
+const hasValidQueryField = query =>
+  Object.keys(query).some(f => SORT_FIELD_REGEX.test(f));
+
+/**
+ * 查询条件全部非法时 fail-closed 拒绝（与 del/update 防御一致），
+ * 避免 applyQuery 静默丢弃全部字段后退化成「无 WHERE 全表查询」导致数据泄露。
+ * @returns {null | {success:false,code:number,msg:string,data:{}}} 校验通过返回 null，否则返回错误体
+ */
+const guardInvalidQuery = query => {
+  if (query && Object.keys(query).length && !hasValidQueryField(query)) {
+    return { success: false, code: CODE_PARAM_INVALID, msg: "查询条件非法", data: {} };
+  }
+  return null;
+};
+
 /**
  * 拼接查询条件，支持操作符/等值/数组in
  * @param {import('knex').Knex.QueryBuilder} dbQuery
@@ -123,12 +139,16 @@ class Repository extends BaseComponent {
 
   /** 查询全部，默认上限1000条 */
   async all({ query={}, sort={}, fields=[], limit=1000 }={}) {
+    const guard = guardInvalidQuery(query);
+    if (guard) return guard;
     const list = await this._buildBaseQuery({query,sort,fields}).limit(limit);
     return { success:true, code:CODE_OK, msg:"查询成功", data: list };
   }
 
   /** 分页偏移查询 */
   async find({ query={}, sort={}, fields=[], limit, offset }={}) {
+    const guard = guardInvalidQuery(query);
+    if (guard) return guard;
     let q = this._buildBaseQuery({query,sort,fields});
     typeof offset === 'number' && (q = q.offset(offset));
     typeof limit === 'number' && (q = q.limit(limit));
@@ -137,6 +157,8 @@ class Repository extends BaseComponent {
 
   /** 查询单条记录 */
   async findOne({ query={}, fields=[] }={}) {
+    const guard = guardInvalidQuery(query);
+    if (guard) return guard;
     const row = await this._buildBaseQuery({query,fields}).first();
     if (!row) return { success:false, code:CODE_NOT_FOUND, msg:"记录不存在", data:null };
     return { success:true, code:CODE_OK, msg:"查询成功", data: row };
@@ -248,8 +270,12 @@ class Repository extends BaseComponent {
    */
   async _doPaginate({ current=1, pageSize=10, query={}, sort={}, field=[] }={}) {
     this._checkDB();
+    const guard = guardInvalidQuery(query);
+    if (guard) return guard;
+    // 页码边界保护：current<=0 会生成负 offset 让 MySQL 直接语法报错
+    const currentPage = Math.max(1, Math.floor(Number(current) || 1));
     const size = Math.min(Math.max(pageSize, 1), this.limit);
-    const offset = (current - 1) * size;
+    const offset = (currentPage - 1) * size;
     const countQ = applyQuery(this.db(this.tableName), query);
     const [totalRow, list] = await Promise.all([
       countQ.count("* as total").first(),
@@ -263,7 +289,7 @@ class Repository extends BaseComponent {
       data: {
         list,
         total,
-        current,
+        current: currentPage,
         pageSize: size,
         totalPages: Math.ceil(total / size)
       }
@@ -278,6 +304,8 @@ class Repository extends BaseComponent {
   /** 统计符合条件记录行数 */
   async count(query={}) {
     this._checkDB();
+    const guard = guardInvalidQuery(query);
+    if (guard) return guard;
     const res = await applyQuery(this.db(this.tableName), query).count("* as total").first();
     return { success:true, code:CODE_OK, msg:"统计成功", data:{ count: Number(res?.total ?? 0) } };
   }
@@ -285,6 +313,8 @@ class Repository extends BaseComponent {
   /** 判断查询条件下记录是否存在 */
   async exists(query={}) {
     this._checkDB();
+    const guard = guardInvalidQuery(query);
+    if (guard) return guard;
     const row = await applyQuery(this.db(this.tableName), query).first();
     return { success:true, code:CODE_OK, msg:"检查成功", data:{ exists: !!row } };
   }
@@ -296,6 +326,8 @@ class Repository extends BaseComponent {
       logger.warn(`[Repository] 非法联表/字段：${joinTable}/${localField}/${foreignField}`);
       return { success: false, code: CODE_PARAM_INVALID, msg: "非法联表或字段", data: null };
     }
+    const guard = guardInvalidQuery(query);
+    if (guard) return guard;
     const select = fields.length
       ? fields.filter(f => SORT_FIELD_REGEX.test(f) || f === '*')
       : [`${this.tableName}.*`];

package/core/Task.js

@@ -0,0 +1,87 @@
+import cron from "node-cron";
+import logger from "../utils/logger.js";
+
+const NAME_REGEX = /^[a-zA-Z0-9_-]{1,50}$/;
+
+/**
+ * 定时任务管理器：基于 node-cron 封装。
+ *
+ * - cron 表达式校验，非法表达式跳过注册并告警，不阻断应用启动
+ * - 回调异常自动捕获并记录日志，不会导致进程崩溃
+ * - 优雅停机时调用 stopAll() 清理全部定时器
+ *
+ * @example
+ * chan.task.add("clear-log", "0 3 * * *", async () => {
+ *   await chan.db.raw("DELETE FROM logs WHERE created_at < NOW() - INTERVAL 7 DAY");
+ * });
+ */
+export class Task {
+  constructor() {
+    /** @type {Map<string, import("node-cron").ScheduledTask>} */
+    this._tasks = new Map();
+  }
+
+  /**
+   * 注册定时任务
+   *
+   * 校验失败（任务名非法 / cron 表达式非法 / 任务已存在 / 回调非函数）
+   * 仅打印 error 日志并返回 null，不抛异常、不阻断应用启动。
+   *
+   * @param {string} name - 任务名（唯一标识）
+   * @param {string} expr - cron 表达式（5 段，如 "0 3 * * *"）
+   * @param {(task: Task) => Promise<void>|void} fn - 任务回调
+   * @param {{ start?: boolean, timezone?: string }} [opts] - 选项
+   * @returns {import("node-cron").ScheduledTask|null} 任务实例，校验失败返回 null
+   */
+  add(name, expr, fn, { start = true, timezone } = {}) {
+    if (!NAME_REGEX.test(name)) {
+      logger.error(`[Task] 注册失败，非法任务名: ${name}，已跳过`);
+      return null;
+    }
+    if (!cron.validate(expr)) {
+      logger.error(`[Task] 注册失败，任务 ${name} 非法 cron 表达式: ${expr}，已跳过`);
+      return null;
+    }
+    if (this._tasks.has(name)) {
+      logger.error(`[Task] 注册失败，任务已存在: ${name}，已跳过`);
+      return null;
+    }
+    if (typeof fn !== "function") {
+      logger.error(`[Task] 注册失败，任务 ${name} 回调必须为函数，已跳过`);
+      return null;
+    }
+
+    const task = cron.schedule(expr, async () => {
+      const t0 = Date.now();
+      try {
+        await fn(this);
+        logger.info(`[Task] ${name} 完成 (${Date.now() - t0}ms)`);
+      } catch (err) {
+        // 捕获异常防进程崩溃，记录日志供排查
+        logger.error(`[Task] ${name} 异常: ${err.message}`, err);
+      }
+    }, { timezone });
+
+    if (!start) task.stop();
+    this._tasks.set(name, task);
+    return task;
+  }
+
+  /** 启动指定任务 */
+  start(name) { this._tasks.get(name)?.start(); }
+
+  /** 停止指定任务 */
+  stop(name) { this._tasks.get(name)?.stop(); }
+
+  /** 获取全部任务名列表 */
+  list() { return [...this._tasks.keys()]; }
+
+  /** 优雅停机：停止全部任务并清空注册表 */
+  stopAll() {
+    for (const task of this._tasks.values()) task.stop();
+    this._tasks.clear();
+    logger.info("[Task] 全部定时任务已停止");
+  }
+}
+
+export default Task;

package/core/errors.js

@@ -45,11 +45,6 @@ export class AppError extends Error {
     if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
   }
 
-  /** 统一判断是否为业务错误实例（推荐使用独立导出函数 isAppError） */
-  static isAppError(err) {
-    return err instanceof AppError;
-  }
-
   /** 自定义序列化 */
   toJSON() {
     const json = { name: this.name, message: this.message, code: this.code, httpStatus: this.httpStatus };