chanjs 2.7.5 → 2.7.6

package/core/BaseComponent.js

@@ -0,0 +1,27 @@
+import { getApp } from "./registry.js";
+
+/**
+ * 轻量基础组件类：提供 app / config / db 快捷访问
+ * Controller / Service / Repository 统一继承此类，
+ * 不再强制绑定组件加载（Container）职责。
+ */
+export class BaseComponent {
+  /** 获取全局应用实例 */
+  get app() { return getApp(); }
+
+  /**
+   * 全局配置快捷访问
+   * 业务 Controller/Service/Repository 大量使用 `this.config.xxx` 读取配置项
+   * 统一从 app.config 取，未初始化时返回空对象避免 undefined.xxx 报错
+   */
+  get config() {
+    return this.app?.config ?? {};
+  }
+
+  /** 数据库连接快捷访问（默认连接） */
+  get db() {
+    return this.app?.db ?? null;
+  }
+}
+
+export default BaseComponent;

package/core/Container.js

@@ -1,44 +1,35 @@
 import fs from 'fs';
 import path from 'path';
 import { Paths } from '../utils/paths.js';
-import { getApp } from './registry.js';
+import { BaseComponent } from './BaseComponent.js';
 import logger from "../utils/logger.js";
 
 const NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
 
 /**
- * 组件容器：统一加载 controller/service
+ * 组件容器：按需动态加载 controller/service 组件（组合模式）
+ * 继承 BaseComponent 获得 app/config/db 访问，额外提供组件加载能力
  */
-export class Container {
+export class Container extends BaseComponent {
   constructor(type = 'service') {
-    this.cache = new Map();
-    this.type = type;
-    this.baseDir = Paths.modulesPath;
-  }
-
-  get app() { return getApp(); }
-
-  /**
-   * 全局配置快捷访问
-   * 业务 Controller/Service/Repository 大量使用 `this.config.xxx` 读取配置项
-   * 统一从 app.config 取，未初始化时返回空对象避免 undefined.xxx 报错
-   */
-  get config() {
-    return this.app?.config ?? {};
+    super();
+    this._componentCache = new Map();
+    this._type = type;
+    this._baseDir = Paths.modulesPath;
   }
 
   /**
-   * 获取组件，自动缓存
-   * @param {string} moduleName
-   * @param {string} fileName
+   * 按需获取组件实例，自动缓存
+   * @param {string} moduleName 模块名
+   * @param {string} fileName 组件文件名（不含 .js）
    */
   async get(moduleName, fileName) {
     const cacheKey = `${moduleName}.${fileName}`;
-    if (this.cache.has(cacheKey)) return this.cache.get(cacheKey);
+    if (this._componentCache.has(cacheKey)) return this._componentCache.get(cacheKey);
 
     try {
-      const instance = await this.loadFile(moduleName, fileName);
-      if (!instance) logger.info(`[Container] ${moduleName}/${this.type}/${fileName}.js 导出实例为空`);
+      const instance = await this._loadFile(moduleName, fileName);
+      if (!instance) logger.info(`[Container] ${moduleName}/${this._type}/${fileName}.js 导出实例为空`);
       return instance;
     } catch (err) {
       logger.error(`[Container] 加载组件失败 ${moduleName}/${fileName}：${err.message}`);
@@ -47,15 +38,15 @@ export class Container {
   }
 
   /** 物理加载文件、导入模块、安全校验 */
-  async loadFile(moduleName, fileName) {
+  async _loadFile(moduleName, fileName) {
     const cacheKey = `${moduleName}.${fileName}`;
 
     if (!NAME_REGEX.test(moduleName) || !NAME_REGEX.test(fileName)) {
       throw new Error(`非法名称 ${moduleName}/${fileName}`);
     }
 
-    const filePath = path.resolve(this.baseDir, moduleName, this.type, `${fileName}.js`);
-    const relativePath = path.relative(this.baseDir, filePath);
+    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}`);
     }
@@ -63,13 +54,13 @@ export class Container {
     try {
       await fs.promises.access(filePath, fs.constants.R_OK);
     } catch {
-      logger.info(`[Container] 文件不存在：${moduleName}/${this.type}/${fileName}.js`);
+      logger.info(`[Container] 文件不存在：${moduleName}/${this._type}/${fileName}.js`);
       return null;
     }
 
     const mod = await import(`file://${filePath}`);
     const instance = mod.default;
-    this.cache.set(cacheKey, instance);
+    this._componentCache.set(cacheKey, instance);
     return instance;
   }
 }

package/core/Repository.js

@@ -1,4 +1,4 @@
-import Container from "./Container.js";
+import { BaseComponent } from "./BaseComponent.js";
 import logger from "../utils/logger.js";
 import {
   CODE_OK,
@@ -8,7 +8,7 @@ import {
 } from "../response/code.js";
 
 const SORT_FIELD_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-const OPERATORS = { $like:'like', $gt:'>', $gte:'>=', $lt:'<', $lte:'<=', $ne:'<>', $in:'in' };
+const OPERATORS = { $like:'like', $gt:'>', $gte:'>=', $lt:'<', $lte:'<=', $ne:'<>' };
 
 /**
  * 拼接查询条件，支持操作符/等值/数组in
@@ -24,12 +24,12 @@ function applyQuery(dbQuery, query) {
     }
     if (val && typeof val === 'object' && !Array.isArray(val)) {
       const ops = Object.keys(val);
-      if (ops.length && ops.every(k => k in OPERATORS || k === '$null' || k === '$notNull')) {
+      if (ops.length && ops.every(k => k in OPERATORS || k === '$in' || k === '$null' || k === '$notNull')) {
         for (const [op, operand] of Object.entries(val)) {
-          if (OPERATORS[op]) {
-            dbQuery = dbQuery.where(field, OPERATORS[op], operand);
-          } else if (op === '$in') {
+          if (op === '$in') {
             dbQuery = dbQuery.whereIn(field, Array.isArray(operand) ? operand : [operand]);
+          } else if (OPERATORS[op]) {
+            dbQuery = dbQuery.where(field, OPERATORS[op], operand);
           } else if (op === '$null') {
             operand ? dbQuery.whereNull(field) : dbQuery.whereNotNull(field);
           } else if (op === '$notNull') {
@@ -71,10 +71,11 @@ function applySelectAndSort(q, fields, sort) {
 
 /**
  * 数据访问基类，封装通用CRUD操作
+ * 继承 BaseComponent 获得 app/config/db 快捷访问，不绑定组件加载职责
  */
-class Repository extends Container {
+class Repository extends BaseComponent {
   constructor(table=null, dbName=null, opts={}) {
-    super('service');
+    super();
     this.tableName = table;
     this._dbName = dbName;
     this._customDb = null;
@@ -82,13 +83,13 @@ class Repository extends Container {
     typeof this.on === 'function' && this.on();
   }
 
-  /** 动态获取数据库连接 */
+  /** 动态获取数据库连接（支持多库：指定 dbName 时取对应连接，否则取默认） */
   get db() {
     if (this._dbName) {
-      this._customDb ??= this.app.dbManager.get(this._dbName);
+      this._customDb ??= this.app?.dbManager?.get(this._dbName);
       return this._customDb;
     }
-    return this.app.db;
+    return this.app?.db ?? null;
   }
 
   /** 分页配置快捷读取 */
@@ -260,16 +261,11 @@ class Repository extends Container {
     };
   }
 
-  /** 标准分页查询（业务侧常用别名） */
+  /** 标准分页查询 */
   async query(params={}) {
     return this._doPaginate(params);
   }
 
-  /** 标准分页查询（list 别名，向后兼容） */
-  async list(params={}) {
-    return this._doPaginate(params);
-  }
-
   /** 统计符合条件记录行数 */
   async count(query={}) {
     this._checkDB();

package/core/bootstrap/error-handler.js

@@ -1,4 +1,4 @@
-import { routeNotFound, serializeError, buildErrorHtml, respondError } from "../../response/index.js";
+import { routeNotFound, serializeError, respondError } from "../../response/index.js";
 import { CODE_NOT_FOUND, CODE_CONFLICT, CODE_BUSINESS_FAIL } from "../../response/code.js";
 import {
   AppError, isAppError, parseStack, describeError, wrapDbError,
@@ -84,21 +84,18 @@ export function registerErrorHandler(chan) {
     // 双重安全校验：生产环境即使环境变量开了，也必须携带合法 Debug Token 才暴露堆栈/SQL
     const exposeDetail = EXPOSE_ERR_DETAIL && (!IS_PROD || req.headers["x-debug-token"] === process.env.DEBUG_TOKEN);
 
-    // 统一判断并返回内置HTML页面（仅浏览器页面访问；API 请求一律 JSON）
-    const sendHtml = (status, message, bizCode) => {
-      if (req.xhr || req.accepts?.(["json", "html"]) === "json") return false;
-      if (!req.accepts?.("html")) return false;
-      res.status(status).type("html").send(buildErrorHtml(status, message, bizCode, req));
-      return true;
-    };
-
     if (isAppError(err)) {
-      if (sendHtml(httpStatus, err.message, err.code)) return;
-      return res.status(httpStatus).json(serializeError(err, exposeDetail));
+      // 统一通过 respondError 做 HTML/JSON 分流（复用 response 层纯函数，消除重复逻辑）
+      const serialized = serializeError(err, exposeDetail);
+      return respondError(res, req, {
+        httpStatus,
+        code: serialized.code,
+        msg: serialized.msg,
+        data: serialized.data ?? null,
+      });
     }
 
-    // 兜底分支（理论上 wrapDbError 已转 AppError，这里防万一）
-    if (sendHtml(500, "服务器内部错误", 500)) return;
-    res.status(500).json(serializeError(err, exposeDetail));
+    // 兆底分支（理论上 wrapDbError 已转 AppError，这里防万一）
+    respondError(res, req, { httpStatus: 500, code: 500, msg: "服务器内部错误" });
   });
 }

package/core/errors.js

@@ -45,7 +45,7 @@ export class AppError extends Error {
     if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
   }
 
-  /** 统一判断是否为业务错误实例 */
+  /** 统一判断是否为业务错误实例（推荐使用独立导出函数 isAppError） */
   static isAppError(err) {
     return err instanceof AppError;
   }
@@ -70,9 +70,30 @@ function createErrorClass(className) {
 
   return class extends AppError {
     constructor(msgOrOpts, ...rest) {
-      const opts = (msgOrOpts && typeof msgOrOpts === 'object') ? msgOrOpts : { msg: msgOrOpts, ...Object.fromEntries(cfg.extraProps?.map((k, i) => [k, rest[i]]) ?? []), cause: rest[cfg.extraProps?.length] };
+      // 支持两种调用方式：
+      //   new XxxError("消息")
+      //   new XxxError({ msg: "消息", cause: err, ...extraProps })
+      let opts;
+      if (msgOrOpts && typeof msgOrOpts === 'object') {
+        opts = msgOrOpts;
+      } else {
+        opts = { msg: msgOrOpts };
+        // 将 extraProps 按顺序映射到 rest 参数
+        if (cfg.extraProps) {
+          cfg.extraProps.forEach((key, i) => {
+            if (rest[i] !== undefined) opts[key] = rest[i];
+          });
+          // extraProps 之后的参数视为 cause
+          const causeIdx = cfg.extraProps.length;
+          if (rest[causeIdx] !== undefined) opts.cause = rest[causeIdx];
+        } else if (rest[0] !== undefined) {
+          opts.cause = rest[0];
+        }
+      }
+
       super(cfg.code, opts.msg ?? cfg.defaultMsg, cfg.httpStatus, opts.cause ?? null);
       this.name = className;
+      // 挂载额外属性（如 fields / retryAfter）
       for (const [k, v] of Object.entries(opts)) {
         if (k !== 'msg' && k !== 'cause' && v !== undefined) this[k] = v;
       }
@@ -192,6 +213,12 @@ export function wrapDbError(err) {
 
   if (isDbConnectionError(e)) return new DbConnectionError("数据库连接失败，请稍后重试", err);
 
+  // 模板/视图渲染错误：Express 的 res.render 找不到模板时抛出
+  const errMsg = String(e?.message || "").toLowerCase();
+  if (errMsg.includes("failed to lookup view") || errMsg.includes("no default engine")) {
+    return new SystemError("模板渲染异常：" + (e?.message || "视图文件不存在"), err);
+  }
+
   const driverCode = e?.code;
   switch (driverCode) {
     case "ER_DUP_ENTRY":

package/index.js

@@ -7,7 +7,7 @@
  *   await chan.start();
  *
  * 命名导出：
- *   import { Controller, Repository, Service, helper, cache, Paths, loader, utils, getApp } from "chanjs";
+ *   import { Controller, Repository, Service, cache, Paths, loader, utils, getApp } from "chanjs";
  *   import { validate, validateAll } from "chanjs";  // zod 校验中间件
  *   import { AppError, NotFoundError, ValidationError } from "chanjs";  // 错误类
  *
@@ -17,6 +17,7 @@
  */
 
 // ===================== 核心基础类 =====================
+export { BaseComponent } from "./core/BaseComponent.js";
 export { default as Controller } from "./core/Controller.js";
 export { default as Repository } from "./core/Repository.js";
 export { Service } from "./core/Service.js";
@@ -55,21 +56,6 @@ export * as utils from "./utils/index.js";
 export { cache, store } from "./storage/index.js";
 export { Paths } from "./utils/paths.js";
 
-// ===================== helper 聚合对象 =====================
-// 为兼容老代码 import { helper } from "chanjs"，薄封装：单一来源 = 命名导出 + 工具命名空间
-import * as utilsNs from "./utils/index.js";
-import { cache, store } from "./storage/index.js";
-import { success, fail } from "./response/index.js";
-import { setToken, getToken, aesEncrypt, aesDecrypt } from "./security/index.js";
-import { createRateLimitMiddleware } from "./security/rate-limit.js";
-import { filterXSS, checkKeywords } from "./security/index.js";
-
-export const helper = Object.assign(Object.create(null), utilsNs, {
-  cache, store, success, fail,
-  setToken, getToken, aesEncrypt, aesDecrypt,
-  createRateLimitMiddleware, filterXSS, checkKeywords,
-});
-
 // ===================== 默认导出应用主类 =====================
 import Chan from "./core/App.js";
 export default Chan;

package/middleware/favicon.js

@@ -1,11 +1,19 @@
+import fs from "fs";
 import path from "path";
 import serveFavicon from "serve-favicon";
 import { Paths } from "../utils/paths.js";
+import logger from "../utils/logger.js";
 
 /**
  * 网站图标中间件，读取public目录favicon.ico
+ * 文件不存在时静默跳过，不阻断启动
  * @param {express.Application} app Express实例
  */
 export const favicon = app => {
-  app.use(serveFavicon(path.join(Paths.publicPath, "favicon.ico")));
+  const icoPath = path.join(Paths.publicPath, "favicon.ico");
+  if (!fs.existsSync(icoPath)) {
+    logger.info("[Favicon] favicon.ico 不存在，跳过图标中间件");
+    return;
+  }
+  app.use(serveFavicon(icoPath));
 };

package/middleware/waf.js

@@ -89,7 +89,7 @@ async function handleStrike(fingerprint, clientIp, keyword, blockCfg) {
 
 /** 执行限流，返回是否已响应 */
 const runRateLimit = (rateLimit, req, res) =>
-  new Promise(rateLimit.bind(null, req, res, r)).then(() => res.headersSent);
+  new Promise(resolve => rateLimit(req, res, resolve)).then(() => res.headersSent);
 
 /**
  * 前置WAF中间件（body前）
@@ -162,14 +162,16 @@ const createWafMiddleware = wafConfig => {
 
 /**
  * 已登录用户的管理接口路径前缀（跳过 body 关键词检测，避免误杀富文本/代码内容）
+ * 可通过 waf 配置 bodySkipPrefixes 字段自定义，默认包含常见管理模块前缀
  */
-const BODY_CHECK_SKIP_PREFIXES = ["/cms/", "/base/", "/member/", "/book/", "/oss/", "/vip/"];
+const DEFAULT_BODY_SKIP_PREFIXES = ["/cms/", "/base/", "/member/", "/book/", "/oss/", "/vip/"];
 
 /**
  * Body层WAF中间件（body解析后）
  */
 const createWafBodyMiddleware = wafConfig => {
   const blockCfg = { ...DEFAULT_BLOCK, ...wafConfig.block };
+  const bodySkipPrefixes = wafConfig.bodySkipPrefixes ?? DEFAULT_BODY_SKIP_PREFIXES;
 
   return async (req, res, next) => {
     try {
@@ -185,7 +187,7 @@ const createWafBodyMiddleware = wafConfig => {
       if (!req.body || (typeof req.body === "object" && !Object.keys(req.body).length)) return next();
 
       // 已登录用户的管理接口：跳过关键词检测（富文本/代码内容会误杀），仅做 XSS 过滤
-      const isAuthedAdmin = req.user?.uid && BODY_CHECK_SKIP_PREFIXES.some(p => path.startsWith(p));
+      const isAuthedAdmin = req.user?.uid && bodySkipPrefixes.some(p => path.startsWith(p));
 
       if (!isAuthedAdmin) {
         // 序列化body文本，截断1w字符防绕过

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "chanjs",
-  "version": "2.7.5",
+  "version": "2.7.6",
   "description": "chanjs基于express5 纯js研发的轻量级mvc框架。",
   "main": "index.js",
   "module": "index.js",

package/security/jwt.js

@@ -12,12 +12,30 @@ const JWT_ERR_MSG = {
 };
 
 /**
- * 校验token是否在黑名单（fail-open：存储异常直接放行）
+ * 黑名单校验失败策略配置
+ * failOpen=true（默认）：存储异常时放行（优先可用性）
+ * failOpen=false：存储异常时拦截（优先安全性，适用于金融/权限敏感场景）
+ * 可通过环境变量 JWT_REVOCATION_FAIL_CLOSE=true 全局切换为 fail-close
+ */
+const IS_FAIL_CLOSE = process.env.JWT_REVOCATION_FAIL_CLOSE === "true";
+
+/**
+ * 校验token是否在黑名单
+ * fail-close 模式：存储异常视为已注销（拦截）
+ * fail-open  模式：存储异常视为未注销（放行）
  */
 const isTokenRevoked = async token => {
   if (!token) return false;
-  try { return !!await store.get(`${REVOKED_KEY_PREFIX}${token}`); }
-  catch { return false; }
+  try {
+    return !!await store.get(`${REVOKED_KEY_PREFIX}${token}`);
+  } catch (err) {
+    if (IS_FAIL_CLOSE) {
+      logger.warn(`[JWT] 黑名单查询异常，fail-close 拦截：${err.message}`);
+      return true;
+    }
+    logger.warn(`[JWT] 黑名单查询异常，fail-open 放行：${err.message}`);
+    return false;
+  }
 };
 
 /**

package/security/keywords.js

@@ -3,8 +3,8 @@
  */
 const KEYWORD_RULES = Object.freeze({
   wholeWord: [
-    "netcat", "nc", "php-cgi", "process", "require", "exec", "import",
-    "child_process", "execSync", "mainModule"
+    "netcat", "php-cgi", "child_process", "execSync", "mainModule",
+    "process.env", "require(", "exec("
   ],
   extensions: [
     ".php", ".asp", ".aspx", ".jsp", ".jspx", ".do", ".action", ".cgi",

package/storage/cache.js

@@ -46,7 +46,7 @@ class Cache {
   clear = () => this.map.clear();
   size() { return this.map.size; }
 
-  /** 访问并刷新LRU，过期项自动清理 */
+  /** 访问并刷新LRU，过期项自动清理（单次 delete+set 维护 Map 插入序） */
   _touch(key) {
     const item = this.map.get(key);
     if (!item) return null;
@@ -54,6 +54,7 @@ class Cache {
       this.map.delete(key);
       return null;
     }
+    // 利用 Map 插入序特性：delete+set 将 key 移至末尾（最近访问）
     this.map.delete(key);
     this.map.set(key, item);
     return item;
@@ -92,13 +93,11 @@ class Cache {
     return true;
   }
 
-  /** LRU淘汰：循环删除最久未访问key */
+  /** LRU淘汰：删除最久未访问key（Map 头部即最早插入） */
   _evictLRU() {
-    while (this.map.size >= this.maxSize) {
-      const oldest = this.map.keys().next().value;
-      if (oldest === undefined) break;
-      this.map.delete(oldest);
-    }
+    if (this.map.size < this.maxSize) return;
+    const oldest = this.map.keys().next().value;
+    if (oldest !== undefined) this.map.delete(oldest);
   }
 
   /** 惰性批量清理：间隔10s一次，单次最多清理1000条防阻塞事件循环 */

package/storage/redis.js

@@ -129,30 +129,31 @@ class RedisBackend {
 
   /**
    * 自增计数，新建key使用全局默认TTL
-   * 纯ioredis方案：先INCR，返回1（key新建/过期重建）则补PEXPIRE，递增不刷新TTL
-   * 解决原 SET NX + INCR 之间 key 过期导致的无 TTL 内存泄漏竞态
+   * Lua 脚本保证 INCR + PEXPIRE 原子性，避免崩溃窗口内 key 无 TTL 内存泄漏
+   * 递增不刷新TTL，仅首次（count===1）设置过期
    * @param {string} key 计数key
    * @returns {number} 当前计数值
    */
   async incr(key) {
     const cli = await this._getClient();
-    const count = await cli.incr(key);
-    // count===1 说明 key 是新建的（首次或过期重建），补设 TTL；递增(count>1)不刷新 TTL
-    if (count === 1) await cli.pexpire(key, REDIS_CONST.DEFAULT_INCR_TTL);
-    return count;
+    return cli.eval(
+      "local c=redis.call('INCR',KEYS[1]);if c==1 then redis.call('PEXPIRE',KEYS[1],ARGV[1])end;return c",
+      1, key, REDIS_CONST.DEFAULT_INCR_TTL
+    );
   }
 
   /**
-   * 限流专用自增，自定义新建key过期时间
+   * 限流专用自增，自定义新建key过期时间（Lua 原子操作）
    * @param {string} key 计数key
    * @param {number} ttlMs 窗口过期时间
    * @returns {number} 当前计数值
    */
   async incrAndExpire(key, ttlMs) {
     const cli = await this._getClient();
-    const count = await cli.incr(key);
-    if (count === 1) await cli.pexpire(key, ttlMs);
-    return count;
+    return cli.eval(
+      "local c=redis.call('INCR',KEYS[1]);if c==1 then redis.call('PEXPIRE',KEYS[1],ARGV[1])end;return c",
+      1, key, ttlMs
+    );
   }
 
   /**

package/utils/index.js

@@ -1,11 +1,10 @@
 /**
  * 工具聚合层
  *
- * 业务侧使用方式：
- *   import { helper } from "chanjs";
- *   const { tree, getIp, formatDateFields } = helper;
+ * 业务侧使用方式（精确命名导入）：
+ *   import { tree, getIp, formatDateFields } from "chanjs/utils/index.js";
  *
- * 也可直接从子模块导入（精确引用）：
+ * 也可从子模块单独导入：
  *   import { getIp } from "chanjs/utils/ip.js";
  */
 

package/utils/request.js

@@ -88,6 +88,7 @@ export async function request(url, options = {}) {
 
     try {
       const res = await fetch(rawUrl, { ...fetchOpts, signal: controller.signal });
+      if (timer) clearTimeout(timer);
 
       if (!res.ok) {
         return { success: false, error: `HTTP ${res.status} ${res.statusText}` };