mm_machine 2.0.1 → 2.0.2

package/README.md

@@ -1,210 +1,576 @@
 # mm_machine
 
-这是超级美眉框架机制构建辅助模块，用于快速构建一个机制。本模块提供了一个灵活的机制管理系统，支持动态加载、热更新和模块管理等功能。
+一个灵活的Node.js插件化机制系统，用于动态加载、管理和执行模块。
 
-## 特性
+## 快速开始
 
-- 支持动态加载和卸载模块
-- 支持热更新
-- 支持模块状态管理
-- 灵活的配置系统
-- 支持多种运行模式
-
-## 安装
+### 安装
 
 ```bash
-npm install mm_machine
+npm install mm_machine --save
 ```
 
-## 核心类
+### 目录结构
 
-### Item 类
+推荐的项目结构：
 
-`Item` 类是模块的基础类，用于管理单个模块的配置和状态。
+```
+my_project/
+├── index.js           # 主应用入口
+├── app/               # 默认模块目录
+│   ├── module1/       # 模块1
+│   │   ├── config_demo.json  # 配置文件 (注意命名规则)
+│   │   └── index.js          # 模块实现
+│   └── module2/       # 模块2
+│       ├── config_demo.json  # 配置文件
+│       └── main.js           # 模块实现 (可以使用index.js或main.js)
+└── package.json
+```
 
-#### 构造函数
+### 使用示例
 
 ```javascript
-new Item(dir, dir_base)
+const $ = require('mm_expand');
+const Machine = require('mm_machine');
+
+// 创建引擎实例
+const engine = new Machine();
+
+// 初始化并加载模块
+async function init() {
+    // 更新配置（可选）
+    engine.update_config_all({
+        searchPath: './app/'  // 默认路径，可自定义
+    });
+    
+    // 加载所有模块
+    await engine.load_list();
+    
+    // 执行所有模块的main方法
+    const results = await engine.execute('main');
+    console.log('执行结果:', results);
+    
+    // 获取特定模块
+    const demo1 = engine.get('demo1');
+    if (demo1) {
+        console.log('找到模块:', demo1.name);
+    }
+    
+    console.log(`已加载 ${engine.list.length} 个模块`);
+}
+
+// 启动应用
+init().catch(err => {
+    console.error('初始化失败:', err);
+});
 ```
 
-参数：
-- `dir` {String} 当前目录
-- `dir_base` {String} 模块目录
+### 创建模块
 
-#### 属性
+**1. 创建配置文件**
 
-- `dir` {String} 当前路径
-- `default_file` {String} 默认配置文件路径，默认为 "./sys.json"
-- `filename` {String} 当前文件名
-- `config` {Object} 配置参数对象
-  - `name` {String} 模块名称
-  - `title` {String} 模块标题
-  - `description` {String} 模块描述
-  - `func_file` {String} 函数文件路径
-  - `func_name` {String} 回调函数名
-  - `sort` {Number} 排序值
-  - `state` {Number} 状态(0:未启用, 1:启用)
-  - `show` {Number} 显示状态(0:不显示, 1:显示)
-- `mode` {Number} 运行模式
-  - 1: 生产模式，文件改变不会重新加载
-  - 2: 热更新模式，文件改变时重新加载
-  - 3: 重载模式，执行完后重新加载
-  - 4: 热更新+重载模式
+在模块目录中创建 `config_demo.json` 文件（注意命名规则）：
 
-### Index 类
+```json
+{
+    "name": "demo1",
+    "title": "测试模块1",
+    "description": "这是第一个测试模块",
+    "sort": 10,
+    "state": 1,
+    "show": 1,
+    "config": {
+        "debug": true,
+        "timeout": 3000
+    }
+}
+```
 
-`Index` 类是机制管理的核心类，用于管理多个模块。
+**2. 创建模块实现**
 
-#### 构造函数
+在同一目录中创建 `index.js` 或 `main.js` 文件：
 
 ```javascript
-new Index(scope, dir_base)
+const $ = require('mm_expand');
+
+/**
+ * 主方法
+ */
+async function main() {
+    $.log.info(`[${this.name}] 测试模块执行`);
+    
+    // 访问模块配置
+    const debug = this.config.debug;
+    if (debug) {
+        $.log.debug(`[${this.name}] 调试模式已启用`);
+    }
+    
+    return {
+        success: true,
+        message: `${this.name} 执行成功`
+    };
+}
+
+// 导出方法
+module.exports = {
+    main
+};
 ```
 
-参数：
-- `scope` {Object} 作用域
-- `dir_base` {String} 模块目录
+### 重要：文件命名规则
 
-#### 属性
+**配置文件必须按照以下格式命名：**
 
-- `scope` {String} 作用域
-- `list` {Array} 模块列表
-- `type` {String} 机制类型
-- `sort_key` {String} 排序键名
-- `mode` {Number} 运行模式，同 Item 类的 mode
+```
+config_{type}.json
+```
 
-## 使用示例
+其中`{type}`必须与您在Engine类中设置的`this.type`属性值完全匹配。例如：
+- 如果`this.type = "demo"`，配置文件必须命名为`config_demo.json`
+- 如果`this.type = "plugin"`，配置文件必须命名为`config_plugin.json`
 
-### 基础使用
+## 完整使用示例
 
-```javascript
-const { Item, Index } = require('mm_machine');
+### 示例1：创建和管理基础模块
 
-// 创建自定义驱动类
-class Drive extends Item {
-    constructor(dir, dir_base) {
-        super(dir, dir_base);
-        this.default_file = "./demo.json";
-    }
-}
+以下是一个完整的示例，展示如何创建和管理基础模块：
 
-// 创建自定义引擎类
-class Engine extends Index {
-    constructor(scope, dir_base) {
-        super(scope, dir_base);
-        this.mode = 0;
-        this.type = "demo";
-    }
-}
+**1. 项目结构**
 
-Engine.prototype.Drive = Drive;
+```
+my_project/
+├── index.js           # 主应用入口
+├── app/               # 模块目录
+│   ├── demo1/         # 模块1
+│   │   ├── config_demo.json  # 模块配置文件
+│   │   └── index.js          # 模块实现
+│   └── demo2/         # 模块2
+│       ├── config_demo.json  # 模块配置文件
+│       └── main.js           # 模块实现
+└── package.json
+```
 
-// 使用示例
-async function demo() {
-    const engine = new Engine();
-    
+**2. 主应用入口 (`index.js`)**
+
+```javascript
+const $ = require('mm_expand');
+const Machine = require('mm_machine');
+
+// 创建引擎实例
+const engine = new Machine();
+
+// 初始化引擎
+async function init() {
     // 加载模块
-    await engine.update("./");
-    
-    // 执行特定模块的方法
-    await engine.run('demo1', 'init');
-    await engine.exec('demo1', 'init');
+    await engine.load_list();
     
-    // 执行所有模块的方法
-    await engine.run(null, 'main');
-    await engine.exec(null, 'main');
+    // 执行所有模块的main方法
+    await engine.execute('main');
     
     // 获取特定模块
-    const plug = engine.get('demo1');
-    if (plug) {
-        plug.loadFile(plug.filename);
+    const demo1 = engine.get('demo1');
+    if (demo1) {
+        console.log('模块1状态:', demo1.state ? '启用' : '禁用');
+        
+        // 执行特定模块的自定义方法
+        const result = await engine.execute('my_custom_method', 'demo1');
+        console.log('自定义方法结果:', result);
     }
+    
+    // 监听文件变化（热更新模式）
+    engine.mode = 2;
+    engine.watch();
+    
+    console.log(`已加载 ${engine.list.length} 个模块`);
 }
+
+// 启动应用
+init().catch(err => {
+    console.error('初始化失败:', err);
+});
 ```
 
-### 模块配置示例
+**3. 模块配置文件示例 (`app/demo1/config_demo.json`)**
 
 ```json
 {
     "name": "demo1",
-    "title": "示例脚本1",
-    "description": "用于测试动态加载、更新、卸载、删除脚本",
-    "func_file": "./index.js",
-    "func_name": "",
+    "title": "测试模块1",
+    "description": "这是第一个测试模块",
     "sort": 10,
-    "state": 0,
-    "show": 0
+    "state": 1,
+    "show": 1,
+    "config": {
+        "debug": true,
+        "timeout": 3000,
+        "api_key": "your_api_key_here"
+    }
 }
 ```
 
-### 模块实现示例
+**4. 模块实现示例 (`app/demo1/index.js`)**
 
 ```javascript
-var i = 0;
+const $ = require('mm_expand');
+
+// 模块状态变量
+let counter = 0;
+
+/**
+ * 初始化方法
+ */
+async function init() {
+    $.log.info(`[${this.name}] 模块初始化中...`);
+    counter = 0;
+    return true;
+}
 
-function test() {
-    console.log("你好", i++)
+/**
+ * 加载方法
+ */
+async function load() {
+    $.log.info(`[${this.name}] 模块加载中...`);
+    // 可以在这里执行加载资源等操作
+    return true;
 }
 
-function main() {
-    test();
-    return i;
+/**
+ * 主方法
+ * @param {Object} params - 传入参数
+ */
+async function main(params = {}) {
+    $.log.info(`[${this.name}] 主方法执行，当前计数: ${counter++}`);
+    
+    // 访问模块配置
+    const debug = this.config.debug;
+    if (debug) {
+        $.log.debug(`[${this.name}] 调试模式已启用`);
+    }
+    
+    // 返回结果
+    return {
+        success: true,
+        message: `${this.name} 执行成功`,
+        count: counter,
+        params: params
+    };
 }
 
-exports.main = main;
+/**
+ * 主方法执行前钩子
+ */
+async function main_before() {
+    $.log.info(`[${this.name}] 主方法执行前处理`);
+    return true;
+}
 
-exports.main_before = function() {
-    console.log("请求前")
+/**
+ * 主方法执行后钩子
+ */
+async function main_after(result) {
+    $.log.info(`[${this.name}] 主方法执行后处理，结果:`, result);
+    return result;
 }
 
-exports.main_after = async function(ret) {
-    console.log("请求后", ret)
+/**
+ * 自定义方法
+ */
+async function my_custom_method() {
+    return {
+        custom: "这是一个自定义方法",
+        module_name: this.name
+    };
 }
 
-exports.init = function() {
-    console.log("初始化");
+// 导出方法
+module.exports = {
+    init,
+    load,
+    main,
+    main_before,
+    main_after,
+    my_custom_method
+};
+```
+
+### 示例2：使用自定义模块目录
+
+如果需要使用非默认的模块目录，可以按以下方式配置：
+
+```javascript
+const engine = new Machine();
+
+// 使用自定义目录
+engine.update_config_all({
+    searchPath: './custom_modules/'
+});
+
+// 然后加载模块
+await engine.load_list();
+```
+
+### 示例3：实现热更新和动态管理
+
+以下示例展示如何实现模块的热更新和动态管理：
+
+```javascript
+const engine = new Machine();
+
+// 设置为热更新模式
+engine.mode = 2;
+
+// 初始化
+async function setup() {
+    // 加载模块
+    await engine.load_list();
+    
+    // 开始监听文件变化
+    engine.watch();
+    
+    // 定时检查模块数量
+    setInterval(async () => {
+        console.log(`当前模块数量: ${engine.list.length}`);
+    }, 5000);
+    
+    // 模拟动态管理模块
+    setTimeout(async () => {
+        // 重载特定模块
+        await engine.reload('demo1');
+        console.log('已重载模块 demo1');
+    }, 10000);
+    
+    setTimeout(async () => {
+        // 卸载模块
+        await engine.unload('demo2');
+        console.log('已卸载模块 demo2');
+    }, 20000);
 }
+
+setup().catch(console.error);
 ```
 
-## 高级功能
+### 示例4：错误处理和异常捕获
 
-### 热更新
+```javascript
+const engine = new Machine();
+
+async function run() {
+    try {
+        // 加载模块并捕获可能的错误
+        await engine.load_list();
+        
+        // 安全地执行模块方法
+        try {
+            const result = await engine.execute('main');
+            console.log('执行结果:', result);
+        } catch (err) {
+            console.error('执行方法时出错:', err);
+            // 继续执行，不会中断整个应用
+        }
+        
+        // 单独执行特定模块并捕获可能的错误
+        try {
+            const demo1Result = await engine.execute('main', 'demo1');
+            console.log('demo1 执行结果:', demo1Result);
+        } catch (err) {
+            console.error('执行 demo1 时出错:', err);
+        }
+    } catch (err) {
+        console.error('初始化失败:', err);
+    }
+}
 
-系统支持多种运行模式，可以通过设置 `mode` 属性来控制：
+run();
+```
 
-1. 生产模式 (mode = 1)：文件改变不会触发重新加载
-2. 热更新模式 (mode = 2)：文件改变时自动重新加载
-3. 重载模式 (mode = 3)：执行完后重新加载，避免变量污染
-4. 热更新+重载模式 (mode = 4)：结合了模式2和3的特性
+## 高级功能
 
 ### 模块生命周期
 
-模块支持以下生命周期方法：
+每个模块支持完整的生命周期方法：
 
-- `init`: 初始化时调用
-- `main`: 主要执行方法
+- `init`: 模块初始化时调用
+- `load`: 模块加载时调用
+- `main`: 主执行方法
 - `main_before`: 主方法执行前的钩子
 - `main_after`: 主方法执行后的钩子
 
-### 模块管理
+### 运行模式说明
+
+系统支持4种运行模式，可通过`mode`属性设置：
+
+1. **生产模式** (`mode = 1`): 最高性能，文件改变不会触发重新加载
+2. **热更新模式** (`mode = 2`): 文件改变时自动重新加载配置和代码
+3. **重载模式** (`mode = 3`): 执行完后重新加载脚本，避免变量污染
+4. **热更新+重载模式** (`mode = 4`): 结合热更新和重载的特性
+
+### 模块管理API
 
 ```javascript
-// 重载模块
-engine.reload("demo1");
+// 重载特定模块
+await engine.reload("moduleName");
+
+// 卸载模块（保留文件）
+await engine.unload("moduleName");
 
-// 卸载模块
-engine.unload("demo2");
+// 卸载并删除模块文件
+await engine.unload("moduleName", true);
 
-// 卸载并删除模块
-engine.unload("demo1", true);
+// 保存模块配置
+await engine.save();
+
+// 获取特定模块
+const module = engine.get("moduleName");
 ```
 
+### 路径处理
+
+- 所有相对路径都会基于模块的目录进行解析
+- 使用`fullname()`方法可以获取绝对路径，避免路径问题
+
+## 常见问题与故障排除
+
+### 1. 模块无法加载
+
+**检查项目：**
+- 确认配置文件命名格式正确 (`config_{type}.json`)
+- 确认`type`属性与配置文件前缀匹配
+- 检查模块的`state`配置是否为1（启用）
+- 检查文件权限是否正确
+
+### 2. 热更新不工作
+
+**检查项目：**
+- 确认`mode`设置为2或4（热更新模式）
+- 确认文件确实被修改了（注意编辑器的保存设置）
+- 检查文件路径是否正确
+
+### 3. 执行方法返回null
+
+**检查项目：**
+- 确认模块已正确加载 (`engine.list.length > 0`)
+- 确认方法名拼写正确
+- 检查模块实现中是否正确导出了该方法
+- 检查模块的`state`是否为1（启用状态）
+
+### 4. 路径错误
+
+**解决方案：**
+- 使用绝对路径或确保相对路径正确
+- 利用`__dirname`和`fullname()`方法构建可靠的路径
+
+## 模块系统设计理念与工作流程
+
+### 设计理念
+
+mm_machine 模块系统基于以下核心设计理念：
+
+1. **高内聚、低耦合**：每个模块独立封装功能，通过明确的接口与其他模块交互
+2. **可插拔架构**：模块可以动态加载、卸载，不影响系统整体运行
+3. **配置驱动**：通过配置文件控制模块行为，无需修改代码
+4. **生命周期管理**：提供完整的模块生命周期钩子，便于资源管理
+5. **热更新支持**：无需重启应用即可更新模块功能
+
+### 工作流程
+
+以下是模块系统的基本工作流程：
+
+```
+初始化引擎 → 扫描模块目录 → 解析配置文件 → 加载模块代码 → 初始化模块 → 执行方法 → 监听文件变化(热更新模式)
+```
+
+详细工作流程说明：
+
+1. **初始化引擎**：创建 Machine 实例，设置配置项
+2. **扫描模块目录**：根据 searchPath 扫描目录，查找 `config_{type}.json` 文件
+3. **解析配置文件**：读取并解析配置，验证模块状态
+4. **加载模块代码**：根据配置中的信息，动态加载模块的实现文件
+5. **初始化模块**：按排序顺序初始化模块，执行 init 和 load 方法
+6. **执行方法**：根据应用需求，执行模块的特定方法（如 main）
+7. **监听文件变化**：在热更新模式下，监听文件变化并自动重新加载模块
+
+### 数据流向
+
+模块间的数据流转遵循以下规则：
+
+1. 引擎将调用参数传递给模块方法
+2. 模块方法处理后返回结果
+3. 钩子方法可以拦截和修改输入/输出数据
+4. 模块可以访问自己的配置，但不能直接访问其他模块的数据
+
+## 最佳实践与开发建议
+
+### 模块设计最佳实践
+
+1. **单一职责原则**：每个模块应专注于单一功能领域
+2. **接口一致性**：遵循模块生命周期接口约定，确保兼容性
+3. **错误处理**：在模块内部实现完善的错误处理机制
+4. **日志记录**：使用统一的日志接口记录模块活动
+5. **资源管理**：在适当的生命周期钩子中释放资源
+
+### 配置管理建议
+
+1. **配置分层**：将公共配置和模块特有配置分开
+2. **配置验证**：在模块初始化时验证配置有效性
+3. **默认值处理**：为重要配置项提供合理的默认值
+4. **敏感信息保护**：避免在配置文件中直接存储敏感信息
+
+### 性能优化建议
+
+1. **懒加载**：对于资源密集型模块，考虑实现懒加载机制
+2. **缓存策略**：合理使用缓存减少重复计算
+3. **异步操作**：使用 async/await 处理异步操作，避免阻塞
+4. **减少全局状态**：尽量减少模块间的状态共享
+
+### 调试技巧
+
+1. **日志级别**：利用不同级别的日志（debug、info、error）辅助调试
+2. **热更新调试**：使用热更新模式（mode=2）进行开发调试
+3. **模块隔离**：出现问题时，尝试单独测试特定模块
+4. **配置检查**：验证配置文件格式和内容是否正确
+
+### 部署注意事项
+
+1. **生产环境模式**：部署到生产环境时，设置 mode=1 以获得最佳性能
+2. **配置备份**：定期备份模块配置文件
+3. **版本控制**：对模块代码和配置进行版本控制
+4. **依赖管理**：明确声明和管理模块依赖
+
+## 贡献指南
+
+如果您有兴趣为 mm_machine 项目贡献代码或改进，请遵循以下步骤：
+
+1. Fork 项目仓库
+2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 打开 Pull Request
+
+## 更新日志
+
+### v1.0.0 (初始版本)
+- 基础模块管理功能
+- 配置文件加载和解析
+- 模块生命周期管理
+- 热更新支持
+- 基础错误处理
+
+### v1.1.0
+- 改进模块加载逻辑，支持自定义目录
+- 增强错误处理和异常捕获
+- 添加更多生命周期钩子
+- 优化性能和内存使用
+
 ## 依赖
 
 - mm_config: ^1.1.4
 - mm_hot_reload: ^1.0.5
+- mm_expand: 用于路径处理和文件操作
 
 ## 许可证
 
 ISC
+
+## 作者信息
+
+本模块由 mm_modules 团队开发和维护。如有问题或建议，请联系我们。

package/app/test1/demo.json

@@ -0,0 +1,10 @@
+{
+	"name": "test1",
+	"title": "测试模块1",
+	"description": "完整测试模块1",
+	"func_file": "./index.js",
+	"func_name": "",
+	"sort": 10,
+	"state": 1,
+	"show": 1
+}