mm_machine 3.5.4 → 3.5.5

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/lib/mod.js CHANGED
@@ -1,35 +1,37 @@
1
- const { Base } = require('mm_expand');
2
- require('./auto_require.js');
1
+ const { Mod: CoreMod } = require('mm_mod');
2
+ const { saveJson, loadJson } = require('mm_helper');
3
3
 
4
4
  /**
5
- * 增强JSON加载函数,专门用于配置文件(.json)热重载
6
- * 当配置文件内容发生变化时,自动重新加载并触发回调
7
- * @param {string} file 配置文件路径(.json)
8
- * @param {Function} func 热更新回调函数,文件变化时触发
9
- * @returns {object} 解析的JSON对象
10
- * @throws {TypeError} 文件路径不是字符串或回调不是函数时抛出
5
+ * 构造模块时使用的占位名称
6
+ * @description mm_mod.Mod 要求配置必须包含名称,模块在未指定名称时先用占位名称通过校验,再还原为空名称
7
+ * @type {string}
11
8
  */
12
- $.loadJson = function (file, func) {
13
- // 参数校验
14
- if (typeof file !== 'string') {
15
- throw new TypeError('第一个参数(file)必须是字符串');
16
- }
9
+ const MOD_DEFAULT_NAME = '__mm_machine_mod__';
17
10
 
18
- if (func && typeof func !== 'function') {
19
- throw new TypeError('第二个参数(func)必须是函数');
20
- }
11
+ /**
12
+ * 模块运行状态在状态存储器中的键名
13
+ * @type {string}
14
+ */
15
+ const MOD_STATE_KEY = 'mod';
21
16
 
22
- // 确保文件是.json文件
23
- if (!file.endsWith('.json')) {
24
- throw new TypeError('$.loadJson 只能用于.json配置文件');
25
- }
26
- return $.mod.load(file, func);
27
- };
17
+ /**
18
+ * 模块运行状态的默认值
19
+ * @type {{state: string, loaded: boolean, inited: boolean}}
20
+ */
21
+ const MOD_STATE_DEFAULT = { state: 'created', loaded: false, inited: false };
22
+
23
+ /**
24
+ * 各实例的待写入状态队列,保证同一模块的状态写入按调用顺序串行落库
25
+ * @type {WeakMap<Object, Promise>}
26
+ */
27
+ const MOD_STATE_WRITING = new WeakMap();
28
28
 
29
29
  /**
30
30
  * 通用模块类
31
+ * @description 在 mm_mod.Mod 的生命周期、配置与日志能力之上,提供插件式调度(do 流水线)、
32
+ * 脚本方法/数据挂载、加载与卸载、缓存数据持久化等能力
31
33
  */
32
- class Mod extends Base {
34
+ class Mod extends CoreMod {
33
35
  /**
34
36
  * 配置项
35
37
  */
@@ -48,16 +50,20 @@ class Mod extends Base {
48
50
  cache_file: ''
49
51
  };
50
52
 
51
- _is_loaded = false;
52
- _is_inited = false;
53
-
54
53
  /**
55
54
  * 构造函数
56
55
  * @param {object} config 配置对象
57
56
  * @param {object} parent 父模块
58
57
  */
59
- constructor(config, parent) {
60
- super(config, parent);
58
+ constructor(config = {}, parent) {
59
+ const cfg = { ...config };
60
+ if (!cfg.name) {
61
+ cfg.name = MOD_DEFAULT_NAME;
62
+ }
63
+ super(cfg, parent);
64
+ if (!config.name) {
65
+ this.config.name = '';
66
+ }
61
67
  if (parent) {
62
68
  this.getParent = function () {
63
69
  return parent;
@@ -67,46 +73,214 @@ class Mod extends Base {
67
73
  this._methods = {};
68
74
  // 脚本数据
69
75
  this._datas = {};
76
+ // 监听事件
77
+ this._listen();
70
78
  }
71
79
 
72
80
  /**
73
81
  * 是否已加载
74
- * @param {boolean} bl 是否已加载
75
- * @returns {boolean} 是否已加载
82
+ * @param {boolean} bl 是否已加载,缺省时读取当前值
83
+ * @returns {Promise<boolean>} 是否已加载
76
84
  */
77
- isLoaded(bl) {
85
+ async isLoaded(bl) {
78
86
  if (bl === undefined) {
79
- return this._is_loaded;
80
- }
81
- this._is_loaded = bl;
82
- if (!bl) {
83
- this._is_inited = false;
87
+ return (await this._readModState()).loaded;
84
88
  }
89
+ await this._writeModState(bl ? { loaded: true } : { loaded: false, inited: false });
85
90
  return bl;
86
91
  }
87
92
 
88
93
  /**
89
94
  * 是否已初始化
90
- * @param {boolean} bl 是否已初始化
91
- * @returns {boolean} 是否已初始化
95
+ * @param {boolean} bl 是否已初始化,缺省时读取当前值
96
+ * @returns {Promise<boolean>} 是否已初始化
92
97
  */
93
- isInited(bl) {
98
+ async isInited(bl) {
94
99
  if (bl === undefined) {
95
- return this._is_inited;
100
+ return (await this._readModState()).inited;
96
101
  }
97
- this._is_inited = bl;
102
+ await this._writeModState({ inited: bl });
98
103
  return bl;
99
104
  }
100
105
  }
101
106
 
102
107
  /**
103
- * 日志输出
104
- * @param {string} level 日志级别
105
- * @param {string} message 日志消息
106
- * @param {...any} params 日志参数
108
+ * 获取运行状态存储器
109
+ * @description mm_state_store 经 mm_cache 反向依赖 mm_mod,只能延迟引用以避开循环依赖
110
+ * @returns {Object} 状态存储器
111
+ * @private
107
112
  */
108
- Mod.prototype.log = function (level, message, ...params) {
109
- this.getLogger()[level](`[${this.constructor.name}.${this.config.name}] ${message}`, ...params);
113
+ Mod.prototype._getModStateStore = function () {
114
+ const { stateAdmin } = require('mm_state_store');
115
+ return stateAdmin(this._label());
116
+ };
117
+
118
+ /**
119
+ * 读取运行状态
120
+ * @returns {Promise<{state: string, loaded: boolean, inited: boolean}>} 运行状态副本
121
+ * @private
122
+ */
123
+ Mod.prototype._readModState = async function () {
124
+ const record = await this._getModStateStore().get(MOD_STATE_KEY);
125
+ return { ...MOD_STATE_DEFAULT, ...(record || {}) };
126
+ };
127
+
128
+ /**
129
+ * 合并并写入运行状态
130
+ * @param {object} patch 需要更新的状态字段
131
+ * @returns {Promise<boolean>} 是否写入成功
132
+ * @private
133
+ */
134
+ Mod.prototype._mergeModState = async function (patch) {
135
+ const state = await this._readModState();
136
+ return await this._getModStateStore().set(MOD_STATE_KEY, { ...state, ...patch });
137
+ };
138
+
139
+ /**
140
+ * 按补丁写入运行状态
141
+ * @description 同一实例的写入串行执行,避免同步调用场景下后写被先写覆盖
142
+ * @param {object} patch 需要更新的状态字段
143
+ * @returns {Promise<boolean>} 是否写入成功
144
+ * @private
145
+ */
146
+ Mod.prototype._writeModState = async function (patch) {
147
+ const prev = MOD_STATE_WRITING.get(this) || Promise.resolve();
148
+ const next = prev.then(() => this._mergeModState(patch));
149
+ MOD_STATE_WRITING.set(
150
+ this,
151
+ next.catch(() => { })
152
+ );
153
+ try {
154
+ return await next;
155
+ } catch (err) {
156
+ this.log('error', '写入运行状态失败', err);
157
+ return false;
158
+ }
159
+ };
160
+
161
+ /**
162
+ * 获取当前状态
163
+ * @returns {Promise<string>} 当前状态
164
+ */
165
+ Mod.prototype.getState = async function () {
166
+ return (await this._readModState()).state;
167
+ };
168
+
169
+ /**
170
+ * 设置当前状态
171
+ * @param {string} state 状态值
172
+ * @returns {Promise<Mod>} 当前实例
173
+ */
174
+ Mod.prototype.setState = async function (state) {
175
+ await this._writeModState({ state });
176
+ return this;
177
+ };
178
+
179
+ /**
180
+ * 设置当前状态(兼容 mm_mod 的内部命名)
181
+ * @param {string} state 状态值
182
+ * @returns {Promise<Mod>} 当前实例
183
+ */
184
+ Mod.prototype._setState = async function (state) {
185
+ return await this.setState(state);
186
+ };
187
+
188
+ /**
189
+ * 是否处于指定状态
190
+ * @param {string} state 目标状态
191
+ * @returns {Promise<boolean>} 是否处于该状态
192
+ */
193
+ Mod.prototype.isState = async function (state) {
194
+ return (await this.getState()) === state;
195
+ };
196
+
197
+ /**
198
+ * 是否运行中
199
+ * @returns {Promise<boolean>} 是否运行中
200
+ */
201
+ Mod.prototype.isRunning = async function () {
202
+ return await this.isState('started');
203
+ };
204
+
205
+ /**
206
+ * 状态断言
207
+ * @param {string} expected 预期状态
208
+ * @param {string} action 操作名称
209
+ * @returns {Promise<Mod>} 当前实例
210
+ * @throws {Error} 当前状态与预期不符时
211
+ */
212
+ Mod.prototype._assertState = async function (expected, action) {
213
+ const state = await this.getState();
214
+ if (state !== expected) {
215
+ throw new Error(
216
+ `${this._label()} cannot ${action} in state "${state}", expected "${expected}"`
217
+ );
218
+ }
219
+ return this;
220
+ };
221
+
222
+ /**
223
+ * 初始化(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
224
+ * @returns {Promise<Mod>} 当前实例
225
+ */
226
+ Mod.prototype._init = async function () {
227
+ return this;
228
+ };
229
+
230
+ /**
231
+ * 初始化
232
+ * @returns {Promise<Mod>} 当前实例
233
+ */
234
+ Mod.prototype.init = async function () {
235
+ return await this._init();
236
+ };
237
+
238
+ /**
239
+ * 启动(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
240
+ * @returns {Promise<Mod>} 当前实例
241
+ */
242
+ Mod.prototype._start = async function () {
243
+ return this;
244
+ };
245
+
246
+ /**
247
+ * 启动
248
+ * @returns {Promise<Mod>} 当前实例
249
+ */
250
+ Mod.prototype.start = async function () {
251
+ return await this._start();
252
+ };
253
+
254
+ /**
255
+ * 停止(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
256
+ * @returns {Promise<Mod>} 当前实例
257
+ */
258
+ Mod.prototype._stop = async function () {
259
+ return this;
260
+ };
261
+
262
+ /**
263
+ * 停止
264
+ * @returns {Promise<Mod>} 当前实例
265
+ */
266
+ Mod.prototype.stop = async function () {
267
+ return await this._stop();
268
+ };
269
+
270
+ /**
271
+ * 销毁(兼容 mm_expand 行为,生命周期由 do 流水线驱动)
272
+ * @returns {Promise<Mod>} 当前实例
273
+ */
274
+ Mod.prototype._destroy = async function () {
275
+ return this;
276
+ };
277
+
278
+ /**
279
+ * 销毁
280
+ * @returns {Promise<Mod>} 当前实例
281
+ */
282
+ Mod.prototype.destroy = async function () {
283
+ return await this._destroy();
110
284
  };
111
285
 
112
286
  /**
@@ -162,76 +336,73 @@ Mod.prototype._listen = function () {
162
336
 
163
337
  /**
164
338
  * 监听加载事件
165
- * @param {object} ctx 上下文对象
166
339
  */
167
- Mod.prototype._onLoad = async function (ctx) {
340
+ Mod.prototype._onLoad = function () {
168
341
  // 1. 加载
169
342
  this.on('load:before', async (ctx) => {
170
- this.setState('loading');
343
+ await this.setState('loading');
171
344
  await this._loadCore(...ctx.params);
172
345
  });
173
- this.on('load:after', (ctx) => {
174
- this.setState('loaded');
175
- this.isLoaded(true);
346
+ this.on('load:after', async () => {
347
+ await this.setState('loaded');
348
+ await this.isLoaded(true);
176
349
  });
177
350
  };
178
351
 
179
352
  /**
180
353
  * 监听初始化事件
181
354
  */
182
- Base.prototype._onInit = function () {
355
+ Mod.prototype._onInit = function () {
183
356
  // 初始化
184
357
  this.on('init:before', async (ctx) => {
185
- this.setState('initing');
358
+ await this.setState('initing');
186
359
  await this._initCore(...ctx.params);
187
360
  });
188
- this.on('init:success', (ctx) => {
189
- this.isInited(true);
361
+ this.on('init:success', async () => {
362
+ await this.isInited(true);
190
363
  });
191
- this.on('init:after', (ctx) => {
192
- this.setState('inited');
364
+ this.on('init:after', async () => {
365
+ await this.setState('inited');
193
366
  });
194
367
  };
195
368
 
196
369
  /**
197
370
  * 监听启动事件
198
- * @param {object} ctx 上下文对象
199
371
  */
200
- Mod.prototype._onStart = async function (ctx) {
372
+ Mod.prototype._onStart = function () {
201
373
  let status_last = 'inited';
202
374
  // 3. 启动
203
375
  this.on('start:before', async (ctx) => {
204
- status_last = this.getState();
205
- this.setState('starting');
376
+ status_last = await this.getState();
377
+ await this.setState('starting');
206
378
  await this._startCore(...ctx.params);
207
379
  });
208
- this.on('start:success', (ctx) => {
209
- this.setState('running');
380
+ this.on('start:success', async () => {
381
+ await this.setState('started');
210
382
  });
211
- this.on('start:error', (ctx) => {
212
- this.setState(status_last);
383
+ this.on('start:error', async () => {
384
+ await this.setState(status_last);
213
385
  });
214
386
  };
215
387
 
216
388
  /**
217
389
  * 监听停止事件
218
- * @param {object} ctx 上下文对象
219
390
  */
220
- Mod.prototype._onStop = async function (ctx) {
221
- let status_last = 'running';
391
+ Mod.prototype._onStop = function () {
392
+ let status_last = 'started';
222
393
  // 4. 停止
223
- this.on('stop:before', async (ctx) => {
224
- status_last = this.getState();
225
- this.setState('stopping');
394
+ this.on('stop:before', async () => {
395
+ status_last = await this.getState();
396
+ await this.setState('stopping');
226
397
  });
227
398
  this.on('stop:after', async (ctx) => {
228
399
  await this._stopCore(...ctx.params);
229
400
  });
230
- this.on('stop:success', async (ctx) => {
231
- this.setState('stopped');
401
+ this.on('stop:success', async () => {
402
+ await this.setState('stopped');
232
403
  });
233
- this.on('stop:error', (ctx) => {
234
- this.setState(status_last);
404
+ this.on('stop:error', async () => {
405
+ await this.setState(status_last);
235
406
  });
236
407
  };
237
408
 
@@ -241,131 +412,98 @@ Mod.prototype._onStop = async function (ctx) {
241
412
  Mod.prototype._onDestroy = function () {
242
413
  let status_last = 'stopped';
243
414
  // 销毁
244
- this.on('destroy:before', async (ctx) => {
245
- status_last = this.getState();
246
- this.setState('destroying');
415
+ this.on('destroy:before', async () => {
416
+ status_last = await this.getState();
417
+ await this.setState('destroying');
247
418
  });
248
- this.on('destroy:check', (ctx) => {
419
+ this.on('destroy:check', async (ctx) => {
249
420
  if (status_last !== 'unloaded') {
250
- this.setState(status_last);
421
+ await this.setState(status_last);
251
422
  ctx.error = new Error('销毁前必须先卸载');
252
423
  }
253
424
  });
254
425
  this.on('destroy:after', async (ctx) => {
255
426
  await this._destroyCore(...ctx.params);
256
427
  });
257
- this.on('destroy:success', (ctx) => {
258
- this.setState('destroyed');
428
+ this.on('destroy:success', async () => {
429
+ await this.setState('disposed');
259
430
  });
260
- this.on('destroy:error', (ctx) => {
261
- this.setState(status_last);
431
+ this.on('destroy:error', async () => {
432
+ await this.setState(status_last);
262
433
  });
263
434
  };
264
435
 
265
436
  /**
266
437
  * 监听卸载事件
267
- * @param {object} ctx 上下文对象
268
438
  */
269
- Mod.prototype._onUnload = async function (ctx) {
439
+ Mod.prototype._onUnload = function () {
270
440
  let status_last = 'stopped';
271
441
  // 5. 卸载
272
- this.on('unload:before', (ctx) => {
273
- status_last = this.getState();
274
- this.setState('unloading');
442
+ this.on('unload:before', async (ctx) => {
443
+ status_last = await this.getState();
444
+ await this.setState('unloading');
275
445
  });
276
- this.on('unload:check', (ctx) => {
446
+ this.on('unload:check', async (ctx) => {
277
447
  if (status_last !== 'stopped') {
278
- status_last = this.getState();
448
+ status_last = await this.getState();
279
449
  ctx.error = new Error('卸载前必须先停止');
280
450
  }
281
451
  });
282
452
  this.on('unload:after', async (ctx) => {
283
- this.setState('unloaded');
453
+ await this.setState('unloaded');
284
454
  await this._unloadCore(...ctx.params);
285
- this.isLoaded(false);
455
+ await this.isLoaded(false);
286
456
  });
287
457
  };
288
458
 
289
459
  /**
290
460
  * 加载 - 内部方法
291
- * @param {...any} args 加载参数
292
- * @returns {object} 模块对象
461
+ * @returns {Promise<Mod>} 模块对象
293
462
  * @private
294
463
  */
295
- Mod.prototype._load = async function (...args) {
464
+ Mod.prototype._load = async function () {
296
465
  return this;
297
466
  };
298
467
 
299
468
  /**
300
469
  * 加载
301
- * @param {...any} args 加载参数
302
- * @returns {object} 模块对象
470
+ * @returns {Promise<Mod>} 模块对象
303
471
  */
304
- Mod.prototype.load = async function (...args) {
305
- return await this._load(...args);
472
+ Mod.prototype.load = async function () {
473
+ return await this._load();
306
474
  };
307
475
 
308
476
  /**
309
477
  * 加载核心
478
+ * @returns {Promise<void>} 无返回值
310
479
  * @private
311
- * @param {...any} args 加载参数
312
- */
313
- Mod.prototype._loadCore = async function (...args) {
314
-
315
- };
316
-
317
- /**
318
- * 启动 - 内部方法
319
- * @private
320
- * @param {...any} args 初始化参数
321
- * @returns {object} 模块对象
322
- */
323
- Mod.prototype._start = async function (...args) {
324
- return this;
325
- };
326
-
327
- /**
328
- * 启动
329
- * @param {...any} args 初始化参数
330
- * @returns {object} 模块对象
331
480
  */
332
- Mod.prototype.start = async function (...args) {
333
- return await this._start(...args);
334
- };
481
+ Mod.prototype._loadCore = async function () { };
335
482
 
336
483
  /**
337
484
  * 启动核心
485
+ * @returns {Promise<void>} 无返回值
338
486
  * @private
339
- * @param {...any} args 初始化参数
340
487
  */
341
- Mod.prototype._startCore = async function (...args) { };
488
+ Mod.prototype._startCore = async function () { };
342
489
 
343
490
  /**
344
- * 停止 - 内部方法
491
+ * 停止核心
492
+ * @returns {Promise<void>} 无返回值
345
493
  * @private
346
- * @returns {object} 模块对象
347
494
  */
348
- Mod.prototype._stop = async function () {
349
- return this;
350
- };
351
-
352
- /**
353
- * 停止
354
- * @returns {object} 模块对象
355
- */
356
- Mod.prototype.stop = async function () {
357
- return await this._stop();
358
- };
495
+ Mod.prototype._stopCore = async function () { };
359
496
 
360
497
  /**
361
- * 停止核心
498
+ * 初始化核心
499
+ * @returns {Promise<void>} 无返回值
362
500
  * @private
363
501
  */
364
- Mod.prototype._stopCore = async function () { };
502
+ Mod.prototype._initCore = async function () { };
365
503
 
366
504
  /**
367
505
  * 销毁核心
368
- * @returns {object} 返回当前对象
506
+ * @returns {Promise<void>} 无返回值
369
507
  */
370
508
  Mod.prototype._destroyCore = async function () {
371
509
  if (this.config.need_cache) {
@@ -377,8 +515,8 @@ Mod.prototype._destroyCore = async function () {
377
515
 
378
516
  /**
379
517
  * 卸载 - 内部方法
518
+ * @returns {Promise<Mod>} 模块对象
380
519
  * @private
381
- * @returns {object} 模块对象
382
520
  */
383
521
  Mod.prototype._unload = async function () {
384
522
  return this;
@@ -386,7 +524,7 @@ Mod.prototype._unload = async function () {
386
524
 
387
525
  /**
388
526
  * 卸载
389
- * @returns {object} 模块对象
527
+ * @returns {Promise<Mod>} 模块对象
390
528
  */
391
529
  Mod.prototype.unload = async function () {
392
530
  return await this._unload();
@@ -394,6 +532,7 @@ Mod.prototype.unload = async function () {
394
532
 
395
533
  /**
396
534
  * 卸载核心
535
+ * @returns {Promise<void>} 无返回值
397
536
  */
398
537
  Mod.prototype._unloadCore = async function () {
399
538
  if (this._methods) {
@@ -412,11 +551,12 @@ Mod.prototype._unloadCore = async function () {
412
551
 
413
552
  /**
414
553
  * 重载
554
+ * @returns {Promise<void>} 无返回值
415
555
  */
416
556
  Mod.prototype.reload = async function () {
417
557
  try {
418
- this._unloadCore();
419
- this.isLoaded(false);
558
+ await this._unloadCore();
559
+ await this.isLoaded(false);
420
560
  } catch (err) {
421
561
  this.log('error', '重载失败', err);
422
562
  }
@@ -424,6 +564,7 @@ Mod.prototype.reload = async function () {
424
564
 
425
565
  /**
426
566
  * 重启
567
+ * @returns {Promise<void>} 无返回值
427
568
  */
428
569
  Mod.prototype.restart = async function () {
429
570
  try {
@@ -434,16 +575,9 @@ Mod.prototype.restart = async function () {
434
575
  }
435
576
  };
436
577
 
437
- /**
438
- * 是否运行中
439
- * @returns {boolean} 是否运行中
440
- */
441
- Mod.prototype.isRunning = function () {
442
- return this.getState() === 'running';
443
- };
444
-
445
578
  /**
446
579
  * 结束
580
+ * @returns {Promise<void>} 无返回值
447
581
  */
448
582
  Mod.prototype.end = async function () {
449
583
  try {
@@ -455,12 +589,263 @@ Mod.prototype.end = async function () {
455
589
  }
456
590
  };
457
591
 
592
+ /**
593
+ * 事件驱动
594
+ * @param {string} method 方法名称
595
+ * @param {...any} params 参数列表
596
+ * @returns {Promise<any>} 执行结果
597
+ */
598
+ Mod.prototype.do = async function (method, ...params) {
599
+ let ctx = await this._do(method, ...params);
600
+ return ctx.result;
601
+ };
602
+
603
+ /**
604
+ * 事件驱动 - 内部方法
605
+ * @param {string} method 方法名称
606
+ * @param {...any} params 参数列表
607
+ * @returns {Promise<object>} 执行上下文对象
608
+ */
609
+ Mod.prototype._do = async function (method, ...params) {
610
+ // 入参校验
611
+ if (!method || typeof method !== 'string') {
612
+ throw new TypeError('方法名必须是非空字符串');
613
+ }
614
+
615
+ if (!this[method]) {
616
+ throw new Error(`方法${method}不存在`);
617
+ }
618
+
619
+ let ctx = {
620
+ method,
621
+ params,
622
+ result: undefined,
623
+ error: undefined,
624
+ cancelled: false
625
+ };
626
+
627
+ try {
628
+ await this._doBeforeProcess(method, ctx);
629
+ if (ctx.cancelled) {
630
+ return ctx;
631
+ }
632
+
633
+ await this._doExecuteMethod(method, ctx);
634
+ } catch (error) {
635
+ ctx.error = error;
636
+ }
637
+ if (ctx.error) {
638
+ // 执行错误处理
639
+ await this._doErrorProcess(method, ctx);
640
+ } else {
641
+ // 如果执行成功,进行成功处理
642
+ await this._doSuccessProcess(method, ctx);
643
+ }
644
+ // 无论成功失败,都要执行后处理
645
+ await this._doAfterProcess(method, ctx);
646
+ return ctx;
647
+ };
648
+
649
+ /**
650
+ * 前处理阶段
651
+ * @param {string} method 方法名称
652
+ * @param {object} ctx 上下文对象
653
+ * @returns {Promise<void>} 无返回值
654
+ * @private
655
+ */
656
+ Mod.prototype._doBeforeProcess = async function (method, ctx) {
657
+ await this.emitWait(method + ':before', ctx);
658
+ };
659
+
660
+ /**
661
+ * 执行方法
662
+ * @param {string} method 方法名称
663
+ * @param {object} ctx 上下文对象
664
+ * @returns {Promise<void>} 无返回值
665
+ * @private
666
+ */
667
+ Mod.prototype._doExecuteMethod = async function (method, ctx) {
668
+ await this._doCheckPhase(method, ctx);
669
+ if (ctx.error) return;
670
+
671
+ await this._doMainMethod(method, ctx);
672
+ if (ctx.error) return;
673
+
674
+ await this._doRenderPhase(method, ctx);
675
+ };
676
+
677
+ /**
678
+ * 检查阶段
679
+ * @param {string} method 方法名称
680
+ * @param {object} ctx 上下文对象
681
+ * @returns {Promise<void>} 无返回值
682
+ */
683
+ Mod.prototype._doCheckPhase = async function (method, ctx) {
684
+ let ret = await this.emitRace(method + ':check', ctx);
685
+
686
+ if (ret) {
687
+ if (ret.status === 'rejected') {
688
+ ctx.error = ret.error;
689
+ } else if (ret.status === 'fulfilled' && ret.result) {
690
+ ctx.result = ret.result;
691
+ }
692
+ }
693
+ };
694
+
695
+ /**
696
+ * 主方法执行
697
+ * @param {string} method 方法名称
698
+ * @param {object} ctx 上下文对象
699
+ * @returns {Promise<void>} 无返回值
700
+ * @private
701
+ */
702
+ Mod.prototype._doMainMethod = async function (method, ctx) {
703
+ if (!ctx.result) {
704
+ // 触发执行中事件
705
+ let result = await this.emitWait(`${method}:main`, ctx);
706
+ if (result) {
707
+ ctx.result = result;
708
+ }
709
+
710
+ if (!ctx.result) {
711
+ // 调用子类实现的逻辑
712
+ ctx.result = await this[method](...ctx.params);
713
+ }
714
+ }
715
+ };
716
+
717
+ /**
718
+ * 渲染阶段
719
+ * @param {string} method 方法名称
720
+ * @param {object} ctx 上下文对象
721
+ * @returns {Promise<void>} 无返回值
722
+ * @private
723
+ */
724
+ Mod.prototype._doRenderPhase = async function (method, ctx) {
725
+ if (ctx.result && !ctx.error) {
726
+ let result = await this.emitWate(method + ':render', ctx.result, ctx);
727
+ if (result) {
728
+ ctx.result = result;
729
+ }
730
+ }
731
+ };
732
+
733
+ /**
734
+ * 成功处理阶段
735
+ * @param {string} method 方法名称
736
+ * @param {object} ctx 上下文对象
737
+ * @returns {Promise<void>} 无返回值
738
+ * @private
739
+ */
740
+ Mod.prototype._doSuccessProcess = async function (method, ctx) {
741
+ await this.emitWait(method + ':success', ctx);
742
+ };
743
+
744
+ /**
745
+ * 后处理阶段
746
+ * @param {string} method 方法名称
747
+ * @param {object} ctx 上下文对象
748
+ * @returns {Promise<void>} 无返回值
749
+ * @private
750
+ */
751
+ Mod.prototype._doAfterProcess = async function (method, ctx) {
752
+ // 顺序执行并等待,确保状态变更在本次调度结束前落库
753
+ await this.emitWait(method + ':after', ctx);
754
+ };
755
+
756
+ /**
757
+ * 错误处理
758
+ * @param {string} method 方法名称
759
+ * @param {object} ctx 上下文对象
760
+ * @returns {Promise<void>} 无返回值
761
+ */
762
+ Mod.prototype._doErrorProcess = async function (method, ctx) {
763
+ if (ctx.error) {
764
+ // 顺序执行并等待,确保错误分支中的状态还原在本次调度结束前落库
765
+ await this.emitWait(method + ':error', ctx);
766
+ this.log('error', `执行方法${method}出错:`, ctx.error);
767
+ }
768
+ };
769
+
770
+ /**
771
+ * 快速执行方法
772
+ * @param {string} method 方法名称
773
+ * @param {...any} params 参数列表
774
+ * @returns {Promise<any>} 执行结果
775
+ */
776
+ Mod.prototype.doEasy = async function (method, ...params) {
777
+ // 快速检查方法是否存在
778
+ if (!this[method]) {
779
+ throw new Error(`方法${method}不存在`);
780
+ }
781
+
782
+ try {
783
+ // 直接执行主方法,跳过所有事件处理
784
+ return await this[method](...params);
785
+ } catch (error) {
786
+ // 简单错误处理
787
+ this.log('error', `快速执行方法${method}出错:`, error);
788
+ }
789
+ };
790
+
791
+ /**
792
+ * 智能执行方法(自动选择 do 或 doEasy)
793
+ * @param {string} method 方法名称
794
+ * @param {...any} params 参数列表
795
+ * @returns {Promise<any>} 执行结果
796
+ */
797
+ Mod.prototype.doSmart = async function (method, ...params) {
798
+ // 提取选项参数
799
+ let options = {};
800
+ if (params.length > 0 && typeof params[params.length - 1] === 'object') {
801
+ options = params.pop();
802
+ }
803
+
804
+ // 检查是否有监听器
805
+ let has_list = this._hasEventListeners(method);
806
+
807
+ // 根据选项和监听器情况选择执行方式
808
+ if (options.fast || !has_list) {
809
+ // 快速执行:无监听器或明确要求快速
810
+ return await this.doEasy(method, ...params);
811
+ } else {
812
+ // 完整事件驱动执行
813
+ return await this.do(method, ...params);
814
+ }
815
+ };
816
+
817
+ /**
818
+ * 检查方法是否有事件监听器
819
+ * @param {string} method 方法名称
820
+ * @returns {boolean} 是否有监听器
821
+ * @private
822
+ */
823
+ Mod.prototype._hasEventListeners = function (method) {
824
+ return (
825
+ this.listenerCount(method + ':before') > 0 ||
826
+ this.listenerCount(method + ':check') > 0 ||
827
+ this.listenerCount(method + ':render') > 0 ||
828
+ this.listenerCount(method + ':success') > 0 ||
829
+ this.listenerCount(method + ':error') > 0 ||
830
+ this.listenerCount(method + ':after') > 0
831
+ );
832
+ };
833
+
834
+ /**
835
+ * 执行入口
836
+ * @param {...any} params 参数列表
837
+ * @returns {Promise<any>} 执行结果
838
+ */
839
+ Mod.prototype.run = async function (...params) {
840
+ return await this.do('main', ...params);
841
+ };
842
+
458
843
  /**
459
844
  * 获取事件管理器
460
845
  * @returns {object} 事件管理器
461
846
  */
462
847
  Mod.prototype.getEventer = function () {
463
- return this._eventer || $.eventer;
848
+ return this._eventer || this;
464
849
  };
465
850
 
466
851
  /**
@@ -471,6 +856,127 @@ Mod.prototype.setEventer = function (eventer) {
471
856
  this._eventer = eventer;
472
857
  };
473
858
 
859
+ /**
860
+ * 触发事件 - 顺序执行并等待完成
861
+ * @param {string} event 事件名
862
+ * @param {...any} args 事件参数
863
+ * @returns {Promise<void>} 无返回值
864
+ */
865
+ Mod.prototype.emitWait = async function (event, ...args) {
866
+ let listeners = this.listeners(event);
867
+ for (let listener of listeners) {
868
+ try {
869
+ await listener(...args);
870
+ } catch (error) {
871
+ this._handleError(error, event);
872
+ }
873
+ }
874
+ };
875
+
876
+ /**
877
+ * 触发事件 - 并发执行不等待
878
+ * @param {string} event 事件名
879
+ * @param {...any} args 事件参数
880
+ * @returns {boolean} 是否成功触发事件
881
+ */
882
+ Mod.prototype.emitAsync = function (event, ...args) {
883
+ let listeners = this.listeners(event);
884
+ if (listeners.length === 0) return false;
885
+
886
+ listeners.forEach((listener) => {
887
+ Promise.resolve()
888
+ .then(() => listener(...args))
889
+ .catch((error) => {
890
+ this._handleError(error, event);
891
+ });
892
+ });
893
+
894
+ return true;
895
+ };
896
+
897
+ /**
898
+ * 触发事件 - 并发执行并等待完成
899
+ * @param {string} event 事件名
900
+ * @param {...any} args 事件参数
901
+ * @returns {Promise<Array>} 所有监听器的执行结果
902
+ */
903
+ Mod.prototype.emitAll = async function (event, ...args) {
904
+ let listeners = this.listeners(event);
905
+ let promises = listeners.map((listener) => Promise.resolve().then(() => listener(...args)));
906
+ return await Promise.all(promises);
907
+ };
908
+
909
+ /**
910
+ * 触发事件 - 竞争执行
911
+ * @param {string} event 事件名
912
+ * @param {...any} args 事件参数
913
+ * @returns {Promise<object|null>} 第一个完成的结果
914
+ */
915
+ Mod.prototype.emitRace = async function (event, ...args) {
916
+ let listeners = this.listeners(event);
917
+ if (listeners.length === 0) return null;
918
+
919
+ let promises = listeners.map((listener, index) =>
920
+ Promise.resolve()
921
+ .then(() => listener(...args))
922
+ .then((result) => ({ index, result, status: 'fulfilled' }))
923
+ .catch((error) => ({ index, error, status: 'rejected' }))
924
+ );
925
+
926
+ return await Promise.race(promises);
927
+ };
928
+
929
+ /**
930
+ * 触发事件 - 瀑布流执行
931
+ * @param {string} event 事件名
932
+ * @param {*} value 初始值
933
+ * @param {...any} args 事件参数
934
+ * @returns {Promise<any>} 最后一个监听器的结果
935
+ */
936
+ Mod.prototype.emitWate = async function (event, value, ...args) {
937
+ let listeners = this.listeners(event);
938
+ let result = value;
939
+
940
+ for (let listener of listeners) {
941
+ try {
942
+ result = await listener(result, ...args);
943
+ } catch (error) {
944
+ this._handleError(error, event);
945
+ throw error;
946
+ }
947
+ }
948
+
949
+ return result;
950
+ };
951
+
952
+ /**
953
+ * 触发事件 - 返回第一个非空结果
954
+ * @param {string} event 事件名
955
+ * @param {...any} args 事件参数
956
+ * @returns {Promise<any>} 第一个非空结果
957
+ */
958
+ Mod.prototype.emitFirst = async function (event, ...args) {
959
+ let listeners = this.listeners(event);
960
+ for (let listener of listeners) {
961
+ let result = await listener(...args);
962
+ if (result !== undefined && result !== null) {
963
+ return result;
964
+ }
965
+ }
966
+ return undefined;
967
+ };
968
+
969
+ /**
970
+ * 事件错误处理
971
+ * @param {Error} error 错误对象
972
+ * @param {string} event 事件名
973
+ * @returns {void}
974
+ * @private
975
+ */
976
+ Mod.prototype._handleError = function (error, event) {
977
+ this.log('error', `事件 ${event} 执行失败:`, error);
978
+ };
979
+
474
980
  /**
475
981
  * 触发事件
476
982
  * @param {string} event 事件名
@@ -481,7 +987,7 @@ Mod.prototype.emitEvent = function (event, ...args) {
481
987
  };
482
988
 
483
989
  /**
484
- * 触发事件 - 随机触发
990
+ * 触发事件 - 竞争执行
485
991
  * @param {string} event 事件名
486
992
  * @param {...any} args 事件参数
487
993
  * @returns {Promise<any>} 事件触发结果
@@ -640,8 +1146,7 @@ Mod.prototype.setData = function (key, value) {
640
1146
  if (key === '_methods') {
641
1147
  throw new Error(`第一个参数(key)不能为_methods键`);
642
1148
  }
643
- if (value === undefined || value === null)
644
- throw new Error(`第二个参数(value)不能为undefined或null`);
1149
+ if (value === undefined || value === null) throw new Error(`第二个参数(value)不能为undefined或null`);
645
1150
  if (typeof value == 'function') {
646
1151
  throw new Error(`第二个参数(value)不能为函数`);
647
1152
  }
@@ -659,26 +1164,26 @@ Mod.prototype.getCacheFile = function () {
659
1164
 
660
1165
  /**
661
1166
  * 保存数据
1167
+ * @returns {void}
662
1168
  */
663
1169
  Mod.prototype.saveDatas = function () {
664
1170
  let datas = this.getDatas();
665
- let file = this.getCacheFile();
666
- file.saveJson(datas);
1171
+ saveJson(this.getCacheFile(), datas);
667
1172
  };
668
1173
 
669
1174
  /**
670
1175
  * 加载数据
1176
+ * @returns {void}
671
1177
  */
672
1178
  Mod.prototype.loadDatas = function () {
673
- let file = this.getCacheFile();
674
- let datas = file.loadJson();
1179
+ let datas = loadJson(this.getCacheFile());
675
1180
  this.setDatas(datas);
676
1181
  };
677
1182
 
678
1183
  /**
679
1184
  * 调用函数(核心执行方法)
680
1185
  * @param {string} method 函数名
681
- * @param {*} params 参数集合
1186
+ * @param {...any} params 参数集合
682
1187
  * @returns {Promise<any>} 执行结果
683
1188
  */
684
1189
  Mod.prototype.call = async function (method, ...params) {
@@ -690,9 +1195,9 @@ Mod.prototype.call = async function (method, ...params) {
690
1195
  let result;
691
1196
 
692
1197
  try {
693
- let before_result = await this._callBefore(method, params);
694
- if (before_result) return before_result;
695
- result = await this._callMain(method_func, params, before_result);
1198
+ let before = await this._callBefore(method, params);
1199
+ if (before) return before;
1200
+ result = await this._callMain(method_func, params, before);
696
1201
  result = await this._callAfter(method, params, result);
697
1202
  } catch (err) {
698
1203
  this.log('error', `执行 ${method} 失败: ${err.message}`, this._wrapError(err, { method: method }));
@@ -776,6 +1281,26 @@ Mod.prototype.getDir = function () {
776
1281
  return parent.getDir();
777
1282
  };
778
1283
 
1284
+ /**
1285
+ * 将模块类的方法复制到目标类原型
1286
+ * @description 供继承其它基类的类复用模块能力;目标类已有的自有成员不会被覆盖
1287
+ * @param {Function} cs 目标类
1288
+ * @returns {Function} 目标类
1289
+ */
1290
+ function addModMethods(cs) {
1291
+ if (typeof cs !== 'function') {
1292
+ throw new TypeError('参数(cs)必须是类');
1293
+ }
1294
+ let names = Object.getOwnPropertyNames(Mod.prototype);
1295
+ for (let name of names) {
1296
+ if (name === 'constructor') continue;
1297
+ if (Object.prototype.hasOwnProperty.call(cs.prototype, name)) continue;
1298
+ Object.defineProperty(cs.prototype, name, Object.getOwnPropertyDescriptor(Mod.prototype, name));
1299
+ }
1300
+ return cs;
1301
+ }
1302
+
779
1303
  module.exports = {
780
- Mod
1304
+ Mod,
1305
+ addModMethods
781
1306
  };