@kne/fastify-task 3.0.0-alpha.7 → 3.0.0-alpha.9
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 +454 -21
- package/index.js +1 -1
- package/libs/controllers/main.js +0 -3
- package/libs/helpers/task-service-context.js +556 -0
- package/libs/models/task.js +1 -1
- package/libs/services/append.js +45 -0
- package/libs/services/callback.js +109 -0
- package/libs/services/executor.js +10 -0
- package/libs/services/main.js +7 -776
- package/libs/services/scheduler.js +230 -0
- package/libs/services/statistics.js +2 -4
- package/libs/services/task.js +224 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -29,10 +29,10 @@ pending(待执行)
|
|
|
29
29
|
claimPendingTasks(按优先级与 startTime 原子认领)
|
|
30
30
|
↓
|
|
31
31
|
running(执行中)
|
|
32
|
-
├→ executor 正常完成 → success
|
|
32
|
+
├→ executor 正常完成 → handler → next task → success
|
|
33
33
|
├→ executor 调用 next() → waiting
|
|
34
34
|
├→ executor 异常 → retry / failed
|
|
35
|
-
└→ waiting → processNext / callbackWithSignature → success / failed
|
|
35
|
+
└→ waiting → processNext / callbackWithSignature → handler → next task → success / failed
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
| 节点 | 说明 |
|
|
@@ -41,6 +41,7 @@ pending(待执行)
|
|
|
41
41
|
| `claimPendingTasks` | 使用带状态条件的更新将 `pending` 原子认领为 `running`,避免多实例重复执行 |
|
|
42
42
|
| `processSystemTask` | 执行任务脚本,并根据结果、异常、重试次数和回调状态更新任务 |
|
|
43
43
|
| `collectTaskStatistics` | 任务进入终态后采集数量和耗时指标 |
|
|
44
|
+
| `taskRegistry` | 维护主项目与插件通过 `append` 注册的任务声明、脚本目录和生命周期钩子 |
|
|
44
45
|
|
|
45
46
|
> **关键设计**:cron 每次触发 `runner` 时先检测超时任务,再按 **优先级降序 + startTime 升序** 认领待执行系统任务。认领通过条件更新完成,只有仍处于
|
|
46
47
|
`pending` 的任务会被当前实例执行。
|
|
@@ -88,6 +89,8 @@ pending(待执行)
|
|
|
88
89
|
| 自动重试 | 指数退避重试策略 |
|
|
89
90
|
| 超时控制 | 全局执行超时和任务级超时均使用毫秒,超时自动标记 failed |
|
|
90
91
|
| 多实例调度 | 待执行任务通过原子认领进入 running,降低重复执行风险 |
|
|
92
|
+
| 插件任务注册 | 插件可通过 `append` 注册自己的任务目录、脚本名、处理函数和错误处理 |
|
|
93
|
+
| 链式任务 | 支持通过 `next` 声明后续任务,按当前输出创建下一任务 |
|
|
91
94
|
| 统计面板 | 任务统计数据查询 + SSE 实时推送 |
|
|
92
95
|
|
|
93
96
|
### 使用方法
|
|
@@ -109,13 +112,30 @@ fastify.register(require('@kne/fastify-task'), {
|
|
|
109
112
|
'export-excel': async ({ task, result, context }) => {
|
|
110
113
|
console.log('导出任务完成:', result);
|
|
111
114
|
},
|
|
112
|
-
'send-email':
|
|
113
|
-
|
|
115
|
+
'send-email': {
|
|
116
|
+
handler: async ({ task, result }) => {
|
|
117
|
+
// 发送邮件完成后的处理
|
|
118
|
+
},
|
|
119
|
+
errorHandler: async ({ task, error }) => {
|
|
120
|
+
// 可选:当前任务类型自己的错误处理
|
|
121
|
+
}
|
|
114
122
|
}
|
|
115
123
|
}
|
|
116
124
|
});
|
|
117
125
|
```
|
|
118
126
|
|
|
127
|
+
#### 任务声明与命名空间
|
|
128
|
+
|
|
129
|
+
任务类型可以由主项目注册时的 `task` 配置声明,也可以由其他插件通过 `append` 动态声明。声明对象支持 `handler`、`errorHandler` 和
|
|
130
|
+
`next`,其中 `handler` 可省略;只要任务类型已经声明并存在对应执行脚本,就可以创建和执行任务。
|
|
131
|
+
|
|
132
|
+
| 声明来源 | 默认命名空间 | 任务名解析规则 |
|
|
133
|
+
|------------|--------------|-----------------------------------------------|
|
|
134
|
+
| 主项目 `task` | `options.name` | 可直接使用本地任务名,也可使用 `{options.name}.任务名` |
|
|
135
|
+
| 插件 `append` | `append.name` | 本地任务名只在当前插件内查找,跨插件使用 `{append.name}.任务名` |
|
|
136
|
+
|
|
137
|
+
> **关键设计**:插件任务不能访问主项目中的任务。插件内的裸任务名只解析到当前插件命名空间,跨插件访问必须使用 `包名.任务名`。
|
|
138
|
+
|
|
119
139
|
#### 任务脚本开发
|
|
120
140
|
|
|
121
141
|
在 `dirs` 配置的目录下创建任务脚本,目录结构:
|
|
@@ -186,7 +206,7 @@ module.exports = async (fastify, options, { task, updateProgress, polling, next,
|
|
|
186
206
|
|
|
187
207
|
#### 任务类型处理函数
|
|
188
208
|
|
|
189
|
-
|
|
209
|
+
任务成功后如果配置了 `handler`,会自动调用对应处理函数;未配置时直接进入成功收尾。处理函数接收参数:
|
|
190
210
|
|
|
191
211
|
| 参数名 | 类型 | 说明 |
|
|
192
212
|
|-----------|-----------------|----------------------|
|
|
@@ -194,14 +214,33 @@ module.exports = async (fastify, options, { task, updateProgress, polling, next,
|
|
|
194
214
|
| `result` | object / string | 任务输出结果 |
|
|
195
215
|
| `context` | object | 任务上下文(`next` 时设置的数据) |
|
|
196
216
|
|
|
217
|
+
#### 错误处理函数
|
|
218
|
+
|
|
219
|
+
任务最终失败时优先调用任务声明中的 `errorHandler`;未配置时调用全局 `errorHandler`。如果任务级 `errorHandler` 抛出异常,仍会继续交给全局
|
|
220
|
+
`errorHandler` 处理。
|
|
221
|
+
|
|
222
|
+
| 处理器 | 触发条件 | 说明 |
|
|
223
|
+
|------------------------|---------------|----------------------------|
|
|
224
|
+
| `tasks[type].errorHandler` | 当前任务最终失败 | 当前任务类型自己的错误处理,优先级最高 |
|
|
225
|
+
| `options.errorHandler` | 未配置任务级处理或任务级处理抛错 | 全局兜底错误处理,不改变任务最终失败状态 |
|
|
226
|
+
|
|
197
227
|
#### 运行时动态添加
|
|
198
228
|
|
|
199
229
|
```js
|
|
200
|
-
//
|
|
230
|
+
// 插件包通过 append 方法运行时添加任务目录和类型
|
|
201
231
|
const result = await fastify.task.services.append({
|
|
202
|
-
|
|
232
|
+
name: 'trtcConference',
|
|
233
|
+
dir: '/path/to/tasks',
|
|
234
|
+
scriptName: 'index',
|
|
203
235
|
tasks: {
|
|
204
|
-
'
|
|
236
|
+
'record-video': {
|
|
237
|
+
handler: async ({ task, result }) => {
|
|
238
|
+
// 可选:任务成功后的处理逻辑
|
|
239
|
+
},
|
|
240
|
+
errorHandler: async ({ task, error }) => {
|
|
241
|
+
// 可选:任务失败后的处理逻辑
|
|
242
|
+
},
|
|
243
|
+
next: ['transcode-video', 'analyze-video']
|
|
205
244
|
}
|
|
206
245
|
}
|
|
207
246
|
});
|
|
@@ -209,6 +248,169 @@ const result = await fastify.task.services.append({
|
|
|
209
248
|
// result.tasks → 实际添加的类型列表
|
|
210
249
|
```
|
|
211
250
|
|
|
251
|
+
`append.scriptName` 只影响本次 append 注册的任务;未配置时固定使用 `index.js`,不会使用主项目注册 task 时的 `options.scriptName`。
|
|
252
|
+
|
|
253
|
+
#### 链式任务 next
|
|
254
|
+
|
|
255
|
+
`tasks[type].next` 用于声明当前任务成功后的后续任务,只配置任务名称:
|
|
256
|
+
|
|
257
|
+
| next 类型 | 下一个任务选择方式 |
|
|
258
|
+
|---------|------------------------------------|
|
|
259
|
+
| string | 固定创建该任务名对应的下一任务 |
|
|
260
|
+
| array | 从当前任务 `output.next` 读取下一任务名,并要求在数组中 |
|
|
261
|
+
|
|
262
|
+
创建下一任务时,`input` 使用当前任务 `output`,`input.name` 沿用当前任务的 `input.name`,`targetType` 固定为 `task`,`targetId` 和
|
|
263
|
+
`parentTaskId` 为当前任务 id,`context` 从当前任务深拷贝。
|
|
264
|
+
|
|
265
|
+
**业务示例:会议录像处理**
|
|
266
|
+
|
|
267
|
+
会议结束后先执行 `record-video` 获取录像文件。脚本根据录像结果决定下一步:如果需要转码则进入 `transcode-video`,如果录像已经可直接使用则进入
|
|
268
|
+
`save-video`。
|
|
269
|
+
|
|
270
|
+
```js
|
|
271
|
+
await fastify.task.services.append({
|
|
272
|
+
name: 'trtcConference',
|
|
273
|
+
dir: path.resolve(__dirname, './libs/tasks'),
|
|
274
|
+
tasks: {
|
|
275
|
+
'record-video': {
|
|
276
|
+
handler: async ({ task, result }) => {
|
|
277
|
+
await fastify.trtcConference.services.saveRecordMeta(result);
|
|
278
|
+
},
|
|
279
|
+
next: ['transcode-video', 'save-video']
|
|
280
|
+
},
|
|
281
|
+
'transcode-video': {
|
|
282
|
+
next: 'save-video'
|
|
283
|
+
},
|
|
284
|
+
'save-video': {
|
|
285
|
+
handler: async ({ result }) => {
|
|
286
|
+
await fastify.trtcConference.services.saveRecordVideo(result);
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
});
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
`record-video/index.js` 可以通过 `output.next` 指定下一步:
|
|
294
|
+
|
|
295
|
+
```js
|
|
296
|
+
module.exports = async (fastify, options, { task }) => {
|
|
297
|
+
const record = await fastify.trtc.services.checkRecord(task.input);
|
|
298
|
+
return {
|
|
299
|
+
name: task.input.name,
|
|
300
|
+
fileId: record.fileId,
|
|
301
|
+
fileUrl: record.fileUrl,
|
|
302
|
+
next: record.needTranscode ? 'transcode-video' : 'save-video'
|
|
303
|
+
};
|
|
304
|
+
};
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
如果 `record.needTranscode` 为 `true`,系统会创建 `transcode-video` 任务;否则创建 `save-video` 任务。下一任务的 `input` 就是上面返回的
|
|
308
|
+
`output`,并自动带上当前任务的 `context`。
|
|
309
|
+
|
|
310
|
+
**业务示例:多级审批**
|
|
311
|
+
|
|
312
|
+
合同审批需要依次经过部门主管、财务和法务。每一级审批任务只负责处理当前节点,并把审批轨迹写入 `context.approvals`。下一任务创建时会复制当前
|
|
313
|
+
`context`,因此后续节点可以看到前面所有审批记录。
|
|
314
|
+
|
|
315
|
+
```js
|
|
316
|
+
await fastify.task.services.append({
|
|
317
|
+
name: 'contractApproval',
|
|
318
|
+
dir: path.resolve(__dirname, './libs/tasks'),
|
|
319
|
+
tasks: {
|
|
320
|
+
'manager-approval': {
|
|
321
|
+
next: 'finance-approval'
|
|
322
|
+
},
|
|
323
|
+
'finance-approval': {
|
|
324
|
+
next: ['legal-approval', 'archive-contract']
|
|
325
|
+
},
|
|
326
|
+
'legal-approval': {
|
|
327
|
+
next: 'archive-contract'
|
|
328
|
+
},
|
|
329
|
+
'archive-contract': {
|
|
330
|
+
handler: async ({ task, context }) => {
|
|
331
|
+
await fastify.contract.services.archive({
|
|
332
|
+
contractId: task.input.contractId,
|
|
333
|
+
approvals: context.approvals
|
|
334
|
+
});
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
});
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
创建第一个审批任务时写入初始上下文:
|
|
342
|
+
|
|
343
|
+
```js
|
|
344
|
+
await fastify.task.services.create({
|
|
345
|
+
type: 'contractApproval.manager-approval',
|
|
346
|
+
targetType: 'contract',
|
|
347
|
+
targetId: contract.id,
|
|
348
|
+
runnerType: 'system',
|
|
349
|
+
input: {
|
|
350
|
+
name: contract.name,
|
|
351
|
+
contractId: contract.id
|
|
352
|
+
},
|
|
353
|
+
context: {
|
|
354
|
+
requestId: contract.requestId,
|
|
355
|
+
approvals: []
|
|
356
|
+
}
|
|
357
|
+
});
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
`manager-approval/index.js` 更新当前任务的 `context`:
|
|
361
|
+
|
|
362
|
+
```js
|
|
363
|
+
module.exports = async (fastify, options, { task }) => {
|
|
364
|
+
const approvals = [...(task.context.approvals || []), {
|
|
365
|
+
node: 'manager',
|
|
366
|
+
approver: 'u-manager-1',
|
|
367
|
+
result: 'approved',
|
|
368
|
+
time: new Date().toISOString()
|
|
369
|
+
}];
|
|
370
|
+
|
|
371
|
+
await task.update({
|
|
372
|
+
context: {
|
|
373
|
+
...task.context,
|
|
374
|
+
approvals
|
|
375
|
+
}
|
|
376
|
+
});
|
|
377
|
+
|
|
378
|
+
return {
|
|
379
|
+
name: task.input.name,
|
|
380
|
+
contractId: task.input.contractId
|
|
381
|
+
};
|
|
382
|
+
};
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
`finance-approval/index.js` 可以根据金额动态决定是否进入法务审批:
|
|
386
|
+
|
|
387
|
+
```js
|
|
388
|
+
module.exports = async (fastify, options, { task }) => {
|
|
389
|
+
const approvals = [...(task.context.approvals || []), {
|
|
390
|
+
node: 'finance',
|
|
391
|
+
approver: 'u-finance-1',
|
|
392
|
+
result: 'approved',
|
|
393
|
+
time: new Date().toISOString()
|
|
394
|
+
}];
|
|
395
|
+
|
|
396
|
+
await task.update({
|
|
397
|
+
context: {
|
|
398
|
+
...task.context,
|
|
399
|
+
approvals
|
|
400
|
+
}
|
|
401
|
+
});
|
|
402
|
+
|
|
403
|
+
return {
|
|
404
|
+
name: task.input.name,
|
|
405
|
+
contractId: task.input.contractId,
|
|
406
|
+
next: task.input.amount > 100000 ? 'legal-approval' : 'archive-contract'
|
|
407
|
+
};
|
|
408
|
+
};
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
在这个流程中,`finance-approval` 会拿到主管审批后复制过来的 `context.approvals`;`legal-approval` 或 `archive-contract`
|
|
412
|
+
也会继续拿到财务审批后更新过的 `context`。每次创建下一任务都会深拷贝当前任务完成时的 `context`,不会和上一任务共享同一个对象引用。
|
|
413
|
+
|
|
212
414
|
#### 签名验证
|
|
213
415
|
|
|
214
416
|
当任务通过 `next({ secret: '密钥' })` 设置了密钥时,外部回调需提供 HMAC-SHA256 签名。
|
|
@@ -281,9 +483,10 @@ const signature = generateSignature({
|
|
|
281
483
|
| `recoverRunningTaskAfter` | number / null | 否 | `null` | 启动恢复 running 任务的陈旧阈值(毫秒);未传时使用 `taskTimeout`,若 `taskTimeout` 为 0 则使用 `1800000` |
|
|
282
484
|
| `recoverRunningTasksOnStart` | boolean | 否 | `true` | 启动时是否恢复陈旧 running 任务 |
|
|
283
485
|
| `retryBaseDelay` | number | 否 | `5000` | 重试基础延迟(毫秒),实际延迟 = `retryBaseDelay * 2^(retryCount-1)` |
|
|
486
|
+
| `errorHandler` | function | 否 | - | 全局错误处理函数,任务级 `errorHandler` 未配置或抛错时调用 |
|
|
284
487
|
| `getUserModel` | function | 否 | - | 获取用户 Model 的函数 |
|
|
285
488
|
| `getAuthenticate` | function | 否 | - | 获取认证中间件的函数 |
|
|
286
|
-
| `task` | object | 否 | `{}` |
|
|
489
|
+
| `task` | object | 否 | `{}` | 主项目任务声明,支持 `{ [type]: handler }` 或 `{ [type]: { handler, errorHandler, next } }` |
|
|
287
490
|
|
|
288
491
|
> **关键设计**:`dirs` 初始化逻辑 — 优先使用用户传入的 `dirs`,否则以 `dir` 为默认值;若 `dirs` 中不包含 `dir`,则将 `dir`
|
|
289
492
|
> 插入 `dirs` 首位,保证向后兼容。
|
|
@@ -298,7 +501,7 @@ const signature = generateSignature({
|
|
|
298
501
|
|
|
299
502
|
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
300
503
|
|--------------|--------|----|-----------|---------------------------|
|
|
301
|
-
| type | string | 是 | - |
|
|
504
|
+
| type | string | 是 | - | 任务类型,必须已在主项目或 `append` 中声明 |
|
|
302
505
|
| targetId | string | 是 | - | 目标对象ID |
|
|
303
506
|
| targetType | string | 是 | - | 目标对象类型 |
|
|
304
507
|
| input | object | 否 | - | 输入数据 |
|
|
@@ -309,6 +512,7 @@ const signature = generateSignature({
|
|
|
309
512
|
| parentTaskId | string | 否 | - | 父任务ID,用于任务依赖 |
|
|
310
513
|
| maxRetries | number | 否 | `0` | 最大自动重试次数 |
|
|
311
514
|
| timeout | number | 否 | `3600000` | 任务超时时间(毫秒),0 表示不超时 |
|
|
515
|
+
| context | object | 否 | `{}` | 初始上下文,用于回调签名、日志或链式任务传递 |
|
|
312
516
|
|
|
313
517
|
返回值:
|
|
314
518
|
|
|
@@ -328,7 +532,6 @@ const signature = generateSignature({
|
|
|
328
532
|
| currentPage | number | 否 | `1` | 当前页码 |
|
|
329
533
|
| filter.id | string | 否 | - | 任务ID |
|
|
330
534
|
| filter.targetId | string | 否 | - | 目标对象ID |
|
|
331
|
-
| filter.targetName | string | 否 | - | 目标名称(模糊匹配 `input.name`) |
|
|
332
535
|
| filter.type | string | 否 | - | 任务类型 |
|
|
333
536
|
| filter.status | string | 否 | - | 任务状态 |
|
|
334
537
|
| filter.runnerType | string | 否 | - | 执行者类型 |
|
|
@@ -503,15 +706,15 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
|
|
|
503
706
|
|
|
504
707
|
#### 任务管理
|
|
505
708
|
|
|
506
|
-
| 方法签名
|
|
507
|
-
|
|
508
|
-
| `services.create({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, priority, parentTaskId, maxRetries, timeout, options })` | 创建任务,返回 Task 实例 |
|
|
509
|
-
| `services.detail({ id })`
|
|
510
|
-
| `services.list({ filter, perPage, currentPage, sort })`
|
|
511
|
-
| `services.complete({ id, userId, status, output, error })`
|
|
512
|
-
| `services.cancel({ id, targetId, targetType, type })`
|
|
513
|
-
| `services.retry({ id, taskIds })`
|
|
514
|
-
| `services.waitingComplete({ id, pollInterval, maxPollTimes })`
|
|
709
|
+
| 方法签名 | 说明 |
|
|
710
|
+
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
|
|
711
|
+
| `services.create({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, priority, parentTaskId, maxRetries, timeout, context, options })` | 创建任务,返回 Task 实例 |
|
|
712
|
+
| `services.detail({ id })` | 获取任务详情,返回 Task 实例 |
|
|
713
|
+
| `services.list({ filter, perPage, currentPage, sort })` | 获取任务列表,返回 `{ pageData, totalCount }` |
|
|
714
|
+
| `services.complete({ id, userId, status, output, error })` | 手动完成任务 |
|
|
715
|
+
| `services.cancel({ id, targetId, targetType, type })` | 取消任务,支持单个或批量 |
|
|
716
|
+
| `services.retry({ id, taskIds })` | 重试任务,仅允许 `failed`/`canceled` 状态 |
|
|
717
|
+
| `services.waitingComplete({ id, pollInterval, maxPollTimes })` | 等待任务完成(轮询),返回任务输出数据 |
|
|
515
718
|
|
|
516
719
|
**services.create 参数:**
|
|
517
720
|
|
|
@@ -529,6 +732,7 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
|
|
|
529
732
|
| parentTaskId | string | 否 | - | 父任务ID |
|
|
530
733
|
| maxRetries | number | 否 | `0` | 最大重试次数 |
|
|
531
734
|
| timeout | number | 否 | `3600000` | 超时时间(毫秒) |
|
|
735
|
+
| context | object | 否 | `{}` | 初始上下文 |
|
|
532
736
|
| options | object | 否 | - | 扩展选项 |
|
|
533
737
|
|
|
534
738
|
**services.waitingComplete 参数:**
|
|
@@ -557,7 +761,29 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
|
|
|
557
761
|
| `services.claimPendingTasks(limit)` | 按优先级和开始时间认领待执行系统任务,返回已认领任务列表 |
|
|
558
762
|
| `services.processSystemTask(task, opts)` | 执行系统任务;`opts.claimed` 为 `true` 时跳过重复置为 running |
|
|
559
763
|
| `services.resetAll({ staleOnly, before })` | 重置 running 任务为 pending;`staleOnly` 为 `true` 时只恢复陈旧任务 |
|
|
560
|
-
| `services.append({ dirs, tasks })`
|
|
764
|
+
| `services.append({ name, dir, dirs, scriptName, tasks, override })` | 运行时动态添加任务声明,返回 `{ dirs, tasks, skippedTasks }` |
|
|
765
|
+
|
|
766
|
+
**services.append 参数:**
|
|
767
|
+
|
|
768
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
769
|
+
|-------------|---------|----|----------------|-----------------------------------------|
|
|
770
|
+
| name | string | 否 | `options.name` | 本次 append 注册的任务命名空间,插件包通常传自身 `options.name` |
|
|
771
|
+
| dir | string | 否 | - | 任务脚本目录,等价于单项 `dirs` |
|
|
772
|
+
| dirs | array | 否 | - | 任务脚本目录列表 |
|
|
773
|
+
| scriptName | string | 否 | `'index'` | 本次 append 注册任务的默认脚本名 |
|
|
774
|
+
| tasks | object | 否 | - | 任务声明映射,支持函数简写或对象配置 |
|
|
775
|
+
| override | boolean | 否 | `false` | 是否覆盖已存在的同名任务声明 |
|
|
776
|
+
|
|
777
|
+
**tasks[type] 对象配置:**
|
|
778
|
+
|
|
779
|
+
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|
|
780
|
+
|---------------|----------------|----|-----|-----------------------------------------|
|
|
781
|
+
| handler | function | 否 | - | 任务成功后的处理函数 |
|
|
782
|
+
| errorHandler | function | 否 | - | 当前任务类型自己的错误处理函数 |
|
|
783
|
+
| next | string / array | 否 | - | 成功后创建的下一任务;数组模式从 `output.next` 中选择下一任务 |
|
|
784
|
+
|
|
785
|
+
> **关键设计**:`append.scriptName` 只影响本次 append 注册的任务。未传时固定使用 `index.js`,不会使用主项目注册 task 时的
|
|
786
|
+
> `options.scriptName`。
|
|
561
787
|
|
|
562
788
|
#### 统计查询
|
|
563
789
|
|
|
@@ -641,6 +867,213 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
|
|
|
641
867
|
|
|
642
868
|
### 机制说明
|
|
643
869
|
|
|
870
|
+
#### 任务声明与命名空间
|
|
871
|
+
|
|
872
|
+
任务类型由 task registry 统一维护。主项目注册 task 插件时可以通过 `task` 直接声明任务,插件包可以通过 `services.append` 声明自己的任务。
|
|
873
|
+
|
|
874
|
+
| 来源 | 命名空间 | 可访问任务范围 |
|
|
875
|
+
|----------------|---------------|-----------------------------------------------|
|
|
876
|
+
| 主项目 `task` | `options.name` | 主项目任务、插件任务;插件任务需使用 `{append.name}.任务名` |
|
|
877
|
+
| 插件 `append` | `append.name` | 当前插件任务、其他插件任务;不能访问主项目任务 |
|
|
878
|
+
| `create({type})` | 根据任务名解析 | 无点号时优先主项目任务;跨插件或指定命名空间时使用 `命名空间.任务名` |
|
|
879
|
+
|
|
880
|
+
`append` 注册的任务可以没有 `handler`,只要存在对应执行脚本即可执行。主项目原有的 `{ [type]: handler }` 写法仍然兼容。
|
|
881
|
+
|
|
882
|
+
> **关键设计**:插件内的裸任务名只在当前插件命名空间内解析;跨插件访问必须使用 `包名.任务名`。插件任务不允许访问主项目任务。
|
|
883
|
+
|
|
884
|
+
#### 成功与错误处理
|
|
885
|
+
|
|
886
|
+
任务执行成功后会先调用当前任务声明的 `handler`,再创建 `next` 任务,最后将当前任务更新为 `success` 并采集统计数据。
|
|
887
|
+
|
|
888
|
+
| 阶段 | 行为 |
|
|
889
|
+
|---------|-----------------------------------------|
|
|
890
|
+
| handler | 如果声明了 `handler`,等待它执行完成;未声明则跳过 |
|
|
891
|
+
| next | 如果声明了 `next`,解析并创建下一任务 |
|
|
892
|
+
| success | 更新 `status/output/progress/completedAt` 并采集统计 |
|
|
893
|
+
|
|
894
|
+
任务最终失败时会触发错误处理:
|
|
895
|
+
|
|
896
|
+
| 处理器 | 触发时机 |
|
|
897
|
+
|------------------------|------------------------------|
|
|
898
|
+
| `tasks[type].errorHandler` | 当前任务最终失败时优先调用 |
|
|
899
|
+
| `options.errorHandler` | 未配置任务级错误处理,或任务级错误处理抛错时调用 |
|
|
900
|
+
|
|
901
|
+
> **关键设计**:自动重试期间不会触发最终错误处理;只有任务最终进入 `failed` 状态时才调用错误处理函数。
|
|
902
|
+
|
|
903
|
+
#### next 链式任务
|
|
904
|
+
|
|
905
|
+
`tasks[type].next` 只声明下一任务名称,不声明下一任务的执行参数。
|
|
906
|
+
|
|
907
|
+
| next 配置 | 解析规则 |
|
|
908
|
+
|---------|-----------------------------------------|
|
|
909
|
+
| string | 固定使用该任务名作为下一任务 |
|
|
910
|
+
| array | 从当前任务 `output.next` 读取任务名,并要求它包含在数组中 |
|
|
911
|
+
|
|
912
|
+
下一任务创建规则:
|
|
913
|
+
|
|
914
|
+
| 字段 | 取值 |
|
|
915
|
+
|--------------|---------------------------------------------------|
|
|
916
|
+
| `type` | 解析后的下一任务声明类型 |
|
|
917
|
+
| `input` | 当前任务 `output`,并将 `input.name` 设为当前任务 `input.name` |
|
|
918
|
+
| `targetType` | 固定为 `task` |
|
|
919
|
+
| `targetId` | 当前任务 id |
|
|
920
|
+
| `parentTaskId` | 当前任务 id |
|
|
921
|
+
| `context` | 当前任务 `context` 的深拷贝 |
|
|
922
|
+
| `runnerType` | 当前任务 `runnerType` |
|
|
923
|
+
|
|
924
|
+
如果 `next` 是数组且 `output.next` 缺失,或 `output.next` 不在允许列表中,当前任务会转为 `failed`。
|
|
925
|
+
|
|
926
|
+
**业务示例:会议录像处理**
|
|
927
|
+
|
|
928
|
+
会议结束后先执行 `record-video` 获取录像文件。脚本根据录像结果决定下一步:需要转码时进入 `transcode-video`,否则直接进入 `save-video`。
|
|
929
|
+
|
|
930
|
+
```js
|
|
931
|
+
await fastify.task.services.append({
|
|
932
|
+
name: 'trtcConference',
|
|
933
|
+
dir: path.resolve(__dirname, './libs/tasks'),
|
|
934
|
+
tasks: {
|
|
935
|
+
'record-video': {
|
|
936
|
+
handler: async ({ task, result }) => {
|
|
937
|
+
await fastify.trtcConference.services.saveRecordMeta(result);
|
|
938
|
+
},
|
|
939
|
+
next: ['transcode-video', 'save-video']
|
|
940
|
+
},
|
|
941
|
+
'transcode-video': {
|
|
942
|
+
next: 'save-video'
|
|
943
|
+
},
|
|
944
|
+
'save-video': {
|
|
945
|
+
handler: async ({ result }) => {
|
|
946
|
+
await fastify.trtcConference.services.saveRecordVideo(result);
|
|
947
|
+
}
|
|
948
|
+
}
|
|
949
|
+
}
|
|
950
|
+
});
|
|
951
|
+
```
|
|
952
|
+
|
|
953
|
+
`record-video/index.js` 返回 `output.next` 指定下一任务:
|
|
954
|
+
|
|
955
|
+
```js
|
|
956
|
+
module.exports = async (fastify, options, { task }) => {
|
|
957
|
+
const record = await fastify.trtc.services.checkRecord(task.input);
|
|
958
|
+
return {
|
|
959
|
+
name: task.input.name,
|
|
960
|
+
fileId: record.fileId,
|
|
961
|
+
fileUrl: record.fileUrl,
|
|
962
|
+
next: record.needTranscode ? 'transcode-video' : 'save-video'
|
|
963
|
+
};
|
|
964
|
+
};
|
|
965
|
+
```
|
|
966
|
+
|
|
967
|
+
当 `output.next` 为 `transcode-video` 时,会创建 `trtcConference.transcode-video`;当它为 `save-video` 时,会创建
|
|
968
|
+
`trtcConference.save-video`。下一任务的 `input` 使用当前任务完整 `output`,并复制当前任务 `context`。
|
|
969
|
+
|
|
970
|
+
**业务示例:多级审批**
|
|
971
|
+
|
|
972
|
+
合同审批需要依次经过部门主管、财务和法务。每一级审批任务只处理当前节点,并把审批轨迹写入 `context.approvals`。下一任务创建时会复制当前
|
|
973
|
+
`context`,因此后续节点可以看到前面所有审批记录。
|
|
974
|
+
|
|
975
|
+
```js
|
|
976
|
+
await fastify.task.services.append({
|
|
977
|
+
name: 'contractApproval',
|
|
978
|
+
dir: path.resolve(__dirname, './libs/tasks'),
|
|
979
|
+
tasks: {
|
|
980
|
+
'manager-approval': {
|
|
981
|
+
next: 'finance-approval'
|
|
982
|
+
},
|
|
983
|
+
'finance-approval': {
|
|
984
|
+
next: ['legal-approval', 'archive-contract']
|
|
985
|
+
},
|
|
986
|
+
'legal-approval': {
|
|
987
|
+
next: 'archive-contract'
|
|
988
|
+
},
|
|
989
|
+
'archive-contract': {
|
|
990
|
+
handler: async ({ task, context }) => {
|
|
991
|
+
await fastify.contract.services.archive({
|
|
992
|
+
contractId: task.input.contractId,
|
|
993
|
+
approvals: context.approvals
|
|
994
|
+
});
|
|
995
|
+
}
|
|
996
|
+
}
|
|
997
|
+
}
|
|
998
|
+
});
|
|
999
|
+
```
|
|
1000
|
+
|
|
1001
|
+
创建第一个审批任务时写入初始上下文:
|
|
1002
|
+
|
|
1003
|
+
```js
|
|
1004
|
+
await fastify.task.services.create({
|
|
1005
|
+
type: 'contractApproval.manager-approval',
|
|
1006
|
+
targetType: 'contract',
|
|
1007
|
+
targetId: contract.id,
|
|
1008
|
+
runnerType: 'system',
|
|
1009
|
+
input: {
|
|
1010
|
+
name: contract.name,
|
|
1011
|
+
contractId: contract.id,
|
|
1012
|
+
amount: contract.amount
|
|
1013
|
+
},
|
|
1014
|
+
context: {
|
|
1015
|
+
requestId: contract.requestId,
|
|
1016
|
+
approvals: []
|
|
1017
|
+
}
|
|
1018
|
+
});
|
|
1019
|
+
```
|
|
1020
|
+
|
|
1021
|
+
`manager-approval/index.js` 更新当前任务的 `context`:
|
|
1022
|
+
|
|
1023
|
+
```js
|
|
1024
|
+
module.exports = async (fastify, options, { task }) => {
|
|
1025
|
+
const approvals = [...(task.context.approvals || []), {
|
|
1026
|
+
node: 'manager',
|
|
1027
|
+
approver: 'u-manager-1',
|
|
1028
|
+
result: 'approved',
|
|
1029
|
+
time: new Date().toISOString()
|
|
1030
|
+
}];
|
|
1031
|
+
|
|
1032
|
+
await task.update({
|
|
1033
|
+
context: {
|
|
1034
|
+
...task.context,
|
|
1035
|
+
approvals
|
|
1036
|
+
}
|
|
1037
|
+
});
|
|
1038
|
+
|
|
1039
|
+
return {
|
|
1040
|
+
name: task.input.name,
|
|
1041
|
+
contractId: task.input.contractId,
|
|
1042
|
+
amount: task.input.amount
|
|
1043
|
+
};
|
|
1044
|
+
};
|
|
1045
|
+
```
|
|
1046
|
+
|
|
1047
|
+
`finance-approval/index.js` 可以根据金额动态决定是否进入法务审批:
|
|
1048
|
+
|
|
1049
|
+
```js
|
|
1050
|
+
module.exports = async (fastify, options, { task }) => {
|
|
1051
|
+
const approvals = [...(task.context.approvals || []), {
|
|
1052
|
+
node: 'finance',
|
|
1053
|
+
approver: 'u-finance-1',
|
|
1054
|
+
result: 'approved',
|
|
1055
|
+
time: new Date().toISOString()
|
|
1056
|
+
}];
|
|
1057
|
+
|
|
1058
|
+
await task.update({
|
|
1059
|
+
context: {
|
|
1060
|
+
...task.context,
|
|
1061
|
+
approvals
|
|
1062
|
+
}
|
|
1063
|
+
});
|
|
1064
|
+
|
|
1065
|
+
return {
|
|
1066
|
+
name: task.input.name,
|
|
1067
|
+
contractId: task.input.contractId,
|
|
1068
|
+
amount: task.input.amount,
|
|
1069
|
+
next: task.input.amount > 100000 ? 'legal-approval' : 'archive-contract'
|
|
1070
|
+
};
|
|
1071
|
+
};
|
|
1072
|
+
```
|
|
1073
|
+
|
|
1074
|
+
在这个流程中,`finance-approval` 会拿到主管审批后复制过来的 `context.approvals`;`legal-approval` 或 `archive-contract`
|
|
1075
|
+
也会继续拿到财务审批后更新过的 `context`。每次创建下一任务都会深拷贝当前任务完成时的 `context`,不会和上一任务共享同一个对象引用。
|
|
1076
|
+
|
|
644
1077
|
#### 签名验证
|
|
645
1078
|
|
|
646
1079
|
使用 HMAC-SHA256 算法,签名数据格式为 `{id}|{data}`,其中 `data` 为 JSON 字符串或原始字符串。
|
package/index.js
CHANGED