mm_machine 5.0.1 → 6.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +120 -545
- package/lib/drive.js +13 -21
- package/lib/manager.js +49 -33
- package/lib/mod.js +7 -64
- package/lib/script_protocol.js +43 -40
- package/package.json +12 -12
- package/tool/machine/index.js +51 -0
- package/tool/machine/tool.json +60 -0
package/README.md
CHANGED
|
@@ -1,509 +1,128 @@
|
|
|
1
1
|
# mm_machine
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Node.js 插件机制:按目录扫描受管模块,统一完成注册、生命周期编排、方法调用与热重载。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
当前版本 6.0.0。入口导出 `{ Mod, Drive, Manager, MODE, addMethods }`,`Manager` 是日常使用的管理器类。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## 安装
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
npm install mm_machine --save
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
推荐的项目结构:
|
|
16
|
-
|
|
17
|
-
```
|
|
18
|
-
my_project/
|
|
19
|
-
├── index.js # 主应用入口
|
|
20
|
-
├── app/ # 默认模块目录
|
|
21
|
-
│ ├── module1/ # 模块1
|
|
22
|
-
│ │ ├── config_demo.json # 配置文件 (注意命名规则)
|
|
23
|
-
│ │ └── index.js # 模块实现
|
|
24
|
-
│ └── module2/ # 模块2
|
|
25
|
-
│ ├── config_demo.json # 配置文件
|
|
26
|
-
│ └── main.js # 模块实现 (可以使用index.js或main.js)
|
|
27
|
-
└── package.json
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
### 使用示例
|
|
13
|
+
## 快速开始
|
|
31
14
|
|
|
32
15
|
```javascript
|
|
33
|
-
const
|
|
34
|
-
const
|
|
35
|
-
|
|
36
|
-
// 创建引擎实例
|
|
37
|
-
const engine = new Machine();
|
|
16
|
+
const path = require('path');
|
|
17
|
+
const { Manager, MODE } = require('mm_machine');
|
|
38
18
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
19
|
+
async function run() {
|
|
20
|
+
const manager = new Manager({
|
|
21
|
+
name: 'demo_manager',
|
|
22
|
+
dir: path.join(__dirname, 'modules'),
|
|
23
|
+
filename: 'manager.json',
|
|
24
|
+
mode: MODE.PRODUCTION
|
|
44
25
|
});
|
|
45
26
|
|
|
46
|
-
//
|
|
47
|
-
await
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
const results = await engine.exec('main');
|
|
51
|
-
$.log.debug('执行结果:', results);
|
|
52
|
-
|
|
53
|
-
// 获取特定模块
|
|
54
|
-
const demo1 = engine.get('demo1');
|
|
55
|
-
if (demo1) {
|
|
56
|
-
$.log.debug('找到模块:', demo1.name);
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
$.log.debug(`已加载 ${engine.list.length} 个模块`);
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
// 启动应用
|
|
63
|
-
init().catch((err) => {
|
|
64
|
-
$.log.error('初始化失败:', err);
|
|
65
|
-
});
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
### 创建模块
|
|
69
|
-
|
|
70
|
-
**1. 创建配置文件**
|
|
71
|
-
|
|
72
|
-
在模块目录中创建 `config_demo.json` 文件(注意命名规则):
|
|
27
|
+
await manager.update(); // 扫描目录并注册模块
|
|
28
|
+
await manager.runAll('load'); // 按 sort 顺序执行生命周期
|
|
29
|
+
await manager.runAll('init');
|
|
30
|
+
await manager.runAll('start');
|
|
73
31
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
"name": "demo1",
|
|
77
|
-
"title": "测试模块1",
|
|
78
|
-
"description": "这是第一个测试模块",
|
|
79
|
-
"sort": 10,
|
|
80
|
-
"state": 1,
|
|
81
|
-
"show": 1,
|
|
82
|
-
"options": {
|
|
83
|
-
"debug": true,
|
|
84
|
-
"timeout": 3000
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
**2. 创建模块实现**
|
|
90
|
-
|
|
91
|
-
在同一目录中创建 `index.js` 或 `main.js` 文件:
|
|
32
|
+
console.log(await manager.main('hello', 'greet', '世界')); // 你好,世界!
|
|
33
|
+
console.log(await manager.callMod('hello', 'greet', 'mm_machine'));
|
|
92
34
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
/**
|
|
97
|
-
* 主方法
|
|
98
|
-
*/
|
|
99
|
-
async function main() {
|
|
100
|
-
$.log.info(`[${this.name}] 测试模块执行`);
|
|
101
|
-
|
|
102
|
-
// 访问模块配置
|
|
103
|
-
const debug = this.config.debug;
|
|
104
|
-
if (debug) {
|
|
105
|
-
$.log.debug(`[${this.name}] 调试模式已启用`);
|
|
106
|
-
}
|
|
107
|
-
|
|
108
|
-
return {
|
|
109
|
-
success: true,
|
|
110
|
-
message: `${this.name} 执行成功`
|
|
111
|
-
};
|
|
35
|
+
await manager.getMod('hello').do('stop');
|
|
36
|
+
await manager.unwatch(); // 关闭目录监听
|
|
112
37
|
}
|
|
113
38
|
|
|
114
|
-
|
|
115
|
-
module.exports = {
|
|
116
|
-
main
|
|
117
|
-
};
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
### 重要:文件命名规则
|
|
121
|
-
|
|
122
|
-
**配置文件必须按照以下格式命名:**
|
|
123
|
-
|
|
39
|
+
run().catch(console.error);
|
|
124
40
|
```
|
|
125
|
-
config_{type}.json
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
其中`{type}`必须与您在Engine类中设置的`this.type`属性值完全匹配。例如:
|
|
129
41
|
|
|
130
|
-
|
|
131
|
-
- 如果`this.type = "plugin"`,配置文件必须命名为`config_plugin.json`
|
|
42
|
+
仓库内 `example/index.js` 是可直接运行的完整示例:`npm run demo`。
|
|
132
43
|
|
|
133
|
-
##
|
|
44
|
+
## 导出 API
|
|
134
45
|
|
|
135
|
-
|
|
46
|
+
| 导出 | 说明 |
|
|
47
|
+
|---|---|
|
|
48
|
+
| `Manager` | 受管模块集合:扫描注册、生命周期编排、方法调用、监听热重载 |
|
|
49
|
+
| `Mod` | 受管模块基类:在 `mm_mod.Mod` 之上增加 `do` 流水线与脚本挂载 |
|
|
50
|
+
| `Drive` | 驱动基类:脚本加载、配置读写、模式判断 |
|
|
51
|
+
| `MODE` | 运行模式枚举 |
|
|
52
|
+
| `addMethods` | 把脚本导出的函数批量挂到实例上 |
|
|
136
53
|
|
|
137
|
-
|
|
54
|
+
## 模块目录约定
|
|
138
55
|
|
|
139
|
-
|
|
56
|
+
清单文件名由 `filename` 指定,示例中为 `manager.json`:
|
|
140
57
|
|
|
58
|
+
```text
|
|
59
|
+
modules/
|
|
60
|
+
└── hello/
|
|
61
|
+
├── manager.json # 模块配置(支持 JSON5 注释)
|
|
62
|
+
└── index.js # 模块脚本
|
|
141
63
|
```
|
|
142
|
-
my_project/
|
|
143
|
-
├── index.js # 主应用入口
|
|
144
|
-
├── app/ # 模块目录
|
|
145
|
-
│ ├── demo1/ # 模块1
|
|
146
|
-
│ │ ├── config_demo.json # 模块配置文件
|
|
147
|
-
│ │ └── index.js # 模块实现
|
|
148
|
-
│ └── demo2/ # 模块2
|
|
149
|
-
│ ├── config_demo.json # 模块配置文件
|
|
150
|
-
│ └── main.js # 模块实现
|
|
151
|
-
└── package.json
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
**2. 主应用入口 (`index.js`)**
|
|
155
|
-
|
|
156
|
-
```javascript
|
|
157
|
-
const $ = require('mm_expand');
|
|
158
|
-
const Machine = require('mm_machine');
|
|
159
|
-
|
|
160
|
-
// 创建引擎实例
|
|
161
|
-
const engine = new Machine();
|
|
162
|
-
|
|
163
|
-
// 初始化引擎
|
|
164
|
-
async function init() {
|
|
165
|
-
// 加载模块
|
|
166
|
-
await engine.loads();
|
|
167
64
|
|
|
168
|
-
|
|
169
|
-
await engine.exec('main');
|
|
170
|
-
|
|
171
|
-
// 获取特定模块
|
|
172
|
-
const demo1 = engine.get('demo1');
|
|
173
|
-
if (demo1) {
|
|
174
|
-
$.log.debug('模块1状态:', demo1.state ? '启用' : '禁用');
|
|
175
|
-
|
|
176
|
-
// 执行特定模块的自定义方法
|
|
177
|
-
const result = await engine.exec('my_custom_method', 'demo1');
|
|
178
|
-
$.log.debug('自定义方法结果:', result);
|
|
179
|
-
}
|
|
180
|
-
|
|
181
|
-
// 监听文件变化(热更新模式)
|
|
182
|
-
engine.mode = 2;
|
|
183
|
-
engine.watch();
|
|
184
|
-
|
|
185
|
-
$.log.debug(`已加载 ${engine.list.length} 个模块`);
|
|
186
|
-
}
|
|
187
|
-
|
|
188
|
-
// 启动应用
|
|
189
|
-
init().catch((err) => {
|
|
190
|
-
$.log.error('初始化失败:', err);
|
|
191
|
-
});
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
**3. 模块配置文件示例 (`app/demo1/config_demo.json`)**
|
|
65
|
+
`manager.json` 必填 `name`,常用 `title` / `description` / `main` / `scope` / `state` / `sort` / `options`:
|
|
195
66
|
|
|
196
67
|
```json
|
|
197
68
|
{
|
|
198
|
-
"name": "
|
|
199
|
-
"title": "
|
|
200
|
-
"
|
|
201
|
-
"sort": 10,
|
|
69
|
+
"name": "hello",
|
|
70
|
+
"title": "问候模块",
|
|
71
|
+
"main": "./index.js",
|
|
202
72
|
"state": 1,
|
|
203
|
-
"
|
|
73
|
+
"sort": 10,
|
|
204
74
|
"options": {
|
|
205
|
-
"
|
|
206
|
-
"timeout": 3000,
|
|
207
|
-
"api_key": "your_api_key_here"
|
|
75
|
+
"greeting": { "default": "你好" }
|
|
208
76
|
}
|
|
209
77
|
}
|
|
210
78
|
```
|
|
211
79
|
|
|
212
|
-
|
|
80
|
+
脚本导出的函数挂为模块方法,非函数值挂为模块数据;`this.getOption()` / `this.setOption()` 读写选项,`this.log()` 写日志:
|
|
213
81
|
|
|
214
82
|
```javascript
|
|
215
|
-
const $ = require('mm_expand');
|
|
216
|
-
|
|
217
|
-
// 模块状态变量
|
|
218
|
-
let counter = 0;
|
|
219
|
-
|
|
220
|
-
/**
|
|
221
|
-
* 初始化方法
|
|
222
|
-
*/
|
|
223
|
-
async function init() {
|
|
224
|
-
$.log.info(`[${this.name}] 模块初始化中...`);
|
|
225
|
-
counter = 0;
|
|
226
|
-
return true;
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
/**
|
|
230
|
-
* 加载方法
|
|
231
|
-
*/
|
|
232
|
-
async function load() {
|
|
233
|
-
$.log.info(`[${this.name}] 模块加载中...`);
|
|
234
|
-
// 可以在这里执行加载资源等操作
|
|
235
|
-
return true;
|
|
236
|
-
}
|
|
237
|
-
|
|
238
|
-
/**
|
|
239
|
-
* 主方法
|
|
240
|
-
* @param {Object} params - 传入参数
|
|
241
|
-
*/
|
|
242
|
-
async function main(params = {}) {
|
|
243
|
-
$.log.info(`[${this.name}] 主方法执行,当前计数: ${counter++}`);
|
|
244
|
-
|
|
245
|
-
// 访问模块配置
|
|
246
|
-
const debug = this.config.debug;
|
|
247
|
-
if (debug) {
|
|
248
|
-
$.log.debug(`[${this.name}] 调试模式已启用`);
|
|
249
|
-
}
|
|
250
|
-
|
|
251
|
-
// 返回结果
|
|
252
|
-
return {
|
|
253
|
-
success: true,
|
|
254
|
-
message: `${this.name} 执行成功`,
|
|
255
|
-
count: counter,
|
|
256
|
-
params: params
|
|
257
|
-
};
|
|
258
|
-
}
|
|
259
|
-
|
|
260
|
-
/**
|
|
261
|
-
* 主方法执行前钩子
|
|
262
|
-
*/
|
|
263
|
-
async function main_before() {
|
|
264
|
-
$.log.info(`[${this.name}] 主方法执行前处理`);
|
|
265
|
-
return true;
|
|
266
|
-
}
|
|
267
|
-
|
|
268
|
-
/**
|
|
269
|
-
* 主方法执行后钩子
|
|
270
|
-
*/
|
|
271
|
-
async function main_after(result) {
|
|
272
|
-
$.log.info(`[${this.name}] 主方法执行后处理,结果:`, result);
|
|
273
|
-
return result;
|
|
274
|
-
}
|
|
275
|
-
|
|
276
|
-
/**
|
|
277
|
-
* 自定义方法
|
|
278
|
-
*/
|
|
279
|
-
async function my_custom_method() {
|
|
280
|
-
return {
|
|
281
|
-
custom: '这是一个自定义方法',
|
|
282
|
-
module_name: this.name
|
|
283
|
-
};
|
|
284
|
-
}
|
|
285
|
-
|
|
286
|
-
// 导出方法
|
|
287
83
|
module.exports = {
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
### 示例2:使用自定义模块目录
|
|
298
|
-
|
|
299
|
-
如果需要使用非默认的模块目录,可以按以下方式配置:
|
|
300
|
-
|
|
301
|
-
```javascript
|
|
302
|
-
const engine = new Machine();
|
|
303
|
-
|
|
304
|
-
// 使用自定义目录
|
|
305
|
-
engine.update_config_all({
|
|
306
|
-
searchPath: './custom_modules/'
|
|
307
|
-
});
|
|
308
|
-
|
|
309
|
-
// 然后加载模块
|
|
310
|
-
await engine.loads();
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
### 示例3:实现热更新和动态管理
|
|
314
|
-
|
|
315
|
-
以下示例展示如何实现模块的热更新和动态管理:
|
|
316
|
-
|
|
317
|
-
```javascript
|
|
318
|
-
const engine = new Machine();
|
|
319
|
-
|
|
320
|
-
// 设置为热更新模式
|
|
321
|
-
engine.mode = 2;
|
|
322
|
-
|
|
323
|
-
// 初始化
|
|
324
|
-
async function setup() {
|
|
325
|
-
// 加载模块
|
|
326
|
-
await engine.loads();
|
|
327
|
-
|
|
328
|
-
// 开始监听文件变化
|
|
329
|
-
engine.watch();
|
|
330
|
-
|
|
331
|
-
// 定时检查模块数量
|
|
332
|
-
setInterval(async () => {
|
|
333
|
-
$.log.debug(`当前模块数量: ${engine.list.length}`);
|
|
334
|
-
}, 5000);
|
|
335
|
-
|
|
336
|
-
// 模拟动态管理模块
|
|
337
|
-
setTimeout(async () => {
|
|
338
|
-
// 重载特定模块
|
|
339
|
-
await engine.reload('demo1');
|
|
340
|
-
$.log.debug('已重载模块 demo1');
|
|
341
|
-
}, 10000);
|
|
342
|
-
|
|
343
|
-
setTimeout(async () => {
|
|
344
|
-
// 卸载模块
|
|
345
|
-
await engine.unload('demo2');
|
|
346
|
-
$.log.debug('已卸载模块 demo2');
|
|
347
|
-
}, 20000);
|
|
348
|
-
}
|
|
349
|
-
|
|
350
|
-
setup().catch($.log.error);
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
### 示例4:错误处理和异常捕获
|
|
354
|
-
|
|
355
|
-
```javascript
|
|
356
|
-
const engine = new Machine();
|
|
357
|
-
|
|
358
|
-
async function run() {
|
|
359
|
-
try {
|
|
360
|
-
// 加载模块并捕获可能的错误
|
|
361
|
-
await engine.loads();
|
|
362
|
-
|
|
363
|
-
// 安全地执行模块方法
|
|
364
|
-
try {
|
|
365
|
-
const result = await engine.exec('main');
|
|
366
|
-
$.log.debug('执行结果:', result);
|
|
367
|
-
} catch (err) {
|
|
368
|
-
$.log.error('执行方法时出错:', err);
|
|
369
|
-
// 继续执行,不会中断整个应用
|
|
370
|
-
}
|
|
371
|
-
|
|
372
|
-
// 单独执行特定模块并捕获可能的错误
|
|
373
|
-
try {
|
|
374
|
-
const demo1Result = await engine.exec('main', 'demo1');
|
|
375
|
-
$.log.debug('demo1 执行结果:', demo1Result);
|
|
376
|
-
} catch (err) {
|
|
377
|
-
$.log.error('执行 demo1 时出错:', err);
|
|
378
|
-
}
|
|
379
|
-
} catch (err) {
|
|
380
|
-
$.log.error('初始化失败:', err);
|
|
84
|
+
async _init() {
|
|
85
|
+
this.log('info', '模块初始化完成');
|
|
86
|
+
},
|
|
87
|
+
async greet(name) {
|
|
88
|
+
return `${this.getOption('greeting')},${name}!`;
|
|
89
|
+
},
|
|
90
|
+
async main(...args) {
|
|
91
|
+
return `main 参数:${JSON.stringify(args)}`;
|
|
381
92
|
}
|
|
382
|
-
}
|
|
383
|
-
|
|
384
|
-
run();
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
## 高级功能
|
|
388
|
-
|
|
389
|
-
### 模块生命周期
|
|
390
|
-
|
|
391
|
-
每个模块支持完整的生命周期方法:
|
|
392
|
-
|
|
393
|
-
- `init`: 模块初始化时调用
|
|
394
|
-
- `load`: 模块加载时调用
|
|
395
|
-
- `main`: 主执行方法
|
|
396
|
-
- `main_before`: 主方法执行前的钩子
|
|
397
|
-
- `main_after`: 主方法执行后的钩子
|
|
398
|
-
|
|
399
|
-
### 运行模式说明
|
|
400
|
-
|
|
401
|
-
系统支持4种运行模式,可通过`mode`属性设置:
|
|
402
|
-
|
|
403
|
-
1. **生产模式** (`mode = 1`): 最高性能,文件改变不会触发重新加载
|
|
404
|
-
2. **热更新模式** (`mode = 2`): 文件改变时自动重新加载配置和代码
|
|
405
|
-
3. **重载模式** (`mode = 3`): 执行完后重新加载脚本,避免变量污染
|
|
406
|
-
4. **热更新+重载模式** (`mode = 4`): 结合热更新和重载的特性
|
|
407
|
-
|
|
408
|
-
### 模块管理API
|
|
409
|
-
|
|
410
|
-
```javascript
|
|
411
|
-
// 重载特定模块
|
|
412
|
-
await engine.reload('moduleName');
|
|
413
|
-
|
|
414
|
-
// 卸载模块(保留文件)
|
|
415
|
-
await engine.unload('moduleName');
|
|
416
|
-
|
|
417
|
-
// 卸载并删除模块文件
|
|
418
|
-
await engine.unload('moduleName', true);
|
|
419
|
-
|
|
420
|
-
// 保存模块配置
|
|
421
|
-
await engine.save();
|
|
422
|
-
|
|
423
|
-
// 获取特定模块
|
|
424
|
-
const module = engine.get('moduleName');
|
|
93
|
+
};
|
|
425
94
|
```
|
|
426
95
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
- 所有相对路径都会基于模块的目录进行解析
|
|
430
|
-
- 使用`fullname()`方法可以获取绝对路径,避免路径问题
|
|
431
|
-
|
|
432
|
-
## 常见问题与故障排除
|
|
433
|
-
|
|
434
|
-
### 1. 模块无法加载
|
|
435
|
-
|
|
436
|
-
**检查项目:**
|
|
96
|
+
## 生命周期与调用
|
|
437
97
|
|
|
438
|
-
-
|
|
439
|
-
-
|
|
440
|
-
-
|
|
441
|
-
-
|
|
98
|
+
- 单模块:`await mod.do('load' | 'init' | 'start' | 'stop' | 'unload' | 'destroy')`
|
|
99
|
+
- 批量:`await manager.runAll('load')`,按 `sort` 顺序编排全部受管模块
|
|
100
|
+
- 调用方法:`await manager.main(name, method, ...args)`、`await manager.callMod(name, method, ...args)`;`manager.main(null, ...)` 广播
|
|
101
|
+
- 查询:`getMod(name)` / `getInfo(name)` / `getInfos()` / `getList(keyword)` / `isRunning(name)`
|
|
102
|
+
- 关闭监听:`await manager.unwatch()`
|
|
442
103
|
|
|
443
|
-
|
|
104
|
+
## 运行模式
|
|
444
105
|
|
|
445
|
-
|
|
106
|
+
`MODE` 为只读枚举,构造时通过 `config.mode` 传入:
|
|
446
107
|
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
108
|
+
| 常量 | 值 | 含义 |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `MODE.PRODUCTION` | 1 | 生产模式,不监听文件变化 |
|
|
111
|
+
| `MODE.HOT_CONFIG` | 2 | 热更新配置 |
|
|
112
|
+
| `MODE.HOT_RELOAD` | 3 | 热重载脚本 |
|
|
113
|
+
| `MODE.HOT_BOTH` | 4 | 配置 + 脚本同时热更新 |
|
|
114
|
+
| `MODE.RELOAD_ALWAYS` | 5 | 始终重载 |
|
|
450
115
|
|
|
451
|
-
|
|
116
|
+
## 目录监听与热重载
|
|
452
117
|
|
|
453
|
-
|
|
118
|
+
`update(dir)` 完成后会对检索目录开启一次递归监听(经 `mm_loader` 的 `Loader.watch`,配置文件与 `.js` 脚本的变更按扩展名分流):
|
|
454
119
|
|
|
455
|
-
-
|
|
456
|
-
- 确认方法名拼写正确
|
|
457
|
-
- 检查模块实现中是否正确导出了该方法
|
|
458
|
-
- 检查模块的`state`是否为1(启用状态)
|
|
459
|
-
|
|
460
|
-
### 4. 路径错误
|
|
461
|
-
|
|
462
|
-
**解决方案:**
|
|
463
|
-
|
|
464
|
-
- 使用绝对路径或确保相对路径正确
|
|
465
|
-
- 利用`__dirname`和`fullname()`方法构建可靠的路径
|
|
466
|
-
|
|
467
|
-
## 模块系统设计理念与工作流程
|
|
468
|
-
|
|
469
|
-
### 设计理念
|
|
470
|
-
|
|
471
|
-
mm_machine 模块系统基于以下核心设计理念:
|
|
472
|
-
|
|
473
|
-
1. **高内聚、低耦合**:每个模块独立封装功能,通过明确的接口与其他模块交互
|
|
474
|
-
2. **可插拔架构**:模块可以动态加载、卸载,不影响系统整体运行
|
|
475
|
-
3. **配置驱动**:通过配置文件控制模块行为,无需修改代码
|
|
476
|
-
4. **生命周期管理**:提供完整的模块生命周期钩子,便于资源管理
|
|
477
|
-
5. **热更新支持**:无需重启应用即可更新模块功能
|
|
478
|
-
|
|
479
|
-
### 工作流程
|
|
480
|
-
|
|
481
|
-
以下是模块系统的基本工作流程:
|
|
482
|
-
|
|
483
|
-
```
|
|
484
|
-
初始化引擎 → 扫描模块目录 → 解析配置文件 → 加载模块代码 → 初始化模块 → 执行方法 → 监听文件变化(热更新模式)
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
详细工作流程说明:
|
|
488
|
-
|
|
489
|
-
1. **初始化引擎**:创建 Machine 实例,设置配置项
|
|
490
|
-
2. **扫描模块目录**:根据 searchPath 扫描目录,查找 `config_{type}.json` 文件
|
|
491
|
-
3. **解析配置文件**:读取并解析配置,验证模块状态
|
|
492
|
-
4. **加载模块代码**:根据配置中的信息,动态加载模块的实现文件
|
|
493
|
-
5. **初始化模块**:按排序顺序初始化模块,执行 init 和 load 方法
|
|
494
|
-
6. **执行方法**:根据应用需求,执行模块的特定方法(如 main)
|
|
495
|
-
7. **监听文件变化**:在热更新模式下,监听文件变化并自动重新加载模块
|
|
496
|
-
|
|
497
|
-
#### 目录监听与热重载
|
|
498
|
-
|
|
499
|
-
`update(dir)` 完成后会对检索目录开启一次递归监听(经 mm_loader 的 `Loader.watch`,配置文件与 `.js` 脚本的变更按扩展名分流):
|
|
500
|
-
|
|
501
|
-
- 所有管理器默认共享 mm_loader 的同一个加载器实例(`loadAdmin(config.use_scope || 'os')`),避免重复扫描、重复监听与重复加载
|
|
120
|
+
- 所有管理器默认共享 mm_loader 的同一个加载器实例(`loadAdmin(config.load_scope || 'app')`),避免重复扫描、重复监听与重复加载
|
|
502
121
|
- 管理器把自己的清单文件名登记为加载器类型:类型键为文件名去掉 `.json` 后缀(`manager.json` → `manager`),已存在的类型不覆盖
|
|
503
|
-
- 需要独立加载器时,用 `
|
|
122
|
+
- 需要独立加载器时,用 `load_scope` 指定另一加载器名
|
|
504
123
|
|
|
505
124
|
| 变更 | 模式要求 | 行为 |
|
|
506
|
-
|
|
125
|
+
|---|---|---|
|
|
507
126
|
| 配置文件新增 | 任意 | 按配置文件注册模块,非懒加载时立即加载 |
|
|
508
127
|
| 配置文件修改 | `mode >= 2`(热更新配置) | 同步配置快照并应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本 |
|
|
509
128
|
| 配置文件删除 | 任意 | 注销模块(停止 → 卸载 → 移除记录) |
|
|
@@ -512,121 +131,69 @@ mm_machine 模块系统基于以下核心设计理念:
|
|
|
512
131
|
| 脚本新增/重建 | `mode = 3 / 4` | 同目录存在同名配置文件时补注册,非懒加载时立即加载 |
|
|
513
132
|
| 脚本内容修改 | `mode = 3 / 4` | 是受管模块的入口:管理器重载脚本(清 require 缓存后重新加载并重挂方法);非入口:仅失效自身 require 缓存 |
|
|
514
133
|
|
|
515
|
-
- 脚本变更按**入口精确匹配**:只有变更文件是某个受管模块的入口脚本才触发重载/注销;公共脚本(com/lib 等)变化只失效自身的 require
|
|
516
|
-
- 脚本事件只在热重载模式(`MODE.HOT_RELOAD` / `MODE.HOT_BOTH
|
|
517
|
-
- 热更新不依赖 `mm_hot_reload`:配置与脚本的变化均由管理器的目录监听(mm_loader)统一接管;`mm_hot_reload` 仅供函数自行应用其他模块时选用
|
|
134
|
+
- 脚本变更按**入口精确匹配**:只有变更文件是某个受管模块的入口脚本才触发重载/注销;公共脚本(com/lib 等)变化只失效自身的 require 缓存,不追溯引用方
|
|
135
|
+
- 脚本事件只在热重载模式(`MODE.HOT_RELOAD` / `MODE.HOT_BOTH`)下纳入监听,生产与仅热更新配置模式不扫描脚本
|
|
518
136
|
- 调用 `unwatch()` 可关闭全部目录监听
|
|
519
137
|
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
模块间的数据流转遵循以下规则:
|
|
523
|
-
|
|
524
|
-
1. 引擎将调用参数传递给模块方法
|
|
525
|
-
2. 模块方法处理后返回结果
|
|
526
|
-
3. 钩子方法可以拦截和修改输入/输出数据
|
|
527
|
-
4. 模块可以访问自己的配置,但不能直接访问其他模块的数据
|
|
138
|
+
## 常见问题
|
|
528
139
|
|
|
529
|
-
|
|
140
|
+
- **模块数为 0**:检查 `dir` 是否为绝对路径、`filename` 是否与清单文件名一致、`state` 是否为 1
|
|
141
|
+
- **热更新不生效**:确认 `mode` 为 `MODE.HOT_CONFIG` / `HOT_RELOAD` / `HOT_BOTH`,且 `update()` 已执行
|
|
142
|
+
- **方法返回 null**:确认模块已 `runAll('load')` / `runAll('init')`,且脚本确实导出了该同名函数
|
|
530
143
|
|
|
531
|
-
|
|
144
|
+
## 测试
|
|
532
145
|
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
5. **资源管理**:在适当的生命周期钩子中释放资源
|
|
538
|
-
|
|
539
|
-
### 配置管理建议
|
|
540
|
-
|
|
541
|
-
1. **配置分层**:将公共配置和模块特有配置分开
|
|
542
|
-
2. **配置验证**:在模块初始化时验证配置有效性
|
|
543
|
-
3. **默认值处理**:为重要配置项提供合理的默认值
|
|
544
|
-
4. **敏感信息保护**:避免在配置文件中直接存储敏感信息
|
|
545
|
-
|
|
546
|
-
### 性能优化建议
|
|
547
|
-
|
|
548
|
-
1. **懒加载**:对于资源密集型模块,考虑实现懒加载机制
|
|
549
|
-
2. **缓存策略**:合理使用缓存减少重复计算
|
|
550
|
-
3. **异步操作**:使用 async/await 处理异步操作,避免阻塞
|
|
551
|
-
4. **减少全局状态**:尽量减少模块间的状态共享
|
|
552
|
-
|
|
553
|
-
### 调试技巧
|
|
146
|
+
```bash
|
|
147
|
+
npm test # jest --coverage
|
|
148
|
+
npm run demo # 运行 example/index.js
|
|
149
|
+
```
|
|
554
150
|
|
|
555
|
-
|
|
556
|
-
2. **热更新调试**:使用热更新模式(mode=2)进行开发调试
|
|
557
|
-
3. **模块隔离**:出现问题时,尝试单独测试特定模块
|
|
558
|
-
4. **配置检查**:验证配置文件格式和内容是否正确
|
|
151
|
+
## 依赖
|
|
559
152
|
|
|
560
|
-
|
|
153
|
+
运行时依赖均按 npm 线上版本声明:
|
|
561
154
|
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
155
|
+
| 包 | 用途 |
|
|
156
|
+
|---|---|
|
|
157
|
+
| `mm_mod` | 生命周期与配置基类,Manager/Mod/Drive 均继承其能力 |
|
|
158
|
+
| `mm_loader` | 目录扫描、清单解析与文件监听(热更新唯一入口) |
|
|
159
|
+
| `mm_scanner` | `typeStore(type)` 读取扫描结果,避免各管理器重复扫描 |
|
|
160
|
+
| `mm_files` | 配置/脚本的读写、路径与存在性判断 |
|
|
161
|
+
| `mm_helper` | 字符串处理与通用工具函数 |
|
|
162
|
+
| `mm_tpl` | 驱动生成配置/脚本时使用的模板 |
|
|
163
|
+
| `@prettier/sync` | `Drive.prettyCode()` 运行时格式化生成的配置与脚本代码 |
|
|
566
164
|
|
|
567
|
-
##
|
|
165
|
+
## 更新日志
|
|
568
166
|
|
|
569
|
-
|
|
167
|
+
### 6.0.0
|
|
570
168
|
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
5. 打开 Pull Request
|
|
576
|
-
|
|
577
|
-
## 更新日志
|
|
169
|
+
- 加载器实例键改为 `load_scope`(即 `Loader.name`),不再拼接 `@目录`
|
|
170
|
+
- `_findFiles` 改为「扫描一次 + 按类型取切片」:先 `ensureScanned()`,再从 `typeStore(type)` 读取条目
|
|
171
|
+
- 依赖升级:`mm_loader ^7.0.0`、新增 `mm_scanner ^5.0.0` 与 `mm_store ^1.0.1`
|
|
172
|
+
- 移除未使用的 `use_scope` 配置
|
|
578
173
|
|
|
579
174
|
### 5.0.1
|
|
580
175
|
|
|
581
|
-
-
|
|
582
|
-
-
|
|
176
|
+
- `mm_loader@^4.0.1` 修复 `load()` 额外对整串 `{表达式}` 做模板求值的 BUG
|
|
177
|
+
- 配置加载职责保持在 mm_machine 这一层,子类不必覆盖 `_readModConfig`
|
|
583
178
|
|
|
584
179
|
### v4.1.0
|
|
585
180
|
|
|
586
|
-
-
|
|
587
|
-
-
|
|
588
|
-
- `_getLoader()` 直接取 mm_loader 实例池中的 `Loader`,不再自行缓存引用;需要独立实例时用 `config.use_scope` 指定另一共享作用域
|
|
589
|
-
- `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除,不影响其他调用方的监听
|
|
590
|
-
- `_findFiles` 改用 `Loader.scan`(物理扫描唯一入口),保证 `update` 能看到新增/删除的文件
|
|
591
|
-
- 依赖 mm_loader ^3.0.0
|
|
181
|
+
- 配置加载器改为共享实例;清单类型按文件名推导登记
|
|
182
|
+
- `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除
|
|
592
183
|
|
|
593
184
|
### v4.0.0
|
|
594
185
|
|
|
595
|
-
-
|
|
596
|
-
-
|
|
597
|
-
- `_watchDir` 复用同一个 Loader:配置回调与脚本回调一次 watch 分流,删除独立的脚本订阅路径
|
|
598
|
-
- 依赖 mm_loader ^2.0.0
|
|
186
|
+
- 热更新收敛到管理器,脚本变更改为入口精确匹配
|
|
187
|
+
- `_watchDir` 复用同一个 Loader,配置回调与脚本回调一次 watch 分流
|
|
599
188
|
|
|
600
189
|
### v3.6.0
|
|
601
190
|
|
|
602
|
-
- 移除对 `mm_hot_reload`
|
|
603
|
-
- 修正 `Drive.setConfig
|
|
604
|
-
- 热更新配置模式下,配置变化同步应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本
|
|
605
|
-
- 热重载模式下,脚本内容变化由管理器重载(清缓存后重新 require 并重挂方法)
|
|
606
|
-
- 移除 `Drive.watchConfig`、`_loadHotReload`,`_handleHotReload` 更名为 `_applyConfigUpdate`
|
|
607
|
-
|
|
608
|
-
### v1.0.0 (初始版本)
|
|
609
|
-
|
|
610
|
-
- 基础模块管理功能
|
|
611
|
-
- 配置文件加载和解析
|
|
612
|
-
- 模块生命周期管理
|
|
613
|
-
- 热更新支持
|
|
614
|
-
- 基础错误处理
|
|
191
|
+
- 移除对 `mm_hot_reload` 的依赖,热更新全部由管理器目录监听接管
|
|
192
|
+
- 修正 `Drive.setConfig` 原地深合并;新增 `_applyConfigUpdate`
|
|
615
193
|
|
|
616
|
-
### v1.1.0
|
|
194
|
+
### v1.1.0 / v1.0.0
|
|
617
195
|
|
|
618
|
-
-
|
|
619
|
-
- 增强错误处理和异常捕获
|
|
620
|
-
- 添加更多生命周期钩子
|
|
621
|
-
- 优化性能和内存使用
|
|
622
|
-
|
|
623
|
-
## 依赖
|
|
624
|
-
|
|
625
|
-
- mm_config: ^2.5.3
|
|
626
|
-
- mm_helper: ^1.0.3
|
|
627
|
-
- mm_loader: ^3.0.0(目录监听与配置/脚本热更新)
|
|
628
|
-
- mm_mod: ^1.0.6
|
|
629
|
-
- mm_tpl: ^2.7.3
|
|
196
|
+
- 基础模块管理、配置加载、生命周期与热更新支持
|
|
630
197
|
|
|
631
198
|
## 许可证
|
|
632
199
|
|
|
@@ -634,4 +201,12 @@ ISC
|
|
|
634
201
|
|
|
635
202
|
## 作者信息
|
|
636
203
|
|
|
637
|
-
本模块由 mm_modules
|
|
204
|
+
本模块由 mm_modules 团队开发和维护。
|
|
205
|
+
|
|
206
|
+
## 工具契约(LLM 可调用)
|
|
207
|
+
|
|
208
|
+
`tool/` 下登记的工具契约,实现位于 `tool/<name>/index.js`:
|
|
209
|
+
|
|
210
|
+
| 工具名 | 标题 | 说明 |
|
|
211
|
+
|---|---|---|
|
|
212
|
+
| `machine` | 插件机制契约自省 | 列出 `MODE` 枚举、`Mod` / `Drive` / `Manager` 的公开方法清单与生命周期顺序;参数 `action=modes|classes` |
|