mm_machine 6.0.0 → 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 +117 -549
- package/lib/drive.js +13 -21
- package/lib/manager.js +13 -16
- package/lib/mod.js +7 -64
- package/lib/script_protocol.js +43 -40
- package/package.json +10 -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
|
-
|
|
454
|
-
|
|
455
|
-
- 确认模块已正确加载 (`engine.list.length > 0`)
|
|
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` 脚本的变更按扩展名分流):
|
|
118
|
+
`update(dir)` 完成后会对检索目录开启一次递归监听(经 `mm_loader` 的 `Loader.watch`,配置文件与 `.js` 脚本的变更按扩展名分流):
|
|
500
119
|
|
|
501
120
|
- 所有管理器默认共享 mm_loader 的同一个加载器实例(`loadAdmin(config.load_scope || 'app')`),避免重复扫描、重复监听与重复加载
|
|
502
121
|
- 管理器把自己的清单文件名登记为加载器类型:类型键为文件名去掉 `.json` 后缀(`manager.json` → `manager`),已存在的类型不覆盖
|
|
503
|
-
- 需要独立加载器时,用 `load_scope`
|
|
122
|
+
- 需要独立加载器时,用 `load_scope` 指定另一加载器名
|
|
504
123
|
|
|
505
124
|
| 变更 | 模式要求 | 行为 |
|
|
506
|
-
|
|
125
|
+
|---|---|---|
|
|
507
126
|
| 配置文件新增 | 任意 | 按配置文件注册模块,非懒加载时立即加载 |
|
|
508
127
|
| 配置文件修改 | `mode >= 2`(热更新配置) | 同步配置快照并应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本 |
|
|
509
128
|
| 配置文件删除 | 任意 | 注销模块(停止 → 卸载 → 移除记录) |
|
|
@@ -512,128 +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
|
-
### 调试技巧
|
|
554
|
-
|
|
555
|
-
1. **日志级别**:利用不同级别的日志(debug、info、error)辅助调试
|
|
556
|
-
2. **热更新调试**:使用热更新模式(mode=2)进行开发调试
|
|
557
|
-
3. **模块隔离**:出现问题时,尝试单独测试特定模块
|
|
558
|
-
4. **配置检查**:验证配置文件格式和内容是否正确
|
|
559
|
-
|
|
560
|
-
### 部署注意事项
|
|
561
|
-
|
|
562
|
-
1. **生产环境模式**:部署到生产环境时,设置 mode=1 以获得最佳性能
|
|
563
|
-
2. **配置备份**:定期备份模块配置文件
|
|
564
|
-
3. **版本控制**:对模块代码和配置进行版本控制
|
|
565
|
-
4. **依赖管理**:明确声明和管理模块依赖
|
|
146
|
+
```bash
|
|
147
|
+
npm test # jest --coverage
|
|
148
|
+
npm run demo # 运行 example/index.js
|
|
149
|
+
```
|
|
566
150
|
|
|
567
|
-
##
|
|
151
|
+
## 依赖
|
|
568
152
|
|
|
569
|
-
|
|
153
|
+
运行时依赖均按 npm 线上版本声明:
|
|
570
154
|
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
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()` 运行时格式化生成的配置与脚本代码 |
|
|
576
164
|
|
|
577
165
|
## 更新日志
|
|
578
166
|
|
|
579
167
|
### 6.0.0
|
|
580
168
|
|
|
581
|
-
- 加载器实例键改为 `load_scope`(即 `Loader.name`),不再拼接
|
|
582
|
-
- `_findFiles` 改为「扫描一次 + 按类型取切片」:先 `
|
|
583
|
-
- 依赖升级:`mm_loader ^7.0.0`、新增 `mm_scanner ^5.0.0` 与 `mm_store ^1.0.1
|
|
584
|
-
- 移除未使用的 `use_scope`
|
|
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` 配置
|
|
585
173
|
|
|
586
174
|
### 5.0.1
|
|
587
175
|
|
|
588
|
-
-
|
|
589
|
-
-
|
|
176
|
+
- `mm_loader@^4.0.1` 修复 `load()` 额外对整串 `{表达式}` 做模板求值的 BUG
|
|
177
|
+
- 配置加载职责保持在 mm_machine 这一层,子类不必覆盖 `_readModConfig`
|
|
590
178
|
|
|
591
179
|
### v4.1.0
|
|
592
180
|
|
|
593
|
-
-
|
|
594
|
-
-
|
|
595
|
-
- `_getLoader()` 直接取 mm_loader 实例池中的 `Loader`,不再自行缓存引用;需要独立实例时用 `config.use_scope` 指定另一共享作用域
|
|
596
|
-
- `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除,不影响其他调用方的监听
|
|
597
|
-
- `_findFiles` 改用 `Loader.scan`(物理扫描唯一入口),保证 `update` 能看到新增/删除的文件
|
|
598
|
-
- 依赖 mm_loader ^3.0.0
|
|
181
|
+
- 配置加载器改为共享实例;清单类型按文件名推导登记
|
|
182
|
+
- `_watchDir` 保存回调引用,`unwatch` 按回调从共享实例上摘除
|
|
599
183
|
|
|
600
184
|
### v4.0.0
|
|
601
185
|
|
|
602
|
-
-
|
|
603
|
-
-
|
|
604
|
-
- `_watchDir` 复用同一个 Loader:配置回调与脚本回调一次 watch 分流,删除独立的脚本订阅路径
|
|
605
|
-
- 依赖 mm_loader ^2.0.0
|
|
186
|
+
- 热更新收敛到管理器,脚本变更改为入口精确匹配
|
|
187
|
+
- `_watchDir` 复用同一个 Loader,配置回调与脚本回调一次 watch 分流
|
|
606
188
|
|
|
607
189
|
### v3.6.0
|
|
608
190
|
|
|
609
|
-
- 移除对 `mm_hot_reload`
|
|
610
|
-
- 修正 `Drive.setConfig
|
|
611
|
-
- 热更新配置模式下,配置变化同步应用到模块(触发 `_onConfigChange` 钩子与 `config:change` 事件),`main` 指向变化时重载脚本
|
|
612
|
-
- 热重载模式下,脚本内容变化由管理器重载(清缓存后重新 require 并重挂方法)
|
|
613
|
-
- 移除 `Drive.watchConfig`、`_loadHotReload`,`_handleHotReload` 更名为 `_applyConfigUpdate`
|
|
614
|
-
|
|
615
|
-
### v1.0.0 (初始版本)
|
|
616
|
-
|
|
617
|
-
- 基础模块管理功能
|
|
618
|
-
- 配置文件加载和解析
|
|
619
|
-
- 模块生命周期管理
|
|
620
|
-
- 热更新支持
|
|
621
|
-
- 基础错误处理
|
|
191
|
+
- 移除对 `mm_hot_reload` 的依赖,热更新全部由管理器目录监听接管
|
|
192
|
+
- 修正 `Drive.setConfig` 原地深合并;新增 `_applyConfigUpdate`
|
|
622
193
|
|
|
623
|
-
### v1.1.0
|
|
194
|
+
### v1.1.0 / v1.0.0
|
|
624
195
|
|
|
625
|
-
-
|
|
626
|
-
- 增强错误处理和异常捕获
|
|
627
|
-
- 添加更多生命周期钩子
|
|
628
|
-
- 优化性能和内存使用
|
|
629
|
-
|
|
630
|
-
## 依赖
|
|
631
|
-
|
|
632
|
-
- mm_config: ^2.5.3
|
|
633
|
-
- mm_helper: ^1.0.3
|
|
634
|
-
- mm_loader: ^3.0.0(目录监听与配置/脚本热更新)
|
|
635
|
-
- mm_mod: ^1.0.6
|
|
636
|
-
- mm_tpl: ^2.7.3
|
|
196
|
+
- 基础模块管理、配置加载、生命周期与热更新支持
|
|
637
197
|
|
|
638
198
|
## 许可证
|
|
639
199
|
|
|
@@ -641,4 +201,12 @@ ISC
|
|
|
641
201
|
|
|
642
202
|
## 作者信息
|
|
643
203
|
|
|
644
|
-
本模块由 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` |
|
package/lib/drive.js
CHANGED
|
@@ -1,40 +1,34 @@
|
|
|
1
1
|
const path = require('path');
|
|
2
2
|
const { getTpl } = require('mm_tpl');
|
|
3
|
+
const { string, push } = require('mm_helper');
|
|
3
4
|
const {
|
|
4
|
-
string,
|
|
5
5
|
fullname,
|
|
6
6
|
hasFile,
|
|
7
7
|
loadText,
|
|
8
8
|
saveText,
|
|
9
9
|
loadJson,
|
|
10
10
|
saveJson,
|
|
11
|
-
push,
|
|
12
11
|
addDir,
|
|
13
12
|
delFile,
|
|
14
13
|
delDir,
|
|
15
14
|
dirname,
|
|
16
15
|
basename
|
|
17
|
-
} = require('
|
|
16
|
+
} = require('mm_files');
|
|
18
17
|
const { Mod } = require('./mod');
|
|
19
18
|
|
|
20
|
-
const MODE = {
|
|
21
|
-
// 生产模式
|
|
22
|
-
PRODUCTION: 1,
|
|
23
|
-
// 热更新配置模式
|
|
24
|
-
HOT_CONFIG: 2,
|
|
25
|
-
// 热更新脚本模式
|
|
26
|
-
HOT_RELOAD: 3,
|
|
27
|
-
// 热更新配置+脚本模式
|
|
28
|
-
HOT_BOTH: 4,
|
|
29
|
-
// 始终重载模式
|
|
30
|
-
RELOAD_ALWAYS: 5
|
|
31
|
-
};
|
|
32
|
-
|
|
33
19
|
/**
|
|
34
20
|
* 驱动基础类
|
|
35
21
|
* @class
|
|
36
22
|
*/
|
|
37
23
|
class Drive extends Mod {
|
|
24
|
+
static MODE = {
|
|
25
|
+
PRODUCTION: 1,
|
|
26
|
+
HOT_CONFIG: 2,
|
|
27
|
+
HOT_RELOAD: 3,
|
|
28
|
+
HOT_BOTH: 4,
|
|
29
|
+
RELOAD_ALWAYS: 5
|
|
30
|
+
};
|
|
31
|
+
|
|
38
32
|
// 配置项
|
|
39
33
|
static config = {
|
|
40
34
|
// 标题, 介绍作用
|
|
@@ -701,7 +695,8 @@ Drive.prototype._applyConfigUpdate = function (config) {
|
|
|
701
695
|
* @param {string} old_script 旧的脚本文件路径
|
|
702
696
|
*/
|
|
703
697
|
Drive.prototype._reloadIfNeeded = function (old_script) {
|
|
704
|
-
|
|
698
|
+
const mode = Drive.MODE;
|
|
699
|
+
if (this.mode === mode.HOT_RELOAD || this.mode === mode.HOT_BOTH) {
|
|
705
700
|
// 只在 main 发生变化时才重载脚本
|
|
706
701
|
if (!old_script || old_script !== this.script_file) {
|
|
707
702
|
this.reloadScript();
|
|
@@ -850,7 +845,4 @@ Drive.prototype.remove = function () {
|
|
|
850
845
|
/**
|
|
851
846
|
* @module 导出Drive类
|
|
852
847
|
*/
|
|
853
|
-
module.exports = {
|
|
854
|
-
Drive,
|
|
855
|
-
MODE
|
|
856
|
-
};
|
|
848
|
+
module.exports = { Drive, MODE: Drive.MODE };
|
package/lib/manager.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
const path = require('path');
|
|
2
2
|
const { Manager: Core } = require('mm_mod');
|
|
3
|
-
const {
|
|
3
|
+
const { string } = require('mm_helper');
|
|
4
|
+
const { hasDir, hasFile, fullname, basename, dirname } = require('mm_files');
|
|
4
5
|
const { loadAdmin } = require('mm_loader');
|
|
5
6
|
const { typeStore } = require('mm_scanner');
|
|
6
7
|
const { Mod, addMethods } = require('./mod.js');
|
|
@@ -136,7 +137,7 @@ class Manager extends Core {
|
|
|
136
137
|
* 构造函数
|
|
137
138
|
* @param {object} config 配置项
|
|
138
139
|
* @param {object} parent 父项对象
|
|
139
|
-
* @param {object} [mods]
|
|
140
|
+
* @param {object} [mods] 模块对象列表,经父类构造注入为受管实例表(保持外部引用)
|
|
140
141
|
*/
|
|
141
142
|
constructor(config, parent, mods) {
|
|
142
143
|
super(
|
|
@@ -144,7 +145,8 @@ class Manager extends Core {
|
|
|
144
145
|
...Manager.config,
|
|
145
146
|
...config
|
|
146
147
|
},
|
|
147
|
-
parent
|
|
148
|
+
parent,
|
|
149
|
+
mods
|
|
148
150
|
);
|
|
149
151
|
|
|
150
152
|
if (parent) {
|
|
@@ -156,10 +158,6 @@ class Manager extends Core {
|
|
|
156
158
|
this._loaded = false;
|
|
157
159
|
// 目录监听器,键为目录路径,值为该目录的配置加载器
|
|
158
160
|
this._dir_watchers = new Map();
|
|
159
|
-
// 外部传入实例表时,直接作为受管记录的实例表,保证外部引用同步
|
|
160
|
-
if (mods) {
|
|
161
|
-
this._getRecord().mods = mods;
|
|
162
|
-
}
|
|
163
161
|
// 监听事件
|
|
164
162
|
this._listen();
|
|
165
163
|
}
|
|
@@ -290,10 +288,9 @@ Manager.prototype.clearMods = async function () {
|
|
|
290
288
|
* @returns {object|null} 删除的模块对象
|
|
291
289
|
*/
|
|
292
290
|
Manager.prototype.delMod = function (name) {
|
|
293
|
-
let
|
|
294
|
-
let mod = record.mods[name];
|
|
291
|
+
let mod = this.mods[name];
|
|
295
292
|
if (mod) {
|
|
296
|
-
delete
|
|
293
|
+
delete this.mods[name];
|
|
297
294
|
let infos = this.configs;
|
|
298
295
|
let index = infos.findIndex((o) => o.name === name);
|
|
299
296
|
if (index >= 0) {
|
|
@@ -309,7 +306,7 @@ Manager.prototype.delMod = function (name) {
|
|
|
309
306
|
* @param {object} mod 模块对象
|
|
310
307
|
*/
|
|
311
308
|
Manager.prototype.setMod = function (name, mod) {
|
|
312
|
-
this.
|
|
309
|
+
this.mods[name] = mod;
|
|
313
310
|
};
|
|
314
311
|
|
|
315
312
|
/**
|
|
@@ -318,7 +315,7 @@ Manager.prototype.setMod = function (name, mod) {
|
|
|
318
315
|
* @returns {object} 模块对象
|
|
319
316
|
*/
|
|
320
317
|
Manager.prototype.getMod = function (name) {
|
|
321
|
-
return this.
|
|
318
|
+
return this.mods[name];
|
|
322
319
|
};
|
|
323
320
|
|
|
324
321
|
/**
|
|
@@ -326,7 +323,7 @@ Manager.prototype.getMod = function (name) {
|
|
|
326
323
|
* @returns {object[]} 模块对象数组
|
|
327
324
|
*/
|
|
328
325
|
Manager.prototype.getMods = function () {
|
|
329
|
-
return this.
|
|
326
|
+
return this.mods;
|
|
330
327
|
};
|
|
331
328
|
|
|
332
329
|
/**
|
|
@@ -819,7 +816,7 @@ Manager.prototype._getConfigByScript = function (file) {
|
|
|
819
816
|
* @returns {void}
|
|
820
817
|
*/
|
|
821
818
|
Manager.prototype.unwatch = function () {
|
|
822
|
-
for (
|
|
819
|
+
for (const entry of this._dir_watchers.values()) {
|
|
823
820
|
entry.loader.unwatch(entry.config_callback, entry.script_callback);
|
|
824
821
|
}
|
|
825
822
|
this._dir_watchers.clear();
|
|
@@ -1089,12 +1086,12 @@ Manager.prototype._ensureModLoaded = async function (mod, method) {
|
|
|
1089
1086
|
if (is_running) {
|
|
1090
1087
|
try {
|
|
1091
1088
|
await mod.do('load');
|
|
1092
|
-
} catch
|
|
1089
|
+
} catch {
|
|
1093
1090
|
throw new Error(`模块${name}加载失败,无法执行方法 ${method}`);
|
|
1094
1091
|
}
|
|
1095
1092
|
try {
|
|
1096
1093
|
await mod.do('init');
|
|
1097
|
-
} catch
|
|
1094
|
+
} catch {
|
|
1098
1095
|
throw new Error(`模块${name}初始化失败,无法执行方法 ${method}`);
|
|
1099
1096
|
}
|
|
1100
1097
|
// 记录受管模块已完成初始化
|
package/lib/mod.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
const { Mod: CoreMod } = require('mm_mod');
|
|
2
|
-
const { saveJson, loadJson } = require('
|
|
2
|
+
const { saveJson, loadJson } = require('mm_files');
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* 通用模块类
|
|
@@ -44,69 +44,12 @@ class Mod extends CoreMod {
|
|
|
44
44
|
}
|
|
45
45
|
}
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
};
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* 初始化
|
|
57
|
-
* @returns {Promise<Mod>} 当前实例
|
|
58
|
-
*/
|
|
59
|
-
Mod.prototype.init = async function () {
|
|
60
|
-
return await this._init();
|
|
61
|
-
};
|
|
62
|
-
|
|
63
|
-
/**
|
|
64
|
-
* 启动(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
|
|
65
|
-
* @returns {Promise<Mod>} 当前实例
|
|
66
|
-
*/
|
|
67
|
-
Mod.prototype._start = async function () {
|
|
68
|
-
return this;
|
|
69
|
-
};
|
|
70
|
-
|
|
71
|
-
/**
|
|
72
|
-
* 启动
|
|
73
|
-
* @returns {Promise<Mod>} 当前实例
|
|
74
|
-
*/
|
|
75
|
-
Mod.prototype.start = async function () {
|
|
76
|
-
return await this._start();
|
|
77
|
-
};
|
|
78
|
-
|
|
79
|
-
/**
|
|
80
|
-
* 停止(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
|
|
81
|
-
* @returns {Promise<Mod>} 当前实例
|
|
82
|
-
*/
|
|
83
|
-
Mod.prototype._stop = async function () {
|
|
84
|
-
return this;
|
|
85
|
-
};
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* 停止
|
|
89
|
-
* @returns {Promise<Mod>} 当前实例
|
|
90
|
-
*/
|
|
91
|
-
Mod.prototype.stop = async function () {
|
|
92
|
-
return await this._stop();
|
|
93
|
-
};
|
|
94
|
-
|
|
95
|
-
/**
|
|
96
|
-
* 销毁(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
|
|
97
|
-
* @returns {Promise<Mod>} 当前实例
|
|
98
|
-
*/
|
|
99
|
-
Mod.prototype._destroy = async function () {
|
|
100
|
-
return this;
|
|
101
|
-
};
|
|
102
|
-
|
|
103
|
-
/**
|
|
104
|
-
* 销毁
|
|
105
|
-
* @returns {Promise<Mod>} 当前实例
|
|
106
|
-
*/
|
|
107
|
-
Mod.prototype.destroy = async function () {
|
|
108
|
-
return await this._destroy();
|
|
109
|
-
};
|
|
47
|
+
// 生命周期入口保留为既有调用方的公开契约;实际编排由 do 流水线的 _xxxCore 钩子承担
|
|
48
|
+
for (const name of ['init', 'start', 'stop', 'destroy']) {
|
|
49
|
+
Mod.prototype[name] = async function () {
|
|
50
|
+
return this;
|
|
51
|
+
};
|
|
52
|
+
}
|
|
110
53
|
|
|
111
54
|
/**
|
|
112
55
|
* 包装错误,附加模块文件路径上下文,用于溯源
|
package/lib/script_protocol.js
CHANGED
|
@@ -7,59 +7,62 @@
|
|
|
7
7
|
* - Drive 系(Drive / App / Plugin / Cmd):script_file、reloadScript()
|
|
8
8
|
* - Mod 系脚本驱动(Api / Event / Service / Pendant):_getScriptFile()、
|
|
9
9
|
* load() 把脚本方法挂到实例 this.main 上
|
|
10
|
-
* 管理器判断「某个脚本属于哪个驱动」以及「如何让它生效」时走本模块,
|
|
11
10
|
* 新增一种驱动类型只需注册适配器,不必修改管理器或宿主。
|
|
12
11
|
*/
|
|
13
12
|
|
|
14
13
|
const path = require('path');
|
|
15
14
|
|
|
16
15
|
/**
|
|
17
|
-
*
|
|
18
|
-
* @
|
|
16
|
+
* 默认入口解析器
|
|
17
|
+
* @returns {Array<function(object): string>} 解析器列表
|
|
19
18
|
*/
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
return drive._getScriptFile() || '';
|
|
27
|
-
} catch {
|
|
28
|
-
return '';
|
|
29
|
-
}
|
|
30
|
-
},
|
|
31
|
-
// Pendant 等驱动 getDir() 返回空串,目录只保存在 config.dir;
|
|
32
|
-
// 直接用 getDir() 会把入口误解析到进程 cwd 下的同名文件
|
|
33
|
-
(drive) => {
|
|
34
|
-
const main = drive.config && drive.config.main;
|
|
35
|
-
if (!main) return '';
|
|
36
|
-
let dir = (drive.config && drive.config.dir) || '';
|
|
37
|
-
if (!dir && typeof drive.getDir === 'function') {
|
|
19
|
+
function defaultEntryResolvers() {
|
|
20
|
+
return [
|
|
21
|
+
(drive) => drive.file || '',
|
|
22
|
+
(drive) => drive.script_file || '',
|
|
23
|
+
(drive) => {
|
|
24
|
+
if (typeof drive._getScriptFile !== 'function') return '';
|
|
38
25
|
try {
|
|
39
|
-
|
|
26
|
+
return drive._getScriptFile() || '';
|
|
40
27
|
} catch {
|
|
41
28
|
return '';
|
|
42
29
|
}
|
|
30
|
+
},
|
|
31
|
+
// Pendant 等驱动 getDir() 返回空串,目录只保存在 config.dir;
|
|
32
|
+
// 直接用 getDir() 会把入口误解析到进程 cwd 下的同名文件
|
|
33
|
+
(drive) => {
|
|
34
|
+
const main = drive.config && drive.config.main;
|
|
35
|
+
if (!main) return '';
|
|
36
|
+
let dir = (drive.config && drive.config.dir) || '';
|
|
37
|
+
if (!dir && typeof drive.getDir === 'function') {
|
|
38
|
+
try {
|
|
39
|
+
dir = drive.getDir() || '';
|
|
40
|
+
} catch {
|
|
41
|
+
return '';
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
return dir ? path.resolve(dir, main) : '';
|
|
43
45
|
}
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
];
|
|
46
|
+
];
|
|
47
|
+
}
|
|
47
48
|
|
|
48
49
|
/**
|
|
49
|
-
*
|
|
50
|
-
* @
|
|
50
|
+
* 默认重载器
|
|
51
|
+
* @returns {Array<{test: function(object): boolean, run: function(object): *}>} 重载器列表
|
|
51
52
|
*/
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
53
|
+
function defaultReloaders() {
|
|
54
|
+
return [
|
|
55
|
+
{ test: (d) => typeof d.reloadScript === 'function', run: (d) => d.reloadScript() },
|
|
56
|
+
// 普通 Mod 的 load 是生命周期方法,额外要求 _setMainMethod 避免误触
|
|
57
|
+
{
|
|
58
|
+
test: (d) => typeof d._setMainMethod === 'function' && typeof d.load === 'function',
|
|
59
|
+
run: (d) => d.load()
|
|
60
|
+
}
|
|
61
|
+
];
|
|
62
|
+
}
|
|
60
63
|
|
|
61
|
-
const
|
|
62
|
-
const
|
|
64
|
+
const ENTRY_RESOLVERS = defaultEntryResolvers();
|
|
65
|
+
const RELOADERS = defaultReloaders();
|
|
63
66
|
|
|
64
67
|
/**
|
|
65
68
|
* 注册入口解析器(扩展点)
|
|
@@ -90,12 +93,12 @@ function registerReloader(test, run, first = false) {
|
|
|
90
93
|
}
|
|
91
94
|
|
|
92
95
|
/**
|
|
93
|
-
*
|
|
96
|
+
* 恢复默认适配器,原地替换以保持注册表引用稳定
|
|
94
97
|
* @returns {void}
|
|
95
98
|
*/
|
|
96
99
|
function resetAdapters() {
|
|
97
|
-
ENTRY_RESOLVERS.splice(0, ENTRY_RESOLVERS.length, ...
|
|
98
|
-
RELOADERS.splice(0, RELOADERS.length, ...
|
|
100
|
+
ENTRY_RESOLVERS.splice(0, ENTRY_RESOLVERS.length, ...defaultEntryResolvers());
|
|
101
|
+
RELOADERS.splice(0, RELOADERS.length, ...defaultReloaders());
|
|
99
102
|
}
|
|
100
103
|
|
|
101
104
|
/**
|
package/package.json
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
"description": "
|
|
2
|
+
"name": "mm_machine",
|
|
3
|
+
"version": "6.0.1",
|
|
4
|
+
"description": "Node.js 插件机制:目录扫描、生命周期编排、方法调用与热重载",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"scripts": {
|
|
7
7
|
"test": "jest --coverage",
|
|
8
|
-
"demo": "node example/index.js"
|
|
9
|
-
"dev": "nodemon ./test.js"
|
|
8
|
+
"demo": "node example/index.js"
|
|
10
9
|
},
|
|
11
10
|
"repository": {
|
|
12
11
|
"type": "git",
|
|
@@ -15,7 +14,6 @@
|
|
|
15
14
|
"keywords": [
|
|
16
15
|
"mm_mod",
|
|
17
16
|
"mm_infra",
|
|
18
|
-
"mm_runtime",
|
|
19
17
|
"plugin-system",
|
|
20
18
|
"module-management",
|
|
21
19
|
"hot-reload",
|
|
@@ -25,27 +23,27 @@
|
|
|
25
23
|
"framework",
|
|
26
24
|
"mechanism"
|
|
27
25
|
],
|
|
28
|
-
"layer": "
|
|
26
|
+
"layer": "shared",
|
|
29
27
|
"group": "runtime",
|
|
30
28
|
"author": "邱文武",
|
|
31
29
|
"license": "ISC",
|
|
32
30
|
"engines": {
|
|
33
|
-
"node": ">=
|
|
31
|
+
"node": ">=18"
|
|
34
32
|
},
|
|
35
33
|
"files": [
|
|
36
34
|
"index.js",
|
|
37
|
-
"lib
|
|
35
|
+
"lib",
|
|
38
36
|
"example",
|
|
39
|
-
"README.md"
|
|
37
|
+
"README.md",
|
|
38
|
+
"tool"
|
|
40
39
|
],
|
|
41
40
|
"dependencies": {
|
|
42
41
|
"@prettier/sync": "^0.6.1",
|
|
43
|
-
"
|
|
42
|
+
"mm_files": "^1.4.0",
|
|
44
43
|
"mm_helper": "^1.0.3",
|
|
45
44
|
"mm_loader": "^7.0.0",
|
|
46
45
|
"mm_mod": "^1.0.6",
|
|
47
46
|
"mm_scanner": "^5.0.0",
|
|
48
|
-
"mm_store": "^1.0.1",
|
|
49
47
|
"mm_tpl": "^2.7.3"
|
|
50
48
|
},
|
|
51
49
|
"devDependencies": {
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* machine —— 插件机制契约自省工具
|
|
4
|
+
* 方法清单直接从模块导出的类原型采集,避免文档与实现漂移。
|
|
5
|
+
*/
|
|
6
|
+
const machine = require('../../index.js');
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* 采集类原型上的公开方法
|
|
10
|
+
* @param {Function} Cls 类
|
|
11
|
+
* @returns {Array<string>} 方法名列表
|
|
12
|
+
*/
|
|
13
|
+
function _methods(Cls) {
|
|
14
|
+
if (typeof Cls !== 'function' || !Cls.prototype) return [];
|
|
15
|
+
return Object.getOwnPropertyNames(Cls.prototype).filter((k) => k !== 'constructor' && k[0] !== '_').sort();
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
async function main(params, ctx, options) {
|
|
19
|
+
void options;
|
|
20
|
+
const p = params || {};
|
|
21
|
+
const action = p.action || 'modes';
|
|
22
|
+
const done = (data) => { ctx.output = data; return data; };
|
|
23
|
+
|
|
24
|
+
try {
|
|
25
|
+
if (action === 'modes') {
|
|
26
|
+
return done({
|
|
27
|
+
code: 0,
|
|
28
|
+
msg: '成功',
|
|
29
|
+
modes: machine.MODE || {},
|
|
30
|
+
lifecycle: ['init', 'start', 'stop', 'destroy']
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
if (action === 'classes') {
|
|
35
|
+
const names = p.class ? [p.class] : ['Mod', 'Drive', 'Manager'];
|
|
36
|
+
const classes = {};
|
|
37
|
+
for (const name of names) {
|
|
38
|
+
const Cls = machine[name];
|
|
39
|
+
if (!Cls) throw new Error('未知类: ' + name);
|
|
40
|
+
classes[name] = _methods(Cls);
|
|
41
|
+
}
|
|
42
|
+
return done({ code: 0, msg: '成功', classes });
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
return done({ code: 10001, msg: '不支持的操作: ' + action });
|
|
46
|
+
} catch (error) {
|
|
47
|
+
return done({ code: 10000, msg: '执行失败:' + error.message, error: { name: error.name, message: error.message } });
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
module.exports = { main };
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "machine",
|
|
3
|
+
"title": "插件机制契约自省",
|
|
4
|
+
"description": "基于 mm_machine 的契约自省能力:列出模块状态枚举值、查看 Mod/Drive/Manager 三个核心类的方法清单与生命周期顺序。适用场景:写自定义受管模块前确认要实现哪些钩子、排查管理器实例该调哪个方法。",
|
|
5
|
+
"category": "内核运行时",
|
|
6
|
+
"group": "kernel",
|
|
7
|
+
"type": "function",
|
|
8
|
+
"main": "./index.js",
|
|
9
|
+
"params": {
|
|
10
|
+
"type": "object",
|
|
11
|
+
"properties": {
|
|
12
|
+
"action": {
|
|
13
|
+
"type": "string",
|
|
14
|
+
"description": "操作类型: modes(状态枚举)/classes(类方法清单)",
|
|
15
|
+
"enum": [
|
|
16
|
+
"modes",
|
|
17
|
+
"classes"
|
|
18
|
+
],
|
|
19
|
+
"default": "modes"
|
|
20
|
+
},
|
|
21
|
+
"class": {
|
|
22
|
+
"type": "string",
|
|
23
|
+
"description": "类名(classes 可选): Mod/Drive/Manager,缺省全部"
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
"required": [
|
|
27
|
+
"action"
|
|
28
|
+
]
|
|
29
|
+
},
|
|
30
|
+
"returns": {
|
|
31
|
+
"type": "object",
|
|
32
|
+
"properties": {
|
|
33
|
+
"code": {
|
|
34
|
+
"type": "number",
|
|
35
|
+
"description": "0 表示成功,1xxxx 表示业务/执行异常"
|
|
36
|
+
},
|
|
37
|
+
"msg": {
|
|
38
|
+
"type": "string",
|
|
39
|
+
"description": "结果描述"
|
|
40
|
+
},
|
|
41
|
+
"modes": {
|
|
42
|
+
"type": "object",
|
|
43
|
+
"description": "状态枚举(MODE)"
|
|
44
|
+
},
|
|
45
|
+
"classes": {
|
|
46
|
+
"type": "object",
|
|
47
|
+
"description": "类名 → 方法清单"
|
|
48
|
+
},
|
|
49
|
+
"lifecycle": {
|
|
50
|
+
"type": "array",
|
|
51
|
+
"description": "生命周期方法顺序"
|
|
52
|
+
},
|
|
53
|
+
"error": {
|
|
54
|
+
"type": "object",
|
|
55
|
+
"description": "异常对象 { name, message }"
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
"handler": "manager"
|
|
60
|
+
}
|