chanjs 2.6.4 → 2.6.5

package/App.js

@@ -9,7 +9,7 @@ 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 "./utils/index.js";
+import { notFoundResponse, parseDatabaseError, errorResponse } from "./helper/index.js";
 import { importFile } from "./global/import.js";
 
 import "./global/index.js";

package/base/Container.js

@@ -5,10 +5,11 @@ import { Paths } from '../config/paths.js';
 export class Container {
   constructor(type = 'service') {
     this.map = new Map();
+    // 组件类型，例如：'service','controller'
     this.type = type;
+    // modules 目录路径
     this.baseDir = Paths.modulesPath;
-    
-    // 只添加 config 属性，db 由 Service 自己管理
+    // 只添加 config 属性，全局默认的配置
     this.config = Chan.config;
   }
 
@@ -20,12 +21,13 @@ export class Container {
    */
   async get(moduleName, fileName) {
     const key = `${moduleName}.${fileName}`;
-    
+    // 如果组件实例已存在，直接返回
     if (this.map.has(key)) {
       return this.map.get(key);
     }
 
     try {
+      // 没有，加载组件实例
       await this.loadFile(moduleName, fileName);
       const obj = this.map.get(key);
       if (!obj) {
@@ -34,6 +36,7 @@ export class Container {
       return obj;
     } catch (err) {
       console.error(`获取模块 ${moduleName} 下文件 ${fileName}.js 对应的组件失败：${err.message}`);
+      return null;
     }
   }
 

package/base/Controller.js

@@ -1,4 +1,4 @@
-import { success, fail } from "../utils/response.js";
+import { success, fail } from "../helper/response.js";
 import Container from "./Container.js";
 
 /**
@@ -7,6 +7,7 @@ import Container from "./Container.js";
  */
 export default class Controller extends Container {
   constructor() {
+    // 调用父类构造函数，指定组件类型为 'controller'
     super('controller');
   }
 

package/base/Service.js

@@ -25,7 +25,26 @@ class Service extends Container {
       this.tableName = tableName;
     }
 
-    this._dateFields = ['created_at', 'updated_at', 'deleted_at', 'publish_time', 'start_time', 'end_time', 'login_time', 'created_date', 'updated_date', 'createdAt', 'updatedAt', 'deletedAt', 'publishTime', 'startTime', 'endTime', 'loginTime', 'createdDate', 'updatedDate'];
+    this._dateFields = [
+      'created_at', 
+      'updated_at', 
+      'deleted_at', 
+      'publish_time', 
+      'start_time', 
+      'end_time', 
+      'login_time', 
+      'created_date', 
+      'updated_date', 
+      'createdAt', 
+      'updatedAt', 
+      'deletedAt', 
+      'publishTime', 
+      'startTime', 
+      'endTime', 
+      'loginTime', 
+      'createdDate', 
+      'updatedDate'
+    ]; 
     
     // 自动注册事件监听器（如果子类定义了 on 方法）
     if (typeof this.on === 'function') {

package/common/index.js

@@ -3,5 +3,3 @@ export { getChildrenId } from "./category.js";
 export { CODE } from "./code.js";
 export { sendMail, genRegEmailHtml, genResetPasswordEmail } from "./email.js";
 export { pages, getHtmlFilesSync } from "./pages.js";
-export { createSmsClient } from "./sms.js";
-export { filterBody, pc, filterImgFromStr } from "./utils.js";

package/doc/Aop.md

@@ -0,0 +1,269 @@
+# Aop 轻量级切面类使用文档
+
+## 概述
+`Aop` 是一个轻量级的 JavaScript 切面编程（AOP）工具类，支持为对象方法注册并执行 `before`（前置）、`after`（后置）、`error`（异常）三种类型的切面函数，适用于日志记录、参数校验、异常处理等横切关注点场景。
+
+## 特性
+- 支持链式调用注册切面函数
+- 内置切面类型校验，仅支持 `before`/`after`/`error` 三种常用类型
+- 支持切面规则启用/禁用，灵活控制切面执行
+- 保留原方法上下文，保证方法执行正确性
+- 完善的错误处理，切面执行异常不阻断主流程
+
+## 安装与引入
+### 方式1：ESModule 引入
+```javascript
+import { Aop, aop } from './aop.js';
+```
+
+## 核心 API
+
+### 1. 切面注册（set）
+注册一个切面函数，返回当前实例支持链式调用。
+
+#### 语法
+```javascript
+aop.set(name, fn)
+```
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| name | string | 切面名称（非空字符串） |
+| fn | Function | 切面执行函数，入参为切面上下文对象 |
+
+#### 示例
+```javascript
+// 注册日志切面
+aop.set('logger', async (params) => {
+  console.log(`[${params.methodName}] 执行时间：${new Date().toISOString()}`);
+  console.log(`参数：`, params.args);
+});
+
+// 注册参数校验切面（链式调用）
+aop.set('paramCheck', async (params) => {
+  const [id] = params.args;
+  if (!id || typeof id !== 'number') {
+    throw new Error(`[${params.methodName}] 参数id必须是数字`);
+  }
+});
+```
+
+### 2. 获取切面（get）
+获取已注册的切面函数。
+
+#### 语法
+```javascript
+aop.get(name)
+```
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| name | string | 切面名称 |
+
+#### 返回值
+| 类型 | 说明 |
+|------|------|
+| Function \| null | 存在则返回切面函数，否则返回 null |
+
+#### 示例
+```javascript
+const logger = aop.get('logger');
+if (logger) {
+  console.log('日志切面已注册');
+}
+```
+
+### 3. 移除切面（remove）
+移除指定名称的切面函数。
+
+#### 语法
+```javascript
+aop.remove(name)
+```
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| name | string | 切面名称 |
+
+#### 示例
+```javascript
+// 移除日志切面
+aop.remove('logger');
+```
+
+### 4. 清空所有切面（clear）
+清空已注册的所有切面函数。
+
+#### 语法
+```javascript
+aop.clear()
+```
+
+#### 示例
+```javascript
+// 清空所有切面
+aop.clear();
+```
+
+### 5. 绑定切面到方法（wrap）
+核心方法，为目标对象的指定方法绑定切面规则。
+
+#### 语法
+```javascript
+aop.wrap(instance, config)
+```
+
+#### 参数
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| instance | object | 目标实例（非空对象） |
+| config | object | 切面配置，格式：`{ 方法名: [{ type: 切面类型, enabled: 是否启用, 切面名称: 配置 }] }` |
+
+#### 配置规则说明
+| 字段 | 类型 | 说明 | 必填 | 默认值 |
+|------|------|------|------|--------|
+| type | string | 切面类型（before/after/error） | 是 | - |
+| enabled | boolean | 是否启用该规则 | 否 | true |
+| [切面名称] | any | 自定义配置，会透传给切面函数 | 否 | {} |
+
+#### 返回值
+| 类型 | 说明 |
+|------|------|
+| object | 绑定后的实例对象 |
+
+## 完整使用示例
+
+### 步骤1：定义目标类
+```javascript
+// 示例控制器类
+class UserController {
+  async getUser(id) {
+    console.log(`获取用户信息，ID：${id}`);
+    if (id === 0) {
+      throw new Error('用户ID不能为0');
+    }
+    return { id, name: '张三', age: 20 };
+  }
+}
+```
+
+### 步骤2：注册切面函数
+```javascript
+import { aop } from './aop.js';
+
+// 1. 注册参数校验切面
+aop.set('paramCheck', async (params) => {
+  const [id] = params.args;
+  console.log(`[paramCheck] 校验参数：id = ${id}`);
+  if (typeof id !== 'number') {
+    throw new Error(`参数id必须是数字，当前值：${id}`);
+  }
+});
+
+// 2. 注册日志切面
+aop.set('logger', async (params) => {
+  const { methodName, args, result, error } = params;
+  if (params.type === 'before') {
+    console.log(`[logger] 方法${methodName}开始执行，参数：`, args);
+  } else if (params.type === 'after') {
+    console.log(`[logger] 方法${methodName}执行完成，结果：`, result);
+  } else if (params.type === 'error') {
+    console.log(`[logger] 方法${methodName}执行异常：`, error.message);
+  }
+});
+
+// 3. 注册异常处理切面
+aop.set('errorHandler', async (params) => {
+  console.log(`[errorHandler] 捕获异常：${params.error.message}，执行兜底逻辑`);
+  // 可在这里添加异常上报、数据清理等逻辑
+});
+```
+
+### 步骤3：绑定切面到方法并使用
+```javascript
+// 创建实例
+const userController = new UserController();
+
+// 绑定切面规则
+aop.wrap(userController, {
+  getUser: [
+    // 前置切面：参数校验 + 日志
+    { type: 'before', enabled: true, paramCheck: true, logger: true },
+    // 后置切面：日志
+    { type: 'after', enabled: true, logger: true },
+    // 异常切面：日志 + 异常处理
+    { type: 'error', enabled: true, logger: true, errorHandler: true }
+  ]
+});
+
+// 测试正常执行
+async function testNormal() {
+  try {
+    const result = await userController.getUser(1);
+    console.log('最终结果：', result);
+  } catch (e) {
+    console.log('测试异常：', e.message);
+  }
+}
+
+// 测试异常执行
+async function testError() {
+  try {
+    const result = await userController.getUser(0);
+    console.log('最终结果：', result);
+  } catch (e) {
+    console.log('测试异常：', e.message);
+  }
+}
+
+// 执行测试
+testNormal();
+// testError();
+```
+
+### 执行结果（testNormal）
+```
+[paramCheck] 校验参数：id = 1
+[logger] 方法getUser开始执行，参数： [1]
+获取用户信息，ID：1
+[logger] 方法getUser执行完成，结果： { id: 1, name: '张三', age: 20 }
+最终结果： { id: 1, name: '张三', age: 20 }
+```
+
+### 执行结果（testError）
+```
+[paramCheck] 校验参数：id = 0
+[logger] 方法getUser开始执行，参数： [0]
+获取用户信息，ID：0
+[logger] 方法getUser执行异常： 用户ID不能为0
+[errorHandler] 捕获异常：用户ID不能为0，执行兜底逻辑
+测试异常： 用户ID不能为0
+```
+
+## 切面函数上下文参数说明
+切面函数的入参是一个上下文对象，包含以下字段：
+
+| 字段 | 类型 | 说明 | 可用切面类型 |
+|------|------|------|--------------|
+| ctx | object | 原方法的执行上下文（实例对象） | all |
+| methodName | string | 被包装的方法名称 | all |
+| args | Array | 原方法的入参数组（浅拷贝） | all |
+| originalMethod | Function | 原始未包装的方法 | all |
+| result | any | 原方法执行结果 | after |
+| error | Error | 原方法抛出的异常 | error |
+| params | object | 切面规则中配置的自定义参数 | all |
+
+## 注意事项
+1. **异步支持**：切面函数和被包装的方法均支持异步（async/await），内部会自动处理异步执行顺序
+2. **上下文保留**：原方法的 `this` 指向会被正确保留，无需额外处理
+3. **异常处理**：`error` 类型切面执行完成后，异常会被重新抛出，不会阻断原有异常流程
+4. **规则过滤**：`enabled: false` 的规则会被自动过滤，不执行对应的切面
+5. **切面名称冲突**：不要使用 `type`/`enabled` 作为切面名称（内置关键字）
+
+### 总结
+1. `Aop` 类核心提供切面注册（`set`）和方法包装（`wrap`）能力，仅支持 `before`/`after`/`error` 三种切面类型。
+2. 切面函数接收包含上下文、参数、结果/异常的完整入参，可灵活实现各类横切逻辑。
+3. 通过配置规则的 `enabled` 字段可动态控制切面是否生效，异常切面执行后会重新抛出异常，保证原有错误流程不受影响。

package/doc/Cache.md

@@ -0,0 +1,160 @@
+# Cache 工具类文档
+## 概述
+`Cache` 是一个基于内存实现的 LRU（最近最少使用）缓存类，支持 TTL（生存时间）过期策略和自动过期清理机制。该类通过两个 `Map` 分别存储缓存数据和访问顺序，既保证了缓存的快速存取，又能实现 LRU 淘汰策略，适用于需要临时缓存数据且对内存使用有控制需求的场景。
+
+## 安装与引入
+从 `chanjs/helper` 模块中引入 `Cache` 类和默认实例：
+```javascript
+import { Cache } from 'chanjs/helper';
+// 或引入预创建的默认缓存实例
+import { cache } from 'chanjs/helper';
+```
+
+## 类构造器
+### `constructor(options = {})`
+创建缓存实例，初始化最大容量和默认过期时间。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| options.maxSize | number | 1000 | 缓存最大条目数，达到该数量时会自动淘汰最久未使用的条目 |
+| options.defaultTTL | number | 300000（5分钟） | 默认过期时间（毫秒），未指定 TTL 时使用该值 |
+
+**示例**：
+```javascript
+// 创建自定义配置的缓存实例
+const customCache = new Cache({
+  maxSize: 500,    // 最大缓存500条
+  defaultTTL: 60000 // 默认1分钟过期
+});
+
+// 使用默认配置的缓存实例（maxSize=1000，defaultTTL=5分钟）
+const defaultCache = new Cache();
+```
+
+## 核心方法
+### 1. 设置缓存值
+#### `set(key, value, ttl = this.defaultTTL)`
+将键值对存入缓存，若缓存达到最大容量且键不存在，则自动淘汰最久未使用的条目，每次设置会更新访问时间。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| key | string | - | 缓存键（非空字符串） |
+| value | * | - | 要缓存的任意类型数据 |
+| ttl | number | 实例默认TTL | 该缓存条目的过期时间（毫秒） |
+
+**示例**：
+```javascript
+// 设置60秒后过期的缓存
+customCache.set('user:123', { name: '张三', age: 20 }, 60000);
+
+// 使用默认过期时间（5分钟）
+customCache.set('config:theme', { color: 'blue' });
+```
+
+### 2. 获取缓存值
+#### `get(key)`
+获取指定键的缓存值，若键不存在或已过期则返回 `null`；过期条目会自动删除，命中的条目会更新访问时间。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| key | string | 要获取的缓存键 |
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| - | * | 缓存的原始值（命中且未过期）；`null`（未命中/已过期） |
+
+**示例**：
+```javascript
+const user = customCache.get('user:123');
+if (user !== null) {
+  console.log('缓存命中:', user); // { name: '张三', age: 20 }
+} else {
+  console.log('缓存未命中或已过期');
+}
+```
+
+### 3. 删除缓存条目
+#### `del(key)`
+从缓存中删除指定键的条目，同时删除对应的访问记录。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| key | string | 要删除的缓存键 |
+
+**示例**：
+```javascript
+customCache.del('user:123'); // 删除指定缓存
+```
+
+### 4. 清空所有缓存
+#### `clear()`
+删除所有缓存条目和访问记录，清空整个缓存。
+
+**示例**：
+```javascript
+customCache.clear(); // 清空所有缓存
+```
+
+### 5. 检查缓存键是否存在
+#### `has(key)`
+检查指定键是否存在且未过期，若已过期则自动删除条目并返回 `false`。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| key | string | 要检查的缓存键 |
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| - | boolean | `true`（存在且未过期）；`false`（不存在/已过期） |
+
+**示例**：
+```javascript
+if (customCache.has('config:theme')) {
+  console.log('缓存存在且有效');
+} else {
+  console.log('缓存不存在或已过期');
+}
+```
+
+### 6. 获取缓存有效条目数
+#### `size()`
+返回当前缓存中的有效条目数量（会先自动清理已过期条目）。
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| - | number | 有效缓存条目数 |
+
+**示例**：
+```javascript
+console.log(`当前缓存有效条目数: ${customCache.size()}`);
+```
+
+## 内部方法（私有）
+### 1. `_evictLRU()`
+淘汰最久未使用的缓存条目，当缓存达到最大容量时自动调用。遍历访问顺序 `Map`，找到访问时间最早的键并删除对应的缓存和访问记录。
+
+### 2. `_cleanupExpired()`
+清理所有已过期的缓存条目，在调用 `size()` 方法时自动触发。遍历缓存 `Map`，删除所有过期的条目及对应的访问记录。
+
+## 预创建实例
+模块导出了一个默认的 `cache` 实例，使用默认配置（`maxSize=1000`，`defaultTTL=5分钟`），可直接使用：
+```javascript
+import { cache } from 'chanjs/helper';
+
+// 直接使用默认实例
+cache.set('global:token', 'abc123', 1800000); // 30分钟过期
+const token = cache.get('global:token');
+```
+
+## 核心特性
+1. **LRU 淘汰**：缓存达到最大容量时，自动删除最久未使用的条目；
+2. **TTL 过期**：支持自定义过期时间，过期条目自动清理；
+3. **自动清理**：获取缓存大小、检查键存在性时，自动清理过期条目；
+4. **访问更新**：每次设置/获取缓存，都会更新该条目的访问时间，保证 LRU 策略准确性；
+5. **内存安全**：通过最大条目数限制，避免缓存无限制占用内存。
+
+## 注意事项
+1. 缓存数据存储在内存中，应用重启后会丢失，不适用于持久化存储场景；
+2. 键必须为字符串类型，非字符串键可能导致不可预期的问题；
+3. 缓存值建议为可序列化的数据（如对象、字符串、数字等），避免存储复杂对象（如 DOM 元素、函数）导致内存泄漏；
+4. 若需高频清理过期条目，可手动调用 `size()` 方法触发清理（不建议频繁调用，会遍历全量缓存）。