chanjs 2.5.9 → 2.6.1

package/base/AOP.MD

@@ -0,0 +1,318 @@
+# AOP 切面编程使用文档
+
+## 一、概念说明
+
+AOP（面向切面编程）就是在函数执行前后插入额外逻辑，不修改原函数代码。
+
+**本质**：给函数加一层"皮"，在函数执行前、后、出错时插入自定义逻辑。
+
+**优势**：
+- 不改原函数代码
+- 复用逻辑（日志、缓存、权限检查等可以统一处理）
+- 按需开启（想用就用 wrap，不想用就不 wrap）
+- 适用场景 ：日志、缓存、权限检查、性能监控、事务管理等
+
+
+## 二、定义切面函数
+
+### 1. 日志切面
+```javascript
+const logAspect = async ({ ctx, methodName, args, result, error }) => {
+  if (error) {
+    console.error(`[ERROR] ${methodName} 出错:`, error.message);
+    return;
+  }
+  
+  if (result) {
+    console.log(`[SUCCESS] ${methodName} 执行完成，结果:`, result);
+  } else {
+    console.log(`[START] ${methodName} 开始执行，参数:`, args);
+  }
+};
+```
+
+### 2. 缓存切面
+```javascript
+const cacheAspect = async ({ ctx, args, methodName, originalMethod, params }) => {
+  const key = `${methodName}:${JSON.stringify(args)}`;
+  
+  // 尝试从缓存获取
+  const cached = await ctx.cache?.get(key);
+  if (cached) {
+    console.log(`[CACHE HIT] ${key}`);
+    return cached;
+  }
+  
+  // 执行原方法
+  const result = await originalMethod.apply(ctx, args);
+  
+  // 写入缓存
+  const ttl = params?.ttl || 3600;
+  await ctx.cache?.set(key, result, ttl);
+  console.log(`[CACHE SET] ${key}, TTL: ${ttl}s`);
+  
+  return result;
+};
+```
+
+### 3. 权限切面
+```javascript
+const authAspect = async ({ ctx, args, params }) => {
+  const requiredRole = params?.role || 'user';
+  const userRole = ctx.user?.role || 'guest';
+  
+  if (userRole !== requiredRole) {
+    throw new Error(`权限不足，需要: ${requiredRole}，当前: ${userRole}`);
+  }
+  
+  console.log(`[AUTH] ${userRole} 通过权限检查`);
+};
+```
+
+### 4. 性能监控切面
+```javascript
+const perfAspect = async ({ ctx, methodName, args, originalMethod }) => {
+  const startTime = Date.now();
+  
+  try {
+    const result = await originalMethod.apply(ctx, args);
+    const cost = Date.now() - startTime;
+    console.log(`[PERF] ${methodName} 耗时: ${cost}ms`);
+    return result;
+  } catch (error) {
+    const cost = Date.now() - startTime;
+    console.log(`[PERF] ${methodName} 耗时: ${cost}ms (出错)`);
+    throw error;
+  }
+};
+```
+
+---
+
+## 三、注册切面
+
+```javascript
+import { aop } from 'Chan';
+
+// 注册切面
+aop.set('log', logAspect);
+aop.set('cache', cacheAspect);
+aop.set('auth', authAspect);
+aop.set('perf', perfAspect);
+```
+
+---
+
+## 四、绑定切面到实例
+
+### 1. 基本绑定
+```javascript
+import UserService from './service/UserService.js';
+import { aop } from 'Chan';
+
+const userService = new UserService();
+
+// 绑定切面
+aop.wrap(userService, {
+  getUser: [
+    { type: 'before', log: true },
+    { type: 'after', log: true }
+  ]
+});
+
+// 正常调用（切面自动生效）
+const user = await userService.getUser(1);
+```
+
+### 2. 多个切面组合
+```javascript
+aop.wrap(userService, {
+  getUser: [
+    { type: 'before', log: true },
+    { type: 'before', auth: { role: 'admin' }},
+    { type: 'after', log: true },
+    { type: 'after', cache: { ttl: 1800 }}
+  ],
+  createUser: [
+    { type: 'before', log: true },
+    { type: 'after', log: true }
+  ]
+});
+```
+
+### 3. 禁用切面
+```javascript
+aop.wrap(userService, {
+  getUser: [
+    { type: 'before', log: true },
+    { type: 'after', log: false }  // 禁用 after 日志
+  ]
+});
+```
+
+---
+
+## 五、完整使用示例
+
+### 场景：用户服务带日志、缓存、权限控制
+
+```javascript
+// 1. 定义切面
+const logAspect = async ({ ctx, methodName, args, result, error }) => {
+  if (error) {
+    console.error(`[ERROR] ${methodName}:`, error.message);
+    return;
+  }
+  
+  console.log(`[${methodName}] 参数:`, args, '结果:', result);
+};
+
+const cacheAspect = async ({ ctx, args, methodName, originalMethod, params }) => {
+  const key = `${methodName}:${JSON.stringify(args)}`;
+  const cached = await ctx.cache?.get(key);
+  if (cached) return cached;
+  
+  const result = await originalMethod.apply(ctx, args);
+  await ctx.cache?.set(key, result, params?.ttl || 3600);
+  return result;
+};
+
+const authAspect = async ({ ctx, params }) => {
+  if (params?.role && ctx.user?.role !== params.role) {
+    throw new Error(`权限不足`);
+  }
+};
+
+// 2. 注册切面
+import { aop } from 'Chan';
+aop.set('log', logAspect);
+aop.set('cache', cacheAspect);
+aop.set('auth', authAspect);
+
+// 3. 绑定切面
+class UserService {
+  constructor(cache, user) {
+    this.cache = cache;
+    this.user = user;
+  }
+  
+  async getUser(id) {
+    return this.db('users').where({ id }).first();
+  }
+  
+  async deleteUser(id) {
+    return this.db('users').where({ id }).delete();
+  }
+}
+
+const userService = new UserService(cache, currentUser);
+aop.wrap(userService, {
+  getUser: [
+    { type: 'before', log: true },
+    { type: 'before', auth: { role: 'admin' }},
+    { type: 'after', cache: { ttl: 1800 }}
+  ],
+  deleteUser: [
+    { type: 'before', log: true },
+    { type: 'before', auth: { role: 'admin' }}
+  ]
+});
+
+// 4. 正常调用
+const user = await userService.getUser(1);  // 自动执行：before → 权限 → 原方法 → 缓存 → after → 日志
+await userService.deleteUser(1);            // 自动执行：before → 权限 → 原方法 → after → 日志
+```
+
+---
+
+## 六、切面类型说明
+
+| 类型 | 时机 | 用途 | 参数 |
+|------|------|------|------|
+| `before` | 函数执行前 | 日志、权限检查、参数验证 | `ctx`, `args`, `methodName`, `originalMethod` |
+| `after` | 函数执行后 | 缓存、日志、数据清理 | `ctx`, `args`, `methodName`, `originalMethod`, `result` |
+| `error` | 函数出错时 | 错误日志、错误处理、降级 | `ctx`, `args`, `methodName`, `originalMethod`, `error` |
+
+### 切面参数说明
+
+```javascript
+{
+  ctx,              // 上下文对象（实例本身），可访问实例属性和方法
+  methodName,        // 方法名称
+  args,             // 方法参数数组
+  originalMethod,    // 原始方法函数
+  result,           // 方法执行结果（after/error 类型才有）
+  error,            // 错误对象（error 类型才有）
+  params             // 自定义参数（通过配置传递）
+}
+```
+
+---
+
+## 七、配置格式说明
+
+### 基本格式
+```javascript
+{
+  methodName: {
+    type: 'before',        // 切面类型：before/after/error
+    enabled: true,          // 是否启用（默认true，设为false禁用）
+    切面名: true,          // 启用切面（无参数）
+    切面名: { 参数 }       // 启用切面（带参数）
+  }
+}
+```
+
+### 数组格式（多个切面）
+```javascript
+{
+  methodName: [
+    { type: 'before', log: true },
+    { type: 'before', auth: { role: 'admin' }},
+    { type: 'after', cache: { ttl: 3600 }}
+  ]
+}
+```
+
+---
+
+## 八、工具方法
+
+```javascript
+// 注册切面
+aop.set('log', logAspect);
+
+// 获取切面
+const logFn = aop.get('log');
+
+// 移除切面
+aop.remove('log');
+
+// 清空所有切面
+aop.clear();
+```
+
+---
+
+## 九、注意事项
+
+1. **切面函数必须是异步函数**
+   - 因为原方法可能是异步的
+   - 切面函数需要 `await` 原方法
+
+2. **参数浅拷贝**
+   - `args: [...args]` 避免修改原参数
+   - `params: { ...value }` 避免修改配置对象
+
+3. **错误处理**
+   - error 切面执行后会重新抛出异常
+   - 不会阻断原方法的错误流程
+
+4. **切面执行顺序**
+   - before 切面按配置顺序执行
+   - after 切面按配置顺序执行
+   - error 切面按配置顺序执行
+
+5. **around 切面已移除**
+   - 当前版本仅支持 before/after/error 三种类型
+   - around 类型已简化为 before + after 组合

package/base/Aop.js

@@ -0,0 +1,178 @@
+/**
+ * @description: 轻量级切面类 用于注册和执行切面函数
+ * @class Aop
+ * @property {Map} aspects - 存储注册的切面函数
+ * @property {Set} types - 切面类型集合（内置关键字）
+ */
+export class Aop {
+  // 定义内置的切面类型关键字（避免和切面名称冲突）
+  static TYPES = new Set(['type', 'enabled']);
+  // 支持的切面类型（仅保留常用的3种）
+  static SUPPORTED_TYPES = new Set(['before', 'after', 'error']);
+
+  constructor() {
+    this.aspects = new Map();
+  }
+
+  /**
+   * 注册切面
+   * @param {string} name - 切面名称
+   * @param {Function} fn - 切面函数
+   * @returns {Aop} - 当前实例（链式调用）
+   * @throws {TypeError} - 入参类型错误时抛出
+   */
+  set(name, fn) {
+    if (typeof name !== 'string' || !name.trim()) {
+      throw new TypeError(`切面名称 ${name} 必须是非空字符串`);
+    }
+    if (typeof fn !== 'function') {
+      throw new TypeError(`切面 ${name} 必须是函数，当前类型：${typeof fn}`);
+    }
+    this.aspects.set(name.trim(), fn);
+    return this;
+  }
+
+  /**
+   * 获取已注册的切面函数
+   * @param {string} name - 切面名称
+   * @returns {Function|null} - 切面函数（不存在则返回null）
+   */
+  get(name) {
+    return this.aspects.get(name?.trim()) || null;
+  }
+
+  /**
+   * 移除指定切面
+   * @param {string} name - 切面名称
+   * @returns {Aop} - 当前实例
+   */
+  remove(name) {
+    this.aspects.delete(name?.trim());
+    return this;
+  }
+
+  /**
+   * 清空所有切面
+   * @returns {Aop} - 当前实例
+   */
+  clear() {
+    this.aspects.clear();
+    return this;
+  }
+
+  /**
+   * 绑定切面到实例方法
+   * @param {object} instance - 目标实例（如 new Controller()）
+   * @param {object} config - 切面配置 { methodName: [{ type: 'before', enabled: true, log: true }] }
+   * @returns {object} - 绑定后的实例对象
+   * @throws {TypeError} - 入参类型错误时抛出
+   */
+  wrap(instance, config) {
+    if (typeof instance !== 'object' || instance === null) {
+      throw new TypeError('instance 必须是非空对象');
+    }
+    if (typeof config !== 'object' || config === null) {
+      throw new TypeError('config 必须是非空对象');
+    }
+
+    Object.entries(config).forEach(([methodName, rules]) => {
+      const originalMethod = instance[methodName];
+      if (typeof originalMethod !== 'function') {
+        console.warn(`[AOP警告] 实例不存在方法 ${methodName}，跳过切面绑定`);
+        return;
+      }
+
+      // 统一规则为数组 + 过滤禁用规则 + 过滤不支持的类型
+      const ruleList = Array.isArray(rules) ? rules : [rules];
+      const validRules = ruleList.filter(rule => {
+        return rule?.enabled !== false && Aop.SUPPORTED_TYPES.has(rule?.type);
+      });
+
+      // 无有效规则时直接返回原方法
+      if (validRules.length === 0) return;
+
+      // 包装原方法（仅保留 before/after/error 逻辑）
+      instance[methodName] = 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) {
+          // 执行异常切面
+          await this._executeAspectByType(ctx, validRules, 'error', args, originalMethod, null, error);
+          throw error; // 重新抛出异常，不阻断流程
+        }
+
+        return result;
+      };
+    });
+
+    return instance;
+  }
+
+  /**
+   * 按类型批量执行切面（私有方法）
+   * @private
+   * @param {object} ctx - 上下文
+   * @param {Array} validRules - 有效规则列表
+   * @param {string} type - 切面类型（before/after/error）
+   * @param {Array} args - 方法参数
+   * @param {Function} originalMethod - 原方法
+   * @param {*} result - 方法执行结果
+   * @param {Error} error - 方法执行错误
+   */
+  async _executeAspectByType(ctx, validRules, type, args, originalMethod, result = null, error = null) {
+    const rulesOfType = validRules.filter(rule => rule.type === type);
+    for (const rule of rulesOfType) {
+      await this._executeSingleRule(ctx, rule, args, originalMethod, result, error);
+    }
+  }
+
+  /**
+   * 执行单个切面规则（私有方法）
+   * @private
+   * @param {object} ctx - 上下文
+   * @param {object} rule - 单个切面规则
+   * @param {Array} args - 方法参数
+   * @param {Function} originalMethod - 原方法
+   * @param {*} result - 方法执行结果
+   * @param {Error} error - 方法执行错误
+   */
+  async _executeSingleRule(ctx, rule, args, originalMethod, result = null, error = null) {
+    for (const [key, value] of Object.entries(rule)) {
+      // 跳过内置关键字 + 空值
+      if (Aop.TYPES.has(key) || !value) continue;
+
+      const aspectFn = this.get(key);
+      if (!aspectFn) {
+        console.warn(`[AOP警告] 未注册切面 ${key}，跳过执行`);
+        continue;
+      }
+
+      // 构造切面入参（浅拷贝避免原数据被修改）
+      const aspectParams = {
+        ctx,
+        methodName: originalMethod.name || 'anonymous',
+        args: [...args],
+        originalMethod,
+        result,
+        error,
+        params: typeof value === 'object' && !Array.isArray(value) ? { ...value } : {}
+      };
+
+      await aspectFn(aspectParams);
+    }
+  }
+}
+
+// 全局单例
+export const aop = new Aop();
+export default Aop;

package/base/Container.js

@@ -0,0 +1,81 @@
+import fs from 'fs';
+import path from 'path';
+import { Paths } from '../config/paths.js';
+
+export class Container {
+  constructor(type = 'service') {
+    this.map = new Map();
+    this.type = type;
+    this.baseDir = Paths.modulesPath;
+    
+    // 只添加 config 属性，db 由 Service 自己管理
+    this.config = Chan.config;
+  }
+
+  /**
+   * 获取模块下的组件实例
+   * @param {string} moduleName - 模块名 ，例如：'web','api'
+   * @param {string} fileName - 文件名
+   * @returns {Promise<any>} - 组件实例
+   */
+  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) {
+        console.log(`文件 ${fileName}.js 加载后组件实例为空`);
+      }
+      return obj;
+    } catch (err) {
+      console.error(`获取模块 ${moduleName} 下文件 ${fileName}.js 对应的组件失败：${err.message}`);
+    }
+  }
+
+  /**
+   * 设置模块下的组件实例
+   * @param {string} moduleName - 模块名 ，例如：'web','api'
+   * @param {string} fileName - 文件名
+   * @param {any} obj - 组件实例
+   * @returns {Container} - 当前实例
+   */
+  set(moduleName, fileName, obj) {
+    const key = `${moduleName}.${fileName}`;
+    this.map.set(key, obj);
+    return this;
+  }
+
+  /**
+   * 加载模块下的组件实例
+   * @param {string} moduleName - 模块名 ，例如：'web','api'
+   * @param {string} fileName - 文件名
+   * @returns {Promise<any>} - 组件实例
+   */
+  async loadFile(moduleName, fileName) {
+    const filePath = path.resolve(
+      this.baseDir,
+      moduleName,
+      this.type,
+      `${fileName}.js`
+    );
+
+    if (!fs.existsSync(filePath)) {
+      console.log(`模块 ${moduleName} 下 ${this.type} 目录中未找到文件：${fileName}.js`);
+      return null;
+    }
+
+    const module = await import(`file://${filePath}`);
+    const obj = module.default;
+
+    const key = `${moduleName}.${fileName}`;
+    this.map.set(key, obj);
+    return obj;
+  }
+}
+
+export default Container;

package/base/Controller.js

@@ -1,11 +1,14 @@
 import { success, fail } from "../utils/response.js";
+import Container from "./Container.js";
 
 /**
  * 控制器基类
  * 提供统一的响应格式和常用方法
  */
-export default class Controller {
-  constructor() {}
+export default class Controller extends Container {
+  constructor() {
+    super('controller');
+  }
 
   /**
    * 返回成功响应

package/base/Event.js

@@ -0,0 +1,49 @@
+import { EventEmitter } from 'events';
+
+export class Event extends EventEmitter {
+  constructor() {
+    super();
+  }
+
+  /**
+   * 注册事件监听器
+   * @param {string} eventName - 事件名
+   * @param {*} listener - 监听器函数
+   * @returns {Event} - 当前实例
+   */
+  on(eventName, listener) {
+    return super.on(eventName, listener);
+  }
+
+  /**
+   * 触发事件
+   * @param {string} eventName - 事件名
+   * @param {*} data - 事件数据
+   * @returns {Event} - 当前实例
+   */
+  emit(eventName, data) {
+    return super.emit(eventName, data);
+  }
+
+  /**
+   * 注销事件监听器
+   * @param {string} eventName - 事件名
+   * @param {*} listener - 监听器函数
+   * @returns {Event} - 当前实例
+   */
+  off(eventName, listener) {
+    return super.off(eventName, listener);
+  }
+
+  /**
+   * 注销所有事件监听器
+   * @param {string} eventName - 事件名
+   * @returns {Event} - 当前实例
+   */
+  removeAllListeners(eventName) {
+    return super.removeAllListeners(eventName);
+  }
+}
+
+export const event = new Event();
+export default Event;

package/base/Service.js

@@ -2,21 +2,35 @@
  * 数据库服务基类
  * 提供常用的数据库操作方法，包括增删改查、分页查询、事务等
  */
-import { formatTime, formatDateFields } from "../helper/time.js";
+import { formatDateFields } from "../helper/time.js";
+import Container from "./Container.js";
 
-class Service {
+class Service extends Container {
   /**
    * 构造函数
-   * @param {Object} knex - Knex数据库实例
    * @param {string} tableName - 表名
+   * @param {string} dbName - 数据库名称，默认使用默认数据库
    */
-  constructor(knex = null, tableName = null) {
-    if (knex && tableName) {
-      this.db = knex;
+  constructor(tableName = null, dbName = null) {
+    super('service');
+
+    // 根据数据库名称获取，否则使用默认数据库
+    if (dbName) {
+      this.db = Chan.dbManager.get(dbName);
+    } else {
+      this.db = Chan.db;
+    }
+
+    if (tableName) {
       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'];
+    
+    // 自动注册事件监听器（如果子类定义了 on 方法）
+    if (typeof this.on === 'function') {
+      this.on();
+    }
   }
 
   /**

package/helper/index.js

@@ -1,4 +1,4 @@
-export { loaderSort, loadConfig, clearConfigCache, bindInstance, loadController } from "./loader.js";
+export { loaderSort, loadConfig, clearConfigCache, loadController } from "./loader.js";
 export { formatTime } from "./time.js";
 export { formatDateFields } from "./time.js";
 export { default as Cache } from "./cache.js";