@kne/fastify-task 2.0.7 → 3.0.0-alpha.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.
@@ -7,8 +7,47 @@ module.exports = fp(async (fastify, options) => {
7
7
  const { models } = fastify[options.name];
8
8
  const { Op } = fastify.sequelize.Sequelize;
9
9
 
10
- /** statistics 插件在 main 之后注册,不能在初始化时解构,否则恒为 undefined */
11
- const callFlushCompletionStatistics = task => fastify[options.name].services.flushCompletionStatistics?.(task);
10
+ /** 通过 @kne/fastify-statistics 采集任务完成数据 */
11
+ const collectTaskStatistics = task => {
12
+ const completedAt = task.completedAt || new Date();
13
+ const createdAt = task.createdAt;
14
+ const startedAt = task.startedAt;
15
+ let waitingTime = 0;
16
+ let executionTime = 0;
17
+ let totalTime = 0;
18
+ let hasTiming = false;
19
+
20
+ if (createdAt && completedAt) {
21
+ totalTime = new Date(completedAt).getTime() - new Date(createdAt).getTime();
22
+ if (startedAt) {
23
+ waitingTime = new Date(startedAt).getTime() - new Date(createdAt).getTime();
24
+ executionTime = new Date(completedAt).getTime() - new Date(startedAt).getTime();
25
+ } else {
26
+ executionTime = totalTime;
27
+ }
28
+ hasTiming = totalTime > 0;
29
+ }
30
+
31
+ const data = {
32
+ total: 1,
33
+ [task.status]: 1
34
+ };
35
+ if (hasTiming) {
36
+ data.waitingTime = waitingTime;
37
+ data.executionTime = executionTime;
38
+ data.totalTime = totalTime;
39
+ }
40
+
41
+ fastify[`${options.name}Statistics`].services
42
+ .collect({
43
+ channel: `task:${task.type}:${task.runnerType || 'manual'}`,
44
+ data,
45
+ time: completedAt
46
+ })
47
+ .catch(e => {
48
+ fastify.log.error(`采集任务统计数据失败: ${e.message}`);
49
+ });
50
+ };
12
51
 
13
52
  const generateSignature = ({ secret, id, data }) => {
14
53
  const dataToSign = `${id}|${typeof data === 'string' ? data : JSON.stringify(data)}`;
@@ -23,7 +62,16 @@ module.exports = fp(async (fastify, options) => {
23
62
  return signature === expectedSignature;
24
63
  };
25
64
 
26
- const create = async ({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, options: currentOptions }) => {
65
+ const create = async ({ userId, input, type, targetId, targetType, runnerType, delay = 0, scriptName, priority = 0, parentTaskId, maxRetries = 0, options: currentOptions }) => {
66
+ if (typeof delay !== 'number' || delay < 0) {
67
+ throw new Error('delay 必须为非负数');
68
+ }
69
+ if (typeof priority !== 'number' || !Number.isInteger(priority)) {
70
+ throw new Error('priority 必须为整数');
71
+ }
72
+ if (typeof maxRetries !== 'number' || !Number.isInteger(maxRetries) || maxRetries < 0) {
73
+ throw new Error('maxRetries 必须为非负整数');
74
+ }
27
75
  if (typeof options.task[type] !== 'function') {
28
76
  throw new Error('未找到合法的任务声明');
29
77
  }
@@ -34,6 +82,9 @@ module.exports = fp(async (fastify, options) => {
34
82
  targetId,
35
83
  targetType,
36
84
  runnerType,
85
+ priority,
86
+ parentTaskId,
87
+ maxRetries,
37
88
  startTime: delay > 0 ? new Date(Date.now() + 1000 * delay) : new Date(),
38
89
  scriptName,
39
90
  options: currentOptions
@@ -54,10 +105,20 @@ module.exports = fp(async (fastify, options) => {
54
105
  };
55
106
 
56
107
  const executor = async ({ type, scriptName, ...props }) => {
57
- const taskModulePath = path.resolve(options.dir, type, `${scriptName || options.scriptName}.js`);
58
- if (!(await fs.exists(taskModulePath))) {
59
- console.warn(`未匹配到任务执行器:${taskModulePath}`);
108
+ const scriptFile = `${scriptName || options.scriptName}.js`;
109
+ let taskModulePath = null;
110
+ for (const dir of options.dirs) {
111
+ const candidate = path.resolve(dir, type, scriptFile);
112
+ if (await fs.exists(candidate)) {
113
+ taskModulePath = candidate;
114
+ break;
115
+ }
116
+ }
117
+ if (!taskModulePath) {
118
+ throw new Error(`未匹配到任务执行器:${type}/${scriptFile},已搜索目录:${options.dirs.join(',')}`);
60
119
  }
120
+ // 清除 require 缓存,确保运行期间模块更新后能加载最新版本
121
+ delete require.cache[taskModulePath];
61
122
  return await require(taskModulePath)(fastify, options, {
62
123
  ...props,
63
124
  updateProgress: async progress => {
@@ -140,7 +201,7 @@ module.exports = fp(async (fastify, options) => {
140
201
  error: result,
141
202
  completedAt: new Date()
142
203
  });
143
- callFlushCompletionStatistics(task);
204
+ collectTaskStatistics(task);
144
205
  return;
145
206
  }
146
207
  await options.task[task.type]({ task, result: result.data, context: task.context });
@@ -150,54 +211,95 @@ module.exports = fp(async (fastify, options) => {
150
211
  progress: 100,
151
212
  completedAt: new Date()
152
213
  });
153
- callFlushCompletionStatistics(task);
214
+ collectTaskStatistics(task);
154
215
  };
155
216
 
156
217
  const processSystemTask = async task => {
157
- try {
158
- await task.update({
159
- status: 'running',
160
- startedAt: new Date(),
161
- progress: 0,
162
- error: null,
163
- output: null,
164
- pollCount: 0,
165
- pollResults: [],
166
- completedAt: null,
167
- context: {}
168
- });
169
- const addLog = props => {
170
- return log(Object.assign({}, props, { taskId: task.id }));
171
- };
172
- executor({ type: task.type, scriptName: task.scriptName, task, log: addLog })
173
- .then(async result => {
174
- if (result === false) {
175
- return;
176
- }
177
- await options.task[task.type]({ task, result, context: task.context });
218
+ await task.update({
219
+ status: 'running',
220
+ startedAt: new Date(),
221
+ progress: 0,
222
+ error: null,
223
+ output: null,
224
+ pollCount: 0,
225
+ pollResults: [],
226
+ completedAt: null,
227
+ context: {}
228
+ });
229
+ const addLog = props => {
230
+ return log(Object.assign({}, props, { taskId: task.id }));
231
+ };
232
+
233
+ // #3: 任务超时自动失败
234
+ const createTimeout = ms => new Promise((_, reject) =>
235
+ setTimeout(() => reject(new Error(`任务执行超时(${ms}ms)`)), ms)
236
+ );
237
+
238
+ const executorPromise = executor({ type: task.type, scriptName: task.scriptName, task, log: addLog });
239
+ const racePromise = options.taskTimeout > 0
240
+ ? Promise.race([executorPromise, createTimeout(options.taskTimeout)])
241
+ : executorPromise;
242
+
243
+ return racePromise
244
+ .then(async result => {
245
+ if (result === false) {
246
+ return;
247
+ }
248
+ await options.task[task.type]({ task, result, context: task.context });
249
+ await task.update({
250
+ status: 'success',
251
+ output: result,
252
+ progress: 100,
253
+ completedAt: new Date()
254
+ });
255
+ collectTaskStatistics(task);
256
+ // #2: 任务依赖/链式执行 — 父任务成功后激活子任务
257
+ await triggerChildTasks(task);
258
+ })
259
+ .catch(async e => {
260
+ // #4: 重试策略 — 判断是否自动重试
261
+ const currentRetryCount = (task.retryCount || 0) + 1;
262
+ const maxRetries = task.maxRetries || 0;
263
+ if (currentRetryCount < maxRetries) {
264
+ // 指数退避:baseDelay * 2^retryCount
265
+ const baseDelay = options.retryBaseDelay || 5000;
266
+ const backoffDelay = baseDelay * Math.pow(2, currentRetryCount - 1);
178
267
  await task.update({
179
- status: 'success',
180
- output: result,
181
- progress: 100,
182
- completedAt: new Date()
268
+ status: 'pending',
269
+ retryCount: currentRetryCount,
270
+ error: (e.stack || '').replaceAll(process.cwd(), '/server'),
271
+ startTime: new Date(Date.now() + backoffDelay),
272
+ completedAt: null
183
273
  });
184
- callFlushCompletionStatistics(task);
185
- })
186
- .catch(async e => {
274
+ fastify.log.info(`任务 ${task.id} 第 ${currentRetryCount} 次重试,${backoffDelay}ms 后执行`);
275
+ } else {
187
276
  await task.update({
188
277
  status: 'failed',
189
278
  error: (e.stack || '').replaceAll(process.cwd(), '/server'),
190
- completedAt: new Date()
279
+ completedAt: new Date(),
280
+ retryCount: currentRetryCount
191
281
  });
192
- callFlushCompletionStatistics(task);
193
- });
194
- } catch (e) {
195
- await task.update({
196
- status: 'failed',
197
- error: (e.stack || '').replaceAll(process.cwd(), '/server'),
198
- completedAt: new Date()
282
+ collectTaskStatistics(task);
283
+ }
199
284
  });
200
- callFlushCompletionStatistics(task);
285
+ };
286
+
287
+ // #2: 触发子任务(父任务成功后激活 pending 的子任务)
288
+ const triggerChildTasks = async parentTask => {
289
+ const childTasks = await models.task.findAll({
290
+ where: {
291
+ parentTaskId: parentTask.id,
292
+ status: 'pending'
293
+ }
294
+ });
295
+ if (childTasks.length === 0) return;
296
+
297
+ fastify.log.info(`父任务 ${parentTask.id} 完成,激活 ${childTasks.length} 个子任务`);
298
+ for (const child of childTasks) {
299
+ if (child.runnerType === 'system') {
300
+ await processSystemTask(child);
301
+ }
302
+ // manual 类型子任务保持 pending,等待手动执行
201
303
  }
202
304
  };
203
305
 
@@ -213,6 +315,7 @@ module.exports = fp(async (fastify, options) => {
213
315
  fastify.log.info(`当前运行中的系统任务数(${runningTaskCount})已达上限(${options.limit}),暂不执行新任务`);
214
316
  return;
215
317
  }
318
+ // #1: 按优先级降序 + startTime 升序获取待处理任务
216
319
  const pendingTasks = await models.task.findAll({
217
320
  where: {
218
321
  runnerType: 'system',
@@ -221,18 +324,16 @@ module.exports = fp(async (fastify, options) => {
221
324
  [Op.lte]: new Date()
222
325
  }
223
326
  },
224
- limit: options.limit
225
- });
226
-
227
- const count = await models.task.count({
228
- where: {
229
- runnerType: 'system',
230
- status: 'pending'
231
- }
327
+ order: [
328
+ ['priority', 'DESC'],
329
+ ['startTime', 'ASC']
330
+ ],
331
+ limit: limit
232
332
  });
233
333
 
234
334
  if (pendingTasks.length > 0) {
235
- fastify.log.info(`本轮执行 ${pendingTasks.length}/${count} 个待处理的系统任务`);
335
+ fastify.log.info(`本轮执行 ${pendingTasks.length} 个待处理的系统任务`);
336
+ // #8: await processSystemTask 返回的 Promise,防止同任务重复执行
236
337
  await Promise.all(pendingTasks.map(async task => processSystemTask(task)));
237
338
  }
238
339
  };
@@ -246,6 +347,9 @@ module.exports = fp(async (fastify, options) => {
246
347
  };
247
348
 
248
349
  const cancel = async ({ id, targetId, targetType, type }) => {
350
+ if (!id && !(targetId && targetType && type)) {
351
+ throw new Error('必须提供 id 或 targetId+targetType+type');
352
+ }
249
353
  if (targetId && targetType && type) {
250
354
  const bulkWhere = {
251
355
  targetId,
@@ -267,7 +371,7 @@ module.exports = fp(async (fastify, options) => {
267
371
  }
268
372
  );
269
373
  for (const row of tasksToCancel) {
270
- callFlushCompletionStatistics(Object.assign({}, row, { status: 'canceled', completedAt }));
374
+ collectTaskStatistics(Object.assign({}, row, { status: 'canceled', completedAt }));
271
375
  }
272
376
  return affectedCount;
273
377
  }
@@ -280,15 +384,12 @@ module.exports = fp(async (fastify, options) => {
280
384
  status: 'canceled',
281
385
  completedAt: new Date()
282
386
  });
283
- callFlushCompletionStatistics(task);
387
+ collectTaskStatistics(task);
284
388
  }
285
389
  };
286
390
 
287
391
  const complete = async ({ id, userId, output, ...props }) => {
288
392
  const task = await detail({ id });
289
- if (!task) {
290
- throw new Error('任务不存在');
291
- }
292
393
  if (props.status === 'success') {
293
394
  try {
294
395
  await options.task[task.type]({ task, result: output });
@@ -300,7 +401,7 @@ module.exports = fp(async (fastify, options) => {
300
401
  startedAt: task.startedAt || task.createdAt,
301
402
  completedUserId: userId
302
403
  });
303
- callFlushCompletionStatistics(task);
404
+ collectTaskStatistics(task);
304
405
  } catch (e) {
305
406
  await task.update(
306
407
  Object.assign({}, props, {
@@ -311,7 +412,7 @@ module.exports = fp(async (fastify, options) => {
311
412
  startedAt: task.startedAt || task.createdAt
312
413
  })
313
414
  );
314
- callFlushCompletionStatistics(task);
415
+ collectTaskStatistics(task);
315
416
  throw e;
316
417
  }
317
418
  } else {
@@ -323,17 +424,16 @@ module.exports = fp(async (fastify, options) => {
323
424
  completedUserId: userId
324
425
  })
325
426
  );
326
- callFlushCompletionStatistics(task);
427
+ collectTaskStatistics(task);
327
428
  }
328
429
  };
329
430
 
330
431
  const waitingComplete = async ({ id, pollInterval = 1000, maxPollTimes = 20 }) => {
331
432
  const task = await detail({ id });
332
- if (!task) {
333
- throw new Error('任务不存在');
334
- }
335
433
 
336
434
  if (task.status === 'pending') {
435
+ // 标记为最高优先级,确保立即执行(即使因重试等重新入队也会被优先处理)
436
+ await task.update({ priority: Number.MAX_SAFE_INTEGER });
337
437
  await processSystemTask(task);
338
438
  }
339
439
 
@@ -391,7 +491,7 @@ module.exports = fp(async (fastify, options) => {
391
491
  }
392
492
  };
393
493
 
394
- const list = async ({ filter, perPage, currentPage, sort }) => {
494
+ const list = async ({ filter, perPage = 20, currentPage = 1, sort }) => {
395
495
  const whereQuery = {};
396
496
 
397
497
  ['id', 'targetId', 'type', 'status', 'runnerType'].forEach(key => {
@@ -417,22 +517,18 @@ module.exports = fp(async (fastify, options) => {
417
517
  whereQuery.completedAt = getTimeQuery(filter.completedAt);
418
518
  }
419
519
 
420
- // 处理sort排序
421
- let orderBy = 'createdAt';
422
- let orderDirection = 'DESC';
520
+ // 处理sort排序:支持多字段排序
521
+ let order = [['createdAt', 'DESC']];
423
522
 
424
523
  if (sort && Object.keys(sort).length > 0) {
425
- Object.keys(sort).forEach(key => {
426
- orderBy = key;
427
- orderDirection = sort[key];
428
- });
524
+ order = Object.entries(sort).map(([key, direction]) => [key, direction]);
429
525
  }
430
526
 
431
527
  const { rows, count } = await models.task.findAndCountAll({
432
528
  where: Object.assign({}, whereQuery),
433
529
  offset: perPage * (currentPage - 1),
434
530
  limit: perPage,
435
- order: [[orderBy, orderDirection]]
531
+ order: order
436
532
  });
437
533
 
438
534
  return {
@@ -449,7 +545,9 @@ module.exports = fp(async (fastify, options) => {
449
545
  await task.update({
450
546
  status: 'pending',
451
547
  completedAt: null,
452
- completedUserId: null
548
+ completedUserId: null,
549
+ retryCount: 0,
550
+ error: null
453
551
  });
454
552
  };
455
553
 
@@ -467,9 +565,6 @@ module.exports = fp(async (fastify, options) => {
467
565
  const log = async ({ id, taskId, data, message = '' }) => {
468
566
  const targetId = id || taskId;
469
567
  const task = await detail({ id: targetId });
470
- if (!task) {
471
- throw new Error('任务不存在');
472
- }
473
568
 
474
569
  const currentOptions = task.options || {};
475
570
  const logs = (currentOptions.logs || []).slice(0);
@@ -494,9 +589,6 @@ module.exports = fp(async (fastify, options) => {
494
589
  const logWithSignature = async ({ id, taskId, data, message = '', signature }) => {
495
590
  const targetId = id || taskId;
496
591
  const task = await detail({ id: targetId });
497
- if (!task) {
498
- throw new Error('任务不存在');
499
- }
500
592
 
501
593
  if (task.context?.secret && !verifySignature({ secret: task.context.secret, id: targetId, data: { data, message }, signature })) {
502
594
  throw new Error('签名验证失败');
@@ -506,10 +598,7 @@ module.exports = fp(async (fastify, options) => {
506
598
  };
507
599
 
508
600
  const callback = async ({ id, code, data, message }) => {
509
- const task = await detail({ id });
510
- if (!task) {
511
- throw new Error('任务不存在');
512
- }
601
+ await detail({ id });
513
602
 
514
603
  const result = { code, data, message };
515
604
  await log({ id, message: '回调结果', data: JSON.stringify(result) });
@@ -532,9 +621,6 @@ module.exports = fp(async (fastify, options) => {
532
621
 
533
622
  const callbackWithSignature = async ({ id, code, data, message, signature }) => {
534
623
  const task = await detail({ id });
535
- if (!task) {
536
- throw new Error('任务不存在');
537
- }
538
624
 
539
625
  if (task.context?.secret && !verifySignature({ secret: task.context.secret, id, data: { code, data, message }, signature })) {
540
626
  throw new Error('签名验证失败');
@@ -543,6 +629,33 @@ module.exports = fp(async (fastify, options) => {
543
629
  return callback({ id, code, data, message });
544
630
  };
545
631
 
632
+ const append = async ({ dirs, tasks }) => {
633
+ const result = { dirs: [], tasks: [] };
634
+ if (Array.isArray(dirs)) {
635
+ for (const dir of dirs) {
636
+ if (!options.dirs.includes(dir)) {
637
+ if (!(await fs.exists(dir))) {
638
+ console.warn(`append 目录不存在:${dir},仍会添加但运行时可能无法匹配任务执行器`);
639
+ }
640
+ options.dirs.push(dir);
641
+ result.dirs.push(dir);
642
+ }
643
+ }
644
+ }
645
+ if (tasks && typeof tasks === 'object') {
646
+ Object.entries(tasks).forEach(([type, handler]) => {
647
+ if (typeof handler !== 'function') {
648
+ throw new Error(`任务 ${type} 的 handler 必须是一个函数`);
649
+ }
650
+ if (typeof options.task[type] !== 'function') {
651
+ options.task[type] = handler;
652
+ result.tasks.push(type);
653
+ }
654
+ });
655
+ }
656
+ return result;
657
+ };
658
+
546
659
  Object.assign(fastify[options.name].services, {
547
660
  create,
548
661
  detail,
@@ -559,6 +672,7 @@ module.exports = fp(async (fastify, options) => {
559
672
  executor,
560
673
  processNext,
561
674
  processSystemTask,
562
- waitingComplete
675
+ waitingComplete,
676
+ append
563
677
  });
564
678
  });