@kne/fastify-task 3.0.0-alpha.1 → 3.0.0-alpha.10
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 +1052 -255
- package/index.js +14 -4
- package/libs/controllers/main.js +4 -3
- package/libs/helpers/task-service-context.js +556 -0
- package/libs/models/task.js +6 -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 -674
- package/libs/services/scheduler.js +230 -0
- package/libs/services/statistics.js +614 -38
- package/libs/services/task.js +224 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -12,46 +12,415 @@ npm i --save @kne/fastify-task
|
|
|
12
12
|
|
|
13
13
|
### 概述
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
`@kne/fastify-task` 是一个 Fastify 插件,用于任务编排、执行状态追踪、结果回调、日志记录和统计分析。插件支持 **system 自动执行
|
|
16
|
+
** 与 **manual 手动完成** 两种模式,适合处理导出、同步、通知、外部异步回调等后台任务场景。
|
|
17
|
+
|
|
18
|
+
### 核心架构与流程
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
创建任务 (services.create)
|
|
22
|
+
↓
|
|
23
|
+
pending(待执行)
|
|
24
|
+
├→ manual:services.complete → success / failed
|
|
25
|
+
└→ system:cron 触发 runner
|
|
26
|
+
↓
|
|
27
|
+
checkTimeout(检测 running / waiting 超时任务)
|
|
28
|
+
↓
|
|
29
|
+
claimPendingTasks(按优先级与 startTime 原子认领)
|
|
30
|
+
↓
|
|
31
|
+
running(执行中)
|
|
32
|
+
├→ executor 正常完成 → handler → next task → success
|
|
33
|
+
├→ executor 调用 next() → waiting
|
|
34
|
+
├→ executor 异常 → retry / failed
|
|
35
|
+
└→ waiting → processNext / callbackWithSignature → handler → next task → success / failed
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
| 节点 | 说明 |
|
|
39
|
+
|-------------------------|-----------------------------------------------------|
|
|
40
|
+
| `checkTimeout` | 每次调度前检测 `running` / `waiting` 中已超过任务级 `timeout` 的任务 |
|
|
41
|
+
| `claimPendingTasks` | 使用带状态条件的更新将 `pending` 原子认领为 `running`,避免多实例重复执行 |
|
|
42
|
+
| `processSystemTask` | 执行任务脚本,并根据结果、异常、重试次数和回调状态更新任务 |
|
|
43
|
+
| `collectTaskStatistics` | 任务进入终态后采集数量和耗时指标 |
|
|
44
|
+
| `taskRegistry` | 维护主项目与插件通过 `append` 注册的任务声明、脚本目录和生命周期钩子 |
|
|
45
|
+
|
|
46
|
+
> **关键设计**:cron 每次触发 `runner` 时先检测超时任务,再按 **优先级降序 + startTime 升序** 认领待执行系统任务。认领通过条件更新完成,只有仍处于
|
|
47
|
+
`pending` 的任务会被当前实例执行。
|
|
48
|
+
|
|
49
|
+
### 核心概念详解
|
|
50
|
+
|
|
51
|
+
#### 任务状态
|
|
52
|
+
|
|
53
|
+
| 状态 | 说明 | 可流转到 |
|
|
54
|
+
|------------|--------|--------------------------------------------|
|
|
55
|
+
| `pending` | 待执行 | `running`、`canceled` |
|
|
56
|
+
| `running` | 执行中 | `success`、`failed`、`waiting`、`pending`(重试) |
|
|
57
|
+
| `waiting` | 等待外部回调 | `success`、`failed` |
|
|
58
|
+
| `success` | 执行成功 | 终态 |
|
|
59
|
+
| `failed` | 执行失败 | `pending`(重试) |
|
|
60
|
+
| `canceled` | 已取消 | `pending`(重试) |
|
|
61
|
+
|
|
62
|
+
#### 执行模式
|
|
63
|
+
|
|
64
|
+
| 模式 | runnerType | 触发方式 | 说明 |
|
|
65
|
+
|------|------------|----------------------|----------------------|
|
|
66
|
+
| 系统自动 | `system` | cron 定时调度 `runner` | 按优先级和 startTime 自动执行 |
|
|
67
|
+
| 手动执行 | `manual` | 用户通过 `complete` 接口完成 | 任务创建后等待人工操作 |
|
|
68
|
+
|
|
69
|
+
#### 调度与恢复
|
|
70
|
+
|
|
71
|
+
| 机制 | 触发时机 | 说明 |
|
|
72
|
+
|------|--------------------------|-------------------------------------------------------------------|
|
|
73
|
+
| 并发上限 | 每次 `runner()` 执行 | 当前 `running` 系统任务数达到 `limit` 时不再认领新任务 |
|
|
74
|
+
| 原子认领 | 查询到候选 `pending` 任务后 | 通过 `id + runnerType + status + startTime` 条件更新为 `running`,认领失败则跳过 |
|
|
75
|
+
| 启动恢复 | Fastify `onReady` | 默认只将超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务恢复为 `pending` |
|
|
76
|
+
| 手动重置 | 调用 `services.resetAll()` | 不传 `staleOnly` 时会将所有 `running` 任务重置为 `pending` |
|
|
16
77
|
|
|
17
78
|
### 主要特性
|
|
18
79
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
80
|
+
| 特性 | 说明 |
|
|
81
|
+
|---------|-------------------------------------------|
|
|
82
|
+
| 任务创建与管理 | 支持创建、取消、重试、完成任务 |
|
|
83
|
+
| 多种执行模式 | system 自动执行 / manual 手动执行 |
|
|
84
|
+
| 定时任务调度 | 基于 cron 表达式定时执行系统任务 |
|
|
85
|
+
| 任务状态追踪 | 实时追踪进度、轮询结果 |
|
|
86
|
+
| 异步回调支持 | 支持 `next` → `processNext`/`callback` 回调链路 |
|
|
87
|
+
| 日志记录 | 任务执行日志,最多保留 100 条 |
|
|
88
|
+
| 优先级与依赖 | 优先级排序 + 父子任务链式执行 |
|
|
89
|
+
| 自动重试 | 指数退避重试策略 |
|
|
90
|
+
| 超时控制 | 全局执行超时和任务级超时均使用毫秒,超时自动标记 failed |
|
|
91
|
+
| 多实例调度 | 待执行任务通过原子认领进入 running,降低重复执行风险 |
|
|
92
|
+
| 插件任务注册 | 插件可通过 `append` 注册自己的任务目录、脚本名、处理函数和错误处理 |
|
|
93
|
+
| 链式任务 | 支持通过 `next` 声明后续任务,按当前输出创建下一任务 |
|
|
94
|
+
| 统计面板 | 任务统计数据查询 + SSE 实时推送 |
|
|
95
|
+
|
|
96
|
+
### 使用方法
|
|
97
|
+
|
|
98
|
+
#### 插件注册与配置
|
|
99
|
+
|
|
100
|
+
```js
|
|
101
|
+
// 基础注册
|
|
102
|
+
const fastify = require('fastify')();
|
|
103
|
+
fastify.register(require('@kne/fastify-task'), {
|
|
104
|
+
// 可选配置项,参见 api.md 配置项章节
|
|
105
|
+
});
|
|
106
|
+
```
|
|
25
107
|
|
|
26
|
-
|
|
108
|
+
```js
|
|
109
|
+
// 带任务类型处理函数的注册
|
|
110
|
+
fastify.register(require('@kne/fastify-task'), {
|
|
111
|
+
task: {
|
|
112
|
+
'export-excel': async ({ task, result, context }) => {
|
|
113
|
+
console.log('导出任务完成:', result);
|
|
114
|
+
},
|
|
115
|
+
'send-email': {
|
|
116
|
+
handler: async ({ task, result }) => {
|
|
117
|
+
// 发送邮件完成后的处理
|
|
118
|
+
},
|
|
119
|
+
errorHandler: async ({ task, error }) => {
|
|
120
|
+
// 可选:当前任务类型自己的错误处理
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
});
|
|
125
|
+
```
|
|
27
126
|
|
|
28
|
-
|
|
29
|
-
- 第三方 API 调用后异步回调处理
|
|
30
|
-
- 定时批量数据处理
|
|
31
|
-
- 需要追踪进度和状态的长时任务
|
|
127
|
+
#### 任务声明与命名空间
|
|
32
128
|
|
|
33
|
-
|
|
129
|
+
任务类型可以由主项目注册时的 `task` 配置声明,也可以由其他插件通过 `append` 动态声明。声明对象支持 `handler`、`errorHandler` 和
|
|
130
|
+
`next`,其中 `handler` 可省略;只要任务类型已经声明并存在对应执行脚本,就可以创建和执行任务。
|
|
34
131
|
|
|
35
|
-
|
|
|
36
|
-
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
| waiting | 等待外部回调 |
|
|
40
|
-
| success | 执行成功 |
|
|
41
|
-
| failed | 执行失败 |
|
|
42
|
-
| canceled | 已取消 |
|
|
132
|
+
| 声明来源 | 默认命名空间 | 任务名解析规则 |
|
|
133
|
+
|------------|--------------|-----------------------------------------------|
|
|
134
|
+
| 主项目 `task` | `options.name` | 可直接使用本地任务名,也可使用 `{options.name}.任务名` |
|
|
135
|
+
| 插件 `append` | `append.name` | 本地任务名只在当前插件内查找,跨插件使用 `{append.name}.任务名` |
|
|
43
136
|
|
|
44
|
-
|
|
137
|
+
> **关键设计**:插件任务不能访问主项目中的任务。插件内的裸任务名只解析到当前插件命名空间,跨插件访问必须使用 `包名.任务名`。
|
|
45
138
|
|
|
46
|
-
|
|
139
|
+
#### 任务脚本开发
|
|
47
140
|
|
|
48
|
-
|
|
141
|
+
在 `dirs` 配置的目录下创建任务脚本,目录结构:
|
|
49
142
|
|
|
50
|
-
```
|
|
143
|
+
```
|
|
144
|
+
libs/tasks/
|
|
145
|
+
└── <任务类型>/
|
|
146
|
+
└── <scriptName>.js # 默认 scriptName 为 'index'
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
**脚本模板:**
|
|
150
|
+
|
|
151
|
+
```js
|
|
152
|
+
module.exports = async (fastify, options, { task, updateProgress, polling, next, log }) => {
|
|
153
|
+
const { input } = task;
|
|
154
|
+
|
|
155
|
+
// 更新进度 (0-100)
|
|
156
|
+
await updateProgress(50);
|
|
157
|
+
|
|
158
|
+
// 轮询外部服务
|
|
159
|
+
const result = await polling(async () => {
|
|
160
|
+
const res = await fetch('external-api');
|
|
161
|
+
return {
|
|
162
|
+
result: 'success | failed | pending',
|
|
163
|
+
data: res.data,
|
|
164
|
+
message: '消息',
|
|
165
|
+
progress: 80
|
|
166
|
+
};
|
|
167
|
+
}, {
|
|
168
|
+
maxPollTimes: 20,
|
|
169
|
+
pollInterval: 10000
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
// 等待外部回调(任务状态变为 waiting)
|
|
173
|
+
await next({
|
|
174
|
+
secret: '签名密钥',
|
|
175
|
+
// 其他上下文数据,回调时可在 context 中获取
|
|
176
|
+
});
|
|
177
|
+
|
|
178
|
+
return { /* 返回结果 */ };
|
|
179
|
+
};
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
#### executor 辅助方法
|
|
183
|
+
|
|
184
|
+
| 方法签名 | 说明 |
|
|
185
|
+
|------------------------------|----------------------------------|
|
|
186
|
+
| `updateProgress(progress)` | 更新任务进度 (0-100) |
|
|
187
|
+
| `polling(callback, options)` | 轮询外部服务直到完成 |
|
|
188
|
+
| `next(context)` | 设置任务为 waiting 状态,返回 `false` 暂停执行 |
|
|
189
|
+
| `log({ data, message })` | 记录任务执行日志 |
|
|
190
|
+
|
|
191
|
+
**polling options 参数:**
|
|
192
|
+
|
|
193
|
+
| 参数名 | 类型 | 默认值 | 说明 |
|
|
194
|
+
|----------------|--------|---------|----------|
|
|
195
|
+
| `maxPollTimes` | number | `20` | 最大轮询次数 |
|
|
196
|
+
| `pollInterval` | number | `10000` | 轮询间隔(毫秒) |
|
|
197
|
+
|
|
198
|
+
**polling callback 返回格式:**
|
|
199
|
+
|
|
200
|
+
| 字段 | 类型 | 说明 |
|
|
201
|
+
|------------|--------|----------------------------------------|
|
|
202
|
+
| `result` | string | `'success'` / `'failed'` / `'pending'` |
|
|
203
|
+
| `data` | object | 成功时返回的数据 |
|
|
204
|
+
| `message` | string | 消息 |
|
|
205
|
+
| `progress` | number | 当前进度 |
|
|
206
|
+
|
|
207
|
+
#### 任务类型处理函数
|
|
208
|
+
|
|
209
|
+
任务成功后如果配置了 `handler`,会自动调用对应处理函数;未配置时直接进入成功收尾。处理函数接收参数:
|
|
210
|
+
|
|
211
|
+
| 参数名 | 类型 | 说明 |
|
|
212
|
+
|-----------|-----------------|----------------------|
|
|
213
|
+
| `task` | Task | 任务实例 |
|
|
214
|
+
| `result` | object / string | 任务输出结果 |
|
|
215
|
+
| `context` | object | 任务上下文(`next` 时设置的数据) |
|
|
216
|
+
|
|
217
|
+
#### 错误处理函数
|
|
218
|
+
|
|
219
|
+
任务最终失败时优先调用任务声明中的 `errorHandler`;未配置时调用全局 `errorHandler`。如果任务级 `errorHandler` 抛出异常,仍会继续交给全局
|
|
220
|
+
`errorHandler` 处理。
|
|
221
|
+
|
|
222
|
+
| 处理器 | 触发条件 | 说明 |
|
|
223
|
+
|------------------------|---------------|----------------------------|
|
|
224
|
+
| `tasks[type].errorHandler` | 当前任务最终失败 | 当前任务类型自己的错误处理,优先级最高 |
|
|
225
|
+
| `options.errorHandler` | 未配置任务级处理或任务级处理抛错 | 全局兜底错误处理,不改变任务最终失败状态 |
|
|
226
|
+
|
|
227
|
+
#### 运行时动态添加
|
|
228
|
+
|
|
229
|
+
```js
|
|
230
|
+
// 插件包通过 append 方法运行时添加任务目录和类型
|
|
231
|
+
const result = await fastify.task.services.append({
|
|
232
|
+
name: 'trtcConference',
|
|
233
|
+
dir: '/path/to/tasks',
|
|
234
|
+
scriptName: 'index',
|
|
235
|
+
tasks: {
|
|
236
|
+
'record-video': {
|
|
237
|
+
handler: async ({ task, result }) => {
|
|
238
|
+
// 可选:任务成功后的处理逻辑
|
|
239
|
+
},
|
|
240
|
+
errorHandler: async ({ task, error }) => {
|
|
241
|
+
// 可选:任务失败后的处理逻辑
|
|
242
|
+
},
|
|
243
|
+
next: ['transcode-video', 'analyze-video']
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
});
|
|
247
|
+
// result.dirs → 实际添加的目录列表
|
|
248
|
+
// result.tasks → 实际添加的类型列表
|
|
249
|
+
```
|
|
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
|
+
|
|
414
|
+
#### 签名验证
|
|
415
|
+
|
|
416
|
+
当任务通过 `next({ secret: '密钥' })` 设置了密钥时,外部回调需提供 HMAC-SHA256 签名。
|
|
417
|
+
|
|
418
|
+
**签名生成方法:**
|
|
419
|
+
|
|
420
|
+
```js
|
|
51
421
|
const crypto = require('node:crypto');
|
|
52
422
|
|
|
53
423
|
function generateSignature({ secret, id, data }) {
|
|
54
|
-
// data 可以是字符串或对象
|
|
55
424
|
const dataStr = typeof data === 'string' ? data : JSON.stringify(data);
|
|
56
425
|
const dataToSign = `${id}|${dataStr}`;
|
|
57
426
|
const hmac = crypto.createHmac('sha256', secret);
|
|
@@ -60,289 +429,717 @@ function generateSignature({ secret, id, data }) {
|
|
|
60
429
|
}
|
|
61
430
|
```
|
|
62
431
|
|
|
63
|
-
|
|
432
|
+
**各接口签名数据格式:**
|
|
64
433
|
|
|
65
|
-
| 接口
|
|
66
|
-
|
|
67
|
-
| processNext
|
|
68
|
-
| logWithSignature
|
|
69
|
-
| callbackWithSignature| `{ code, data, message }` 对象
|
|
434
|
+
| 接口 | data 格式 |
|
|
435
|
+
|-------------------------|------------------------------|
|
|
436
|
+
| `processNext` | `result` 字符串(JSON 格式结果) |
|
|
437
|
+
| `logWithSignature` | `{ data, message }` 对象 |
|
|
438
|
+
| `callbackWithSignature` | `{ code, data, message }` 对象 |
|
|
70
439
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
```javascript
|
|
440
|
+
```js
|
|
74
441
|
// processNext 签名
|
|
75
442
|
const result = JSON.stringify({ code: 0, data: { output: 'done' } });
|
|
76
443
|
const signature = generateSignature({ secret: 'your-secret', id: 'task-1', data: result });
|
|
77
444
|
|
|
78
|
-
// logWithSignature 签名
|
|
79
|
-
const signature = generateSignature({
|
|
80
|
-
secret: 'your-secret',
|
|
81
|
-
id: 'task-1',
|
|
82
|
-
data: { data: { key: 'value' }, message: '日志消息' }
|
|
83
|
-
});
|
|
84
|
-
|
|
85
445
|
// callbackWithSignature 签名
|
|
86
446
|
const signature = generateSignature({
|
|
87
|
-
secret: 'your-secret',
|
|
88
|
-
id: 'task-1',
|
|
447
|
+
secret: 'your-secret', id: 'task-1',
|
|
89
448
|
data: { code: 0, data: { result: 'done' }, message: '成功' }
|
|
90
449
|
});
|
|
91
450
|
```
|
|
92
451
|
|
|
93
|
-
|
|
452
|
+
> **关键设计**:未设置 `context.secret` 时签名验证自动跳过,不阻塞无密钥任务的回调。
|
|
94
453
|
|
|
95
|
-
|
|
454
|
+
#### 插件依赖
|
|
96
455
|
|
|
97
|
-
|
|
456
|
+
| 依赖 | 说明 |
|
|
457
|
+
|---------------------------|---------|
|
|
458
|
+
| `fastify-cron` | 定时任务支持 |
|
|
459
|
+
| `@kne/fastify-namespace` | 命名空间模块化 |
|
|
460
|
+
| `@kne/fastify-statistics` | 统计数据采集 |
|
|
461
|
+
| `fastify-sequelize` | 数据库模型支持 |
|
|
98
462
|
|
|
99
|
-
| 属性名 | 类型 | 默认值 | 说明 |
|
|
100
|
-
|-------------------|----------|----------------|----------------------|
|
|
101
|
-
| dbTableNamePrefix | string | 't_' | 数据库表名前缀 |
|
|
102
|
-
| prefix | string | '/api/task' | API 路由前缀 |
|
|
103
|
-
| name | string | 'task' | 命名空间名称 |
|
|
104
|
-
| limit | number | 10 | 并发执行任务数上限 |
|
|
105
|
-
| dir | string | 'libs/tasks' | 任务脚本目录 |
|
|
106
|
-
| cronTime | string | '*/10 * * * *' | cron 执行周期,设为 null 禁用 |
|
|
107
|
-
| scriptName | string | 'index' | 默认任务脚本名称 |
|
|
108
|
-
| maxPollTimes | number | 20 | 最大轮询次数 |
|
|
109
|
-
| pollInterval | number | 10000 | 轮询间隔(毫秒) |
|
|
110
|
-
| getUserModel | function | - | 获取用户模型的函数 |
|
|
111
|
-
| getAuthenticate | function | - | 获取认证中间件的函数 |
|
|
112
|
-
| task | object | {} | 任务类型处理函数映射 |
|
|
113
463
|
|
|
114
|
-
###
|
|
464
|
+
### 示例
|
|
115
465
|
|
|
116
|
-
|
|
466
|
+
### API
|
|
117
467
|
|
|
118
|
-
|
|
468
|
+
### 配置项
|
|
469
|
+
|
|
470
|
+
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|
|
471
|
+
|------------------------------|---------------|----|------------------|--------------------------------------------------------------------------------|
|
|
472
|
+
| `dbTableNamePrefix` | string | 否 | `'t_'` | 数据库表名前缀 |
|
|
473
|
+
| `prefix` | string | 否 | `'/api/task'` | API 路由前缀 |
|
|
474
|
+
| `name` | string | 否 | `'task'` | 插件命名空间名称 |
|
|
475
|
+
| `limit` | number | 否 | `10` | 系统任务并发执行上限 |
|
|
476
|
+
| `dir` | string | 否 | `'libs/tasks'` | 任务脚本目录(向后兼容,优先级高于 dirs) |
|
|
477
|
+
| `dirs` | array | 否 | `null` | 任务脚本目录列表,运行时可通过 `append` 动态添加 |
|
|
478
|
+
| `cronTime` | string | 否 | `'*/10 * * * *'` | 定时任务 Cron 表达式 |
|
|
479
|
+
| `scriptName` | string | 否 | `'index'` | 默认任务脚本名称 |
|
|
480
|
+
| `maxPollTimes` | number | 否 | `20` | 最大轮询次数 |
|
|
481
|
+
| `pollInterval` | number | 否 | `10000` | 轮询间隔(毫秒) |
|
|
482
|
+
| `taskTimeout` | number | 否 | `1800000` | 任务执行超时时间(毫秒),0 表示不超时 |
|
|
483
|
+
| `recoverRunningTaskAfter` | number / null | 否 | `null` | 启动恢复 running 任务的陈旧阈值(毫秒);未传时使用 `taskTimeout`,若 `taskTimeout` 为 0 则使用 `1800000` |
|
|
484
|
+
| `recoverRunningTasksOnStart` | boolean | 否 | `true` | 启动时是否恢复陈旧 running 任务 |
|
|
485
|
+
| `retryBaseDelay` | number | 否 | `5000` | 重试基础延迟(毫秒),实际延迟 = `retryBaseDelay * 2^(retryCount-1)` |
|
|
486
|
+
| `errorHandler` | function | 否 | - | 全局错误处理函数,任务级 `errorHandler` 未配置或抛错时调用 |
|
|
487
|
+
| `getUserModel` | function | 否 | - | 获取用户 Model 的函数 |
|
|
488
|
+
| `getAuthenticate` | function | 否 | - | 获取认证中间件的函数 |
|
|
489
|
+
| `task` | object | 否 | `{}` | 主项目任务声明,支持 `{ [type]: handler }` 或 `{ [type]: { handler, errorHandler, next } }` |
|
|
490
|
+
|
|
491
|
+
> **关键设计**:`dirs` 初始化逻辑 — 优先使用用户传入的 `dirs`,否则以 `dir` 为默认值;若 `dirs` 中不包含 `dir`,则将 `dir`
|
|
492
|
+
> 插入 `dirs` 首位,保证向后兼容。
|
|
493
|
+
|
|
494
|
+
> **关键设计**:`recoverRunningTasksOnStart` 只恢复陈旧 `running` 任务,避免多实例部署时某个实例重启误重置其他实例正在执行的任务。
|
|
495
|
+
|
|
496
|
+
### HTTP 接口
|
|
497
|
+
|
|
498
|
+
#### POST `{prefix}/create`
|
|
499
|
+
|
|
500
|
+
创建任务,需 `write` 权限。
|
|
501
|
+
|
|
502
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
503
|
+
|--------------|--------|----|-----------|---------------------------|
|
|
504
|
+
| type | string | 是 | - | 任务类型,必须已在主项目或 `append` 中声明 |
|
|
505
|
+
| targetId | string | 是 | - | 目标对象ID |
|
|
506
|
+
| targetType | string | 是 | - | 目标对象类型 |
|
|
507
|
+
| input | object | 否 | - | 输入数据 |
|
|
508
|
+
| runnerType | string | 否 | - | 执行者类型:`manual` / `system` |
|
|
509
|
+
| delay | number | 否 | `0` | 延迟执行秒数 |
|
|
510
|
+
| scriptName | string | 否 | - | 任务脚本名称 |
|
|
511
|
+
| priority | number | 否 | `0` | 优先级,数值越大越优先 |
|
|
512
|
+
| parentTaskId | string | 否 | - | 父任务ID,用于任务依赖 |
|
|
513
|
+
| maxRetries | number | 否 | `0` | 最大自动重试次数 |
|
|
514
|
+
| timeout | number | 否 | `3600000` | 任务超时时间(毫秒),0 表示不超时 |
|
|
515
|
+
| context | object | 否 | `{}` | 初始上下文,用于回调签名、日志或链式任务传递 |
|
|
516
|
+
|
|
517
|
+
返回值:
|
|
518
|
+
|
|
519
|
+
```json
|
|
520
|
+
{
|
|
521
|
+
"id": "task-1"
|
|
522
|
+
}
|
|
523
|
+
```
|
|
119
524
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
|
125
|
-
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
| filter.
|
|
129
|
-
| filter.
|
|
130
|
-
| filter.
|
|
131
|
-
| filter.
|
|
132
|
-
| filter.
|
|
133
|
-
| filter.
|
|
134
|
-
|
|
|
525
|
+
#### GET `{prefix}/list`
|
|
526
|
+
|
|
527
|
+
获取任务列表,需 `read` 权限。
|
|
528
|
+
|
|
529
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
530
|
+
|------------------------------|--------|----|------|-----------------------------------------------------|
|
|
531
|
+
| perPage | number | 否 | `20` | 每页数量 |
|
|
532
|
+
| currentPage | number | 否 | `1` | 当前页码 |
|
|
533
|
+
| filter.id | string | 否 | - | 任务ID |
|
|
534
|
+
| filter.targetId | string | 否 | - | 目标对象ID |
|
|
535
|
+
| filter.type | string | 否 | - | 任务类型 |
|
|
536
|
+
| filter.status | string | 否 | - | 任务状态 |
|
|
537
|
+
| filter.runnerType | string | 否 | - | 执行者类型 |
|
|
538
|
+
| filter.createdAt.startTime | string | 否 | - | 创建时间起始 |
|
|
539
|
+
| filter.createdAt.endTime | string | 否 | - | 创建时间结束 |
|
|
540
|
+
| filter.completedAt.startTime | string | 否 | - | 完成时间起始 |
|
|
541
|
+
| filter.completedAt.endTime | string | 否 | - | 完成时间结束 |
|
|
542
|
+
| sort | object | 否 | - | 排序规则(支持 `completedAt`、`updatedAt` 等字段,`ASC`/`DESC`) |
|
|
543
|
+
|
|
544
|
+
返回值:
|
|
545
|
+
|
|
546
|
+
```json
|
|
547
|
+
{
|
|
548
|
+
"pageData": [],
|
|
549
|
+
"totalCount": 0
|
|
550
|
+
}
|
|
551
|
+
```
|
|
135
552
|
|
|
136
|
-
|
|
553
|
+
#### POST `{prefix}/complete`
|
|
137
554
|
|
|
138
|
-
|
|
139
|
-
|------------|--------|------|
|
|
140
|
-
| pageData | array | 任务列表 |
|
|
141
|
-
| totalCount | number | 总数量 |
|
|
555
|
+
手动完成任务,需 `write` 权限。
|
|
142
556
|
|
|
143
|
-
|
|
557
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
558
|
+
|--------|--------|----|---------------------------|
|
|
559
|
+
| id | string | 是 | 任务ID |
|
|
560
|
+
| status | string | 是 | 完成状态:`success` / `failed` |
|
|
561
|
+
| error | string | 否 | 错误信息 |
|
|
562
|
+
| msg | string | 否 | 消息 |
|
|
563
|
+
| output | object | 否 | 输出数据 |
|
|
144
564
|
|
|
145
|
-
|
|
565
|
+
返回空对象:
|
|
146
566
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
| status | string | 是 | 状态:success/failed |
|
|
151
|
-
| error | string | 否 | 错误信息 |
|
|
152
|
-
| msg | string | 否 | 消息 |
|
|
153
|
-
| output | object | 否 | 输出数据 |
|
|
567
|
+
```json
|
|
568
|
+
{}
|
|
569
|
+
```
|
|
154
570
|
|
|
155
|
-
####
|
|
571
|
+
#### POST `{prefix}/cancel`
|
|
156
572
|
|
|
157
|
-
|
|
573
|
+
取消任务,需 `write` 权限。支持单个取消(`id`)或批量取消(`targetId` + `targetType` + `type`)。
|
|
158
574
|
|
|
159
|
-
| 参数名
|
|
160
|
-
|
|
161
|
-
| id
|
|
575
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
576
|
+
|------------|--------|----|----------------------------------------|
|
|
577
|
+
| id | string | 否 | 任务ID(单个取消) |
|
|
578
|
+
| targetId | string | 否 | 目标对象ID(批量取消,需配合 `targetType` 和 `type`) |
|
|
579
|
+
| targetType | string | 否 | 目标对象类型(批量取消) |
|
|
580
|
+
| type | string | 否 | 任务类型(批量取消) |
|
|
581
|
+
|
|
582
|
+
返回空对象:
|
|
583
|
+
|
|
584
|
+
```json
|
|
585
|
+
{}
|
|
586
|
+
```
|
|
162
587
|
|
|
163
|
-
####
|
|
588
|
+
#### POST `{prefix}/retry`
|
|
164
589
|
|
|
165
|
-
|
|
590
|
+
重试任务,需 `write` 权限。仅允许重试 `failed` 或 `canceled` 状态的任务。
|
|
166
591
|
|
|
167
592
|
| 参数名 | 类型 | 必填 | 说明 |
|
|
168
593
|
|---------|----------|----|--------|
|
|
169
594
|
| id | string | 否 | 单个任务ID |
|
|
170
|
-
| taskIds |
|
|
595
|
+
| taskIds | array | 否 | 任务ID数组 |
|
|
171
596
|
|
|
172
|
-
|
|
597
|
+
返回空对象:
|
|
173
598
|
|
|
174
|
-
|
|
599
|
+
```json
|
|
600
|
+
{}
|
|
601
|
+
```
|
|
175
602
|
|
|
176
|
-
|
|
177
|
-
|-----------|--------|----|----------------------------------------|
|
|
178
|
-
| id | string | 是 | 任务ID |
|
|
179
|
-
| signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
|
|
180
|
-
| result | string | 是 | JSON格式的结果 |
|
|
603
|
+
#### POST `{prefix}/next`
|
|
181
604
|
|
|
182
|
-
|
|
605
|
+
处理等待回调的任务,无需认证。当任务设置了 `context.secret` 时需提供签名。
|
|
183
606
|
|
|
184
|
-
|
|
607
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
608
|
+
|-----------|--------|----|------------------------------------------|
|
|
609
|
+
| id | string | 是 | 任务ID |
|
|
610
|
+
| signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
|
|
611
|
+
| result | string | 是 | JSON 格式结果字符串 |
|
|
185
612
|
|
|
186
|
-
|
|
187
|
-
|-----------|--------|----|----------------------------------------|
|
|
188
|
-
| id | string | 是 | 任务ID(body) |
|
|
189
|
-
| taskId | string | 是 | 任务ID(query) |
|
|
190
|
-
| data | object | 否 | 日志数据 |
|
|
191
|
-
| message | string | 否 | 日志消息 |
|
|
192
|
-
| signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
|
|
613
|
+
成功处理时返回空对象:
|
|
193
614
|
|
|
194
|
-
|
|
615
|
+
```json
|
|
616
|
+
{}
|
|
617
|
+
```
|
|
195
618
|
|
|
196
|
-
|
|
619
|
+
#### POST `{prefix}/log`
|
|
197
620
|
|
|
198
|
-
|
|
199
|
-
|-----------|--------|----|----------------------------------------|
|
|
200
|
-
| id | string | 是 | 任务ID(body) |
|
|
201
|
-
| taskId | string | 是 | 任务ID(query) |
|
|
202
|
-
| code | number | 是 | 状态码,0为成功 |
|
|
203
|
-
| data | object | 否 | 回调数据 |
|
|
204
|
-
| message | string | 否 | 回调消息 |
|
|
205
|
-
| signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
|
|
621
|
+
记录任务日志,无需认证。当任务设置了 `context.secret` 时需提供签名。
|
|
206
622
|
|
|
207
|
-
|
|
623
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
624
|
+
|-----------|--------|----|------------------------------------------|
|
|
625
|
+
| id | string | 否 | 任务ID(body) |
|
|
626
|
+
| taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
|
|
627
|
+
| data | object | 否 | 日志数据 |
|
|
628
|
+
| message | string | 否 | 日志消息 |
|
|
629
|
+
| signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
|
|
208
630
|
|
|
209
|
-
|
|
631
|
+
返回更新后的 Task 实例:
|
|
210
632
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
| delay | number | 否 | 延迟执行秒数 |
|
|
220
|
-
| scriptName | string | 否 | 脚本名称 |
|
|
221
|
-
| options | object | 否 | 扩展选项 |
|
|
633
|
+
```json
|
|
634
|
+
{
|
|
635
|
+
"id": "task-1",
|
|
636
|
+
"options": {
|
|
637
|
+
"logs": []
|
|
638
|
+
}
|
|
639
|
+
}
|
|
640
|
+
```
|
|
222
641
|
|
|
223
|
-
|
|
642
|
+
#### POST `{prefix}/callback`
|
|
224
643
|
|
|
225
|
-
|
|
644
|
+
任务回调,无需认证。当任务设置了 `context.secret` 时需提供签名。
|
|
226
645
|
|
|
227
|
-
| 参数名
|
|
228
|
-
|
|
229
|
-
| id
|
|
646
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
647
|
+
|-----------|--------|----|------------------------------------------|
|
|
648
|
+
| id | string | 否 | 任务ID(body) |
|
|
649
|
+
| taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
|
|
650
|
+
| code | number | 是 | 状态码,0 为成功 |
|
|
651
|
+
| data | object | 否 | 回调数据 |
|
|
652
|
+
| message | string | 否 | 回调消息 |
|
|
653
|
+
| signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
|
|
230
654
|
|
|
231
|
-
|
|
655
|
+
成功处理时返回空对象:
|
|
232
656
|
|
|
233
|
-
|
|
657
|
+
```json
|
|
658
|
+
{}
|
|
659
|
+
```
|
|
234
660
|
|
|
235
|
-
|
|
661
|
+
#### GET `{prefix}/statistics`
|
|
662
|
+
|
|
663
|
+
获取任务统计概览,需 `statistics` 权限。
|
|
664
|
+
|
|
665
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
666
|
+
|------------|--------|----|--------|--------------------------------|
|
|
667
|
+
| range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
|
|
668
|
+
| timezone | string | 否 | 服务器时区 | 时区,如 `Asia/Shanghai` |
|
|
669
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
670
|
+
| runnerType | string | 否 | - | 按执行方式筛选 `manual` / `system` |
|
|
671
|
+
|
|
672
|
+
返回值:
|
|
673
|
+
|
|
674
|
+
```json
|
|
675
|
+
{
|
|
676
|
+
"range": "7d",
|
|
677
|
+
"rangeLabel": "最近7天",
|
|
678
|
+
"totalTasks": 0,
|
|
679
|
+
"byStatus": {},
|
|
680
|
+
"byType": {},
|
|
681
|
+
"byRunnerType": {},
|
|
682
|
+
"recentTrend": [],
|
|
683
|
+
"recentTrendByStatus": [],
|
|
684
|
+
"recentTrendByType": [],
|
|
685
|
+
"durationTrend": [],
|
|
686
|
+
"hourlyTrend": [],
|
|
687
|
+
"hourlyCompletionTrend": []
|
|
688
|
+
}
|
|
689
|
+
```
|
|
236
690
|
|
|
237
|
-
####
|
|
691
|
+
#### GET `{prefix}/statistics/sse`
|
|
692
|
+
|
|
693
|
+
SSE 实时推送任务统计数据,需 `statistics` 权限。
|
|
694
|
+
|
|
695
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
696
|
+
|------------|--------|----|--------|------------------|
|
|
697
|
+
| range | string | 否 | `'7d'` | 时间范围 |
|
|
698
|
+
| timezone | string | 否 | 服务器时区 | 时区 |
|
|
699
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
700
|
+
| runnerType | string | 否 | - | 按执行方式筛选 |
|
|
701
|
+
| interval | number | 否 | `5` | 推送间隔时间(秒),最小 1 秒 |
|
|
702
|
+
|
|
703
|
+
### 程序化 API
|
|
704
|
+
|
|
705
|
+
通过 `fastify.task.services` 访问。
|
|
706
|
+
|
|
707
|
+
#### 任务管理
|
|
708
|
+
|
|
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 })` | 等待任务完成(轮询),返回任务输出数据 |
|
|
718
|
+
|
|
719
|
+
**services.create 参数:**
|
|
720
|
+
|
|
721
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
722
|
+
|--------------|--------|----|-----------|----------|
|
|
723
|
+
| userId | string | 否 | - | 用户ID |
|
|
724
|
+
| input | object | 否 | - | 输入数据 |
|
|
725
|
+
| type | string | 是 | - | 任务类型 |
|
|
726
|
+
| targetId | string | 是 | - | 目标对象ID |
|
|
727
|
+
| targetType | string | 是 | - | 目标对象类型 |
|
|
728
|
+
| runnerType | string | 否 | - | 执行者类型 |
|
|
729
|
+
| delay | number | 否 | `0` | 延迟执行秒数 |
|
|
730
|
+
| scriptName | string | 否 | - | 脚本名称 |
|
|
731
|
+
| priority | number | 否 | `0` | 优先级 |
|
|
732
|
+
| parentTaskId | string | 否 | - | 父任务ID |
|
|
733
|
+
| maxRetries | number | 否 | `0` | 最大重试次数 |
|
|
734
|
+
| timeout | number | 否 | `3600000` | 超时时间(毫秒) |
|
|
735
|
+
| context | object | 否 | `{}` | 初始上下文 |
|
|
736
|
+
| options | object | 否 | - | 扩展选项 |
|
|
737
|
+
|
|
738
|
+
**services.waitingComplete 参数:**
|
|
739
|
+
|
|
740
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
741
|
+
|--------------|--------|----|--------|----------|
|
|
742
|
+
| id | string | 是 | - | 任务ID |
|
|
743
|
+
| pollInterval | number | 否 | `1000` | 轮询间隔(毫秒) |
|
|
744
|
+
| maxPollTimes | number | 否 | `20` | 最大轮询次数 |
|
|
745
|
+
|
|
746
|
+
#### 回调与日志
|
|
747
|
+
|
|
748
|
+
| 方法签名 | 说明 |
|
|
749
|
+
|--------------------------------------------------------------------------|--------------------------|
|
|
750
|
+
| `services.processNext({ id, signature, result })` | 处理等待回调的任务,需签名验证 |
|
|
751
|
+
| `services.callback({ id, code, data, message })` | 任务回调(内部调用,无需签名) |
|
|
752
|
+
| `services.callbackWithSignature({ id, code, data, message, signature })` | 任务回调(外部调用,需签名验证) |
|
|
753
|
+
| `services.log({ id, taskId, data, message })` | 记录日志(内部调用,无需签名),最多 100 条 |
|
|
754
|
+
| `services.logWithSignature({ id, taskId, data, message, signature })` | 记录日志(外部调用,需签名验证) |
|
|
755
|
+
|
|
756
|
+
#### 系统调度
|
|
757
|
+
|
|
758
|
+
| 方法签名 | 说明 |
|
|
759
|
+
|--------------------------------------------|------------------------------------------------------|
|
|
760
|
+
| `services.runner()` | 执行系统任务,由 cron 定时调用 |
|
|
761
|
+
| `services.claimPendingTasks(limit)` | 按优先级和开始时间认领待执行系统任务,返回已认领任务列表 |
|
|
762
|
+
| `services.processSystemTask(task, opts)` | 执行系统任务;`opts.claimed` 为 `true` 时跳过重复置为 running |
|
|
763
|
+
| `services.resetAll({ staleOnly, before })` | 重置 running 任务为 pending;`staleOnly` 为 `true` 时只恢复陈旧任务 |
|
|
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`。
|
|
787
|
+
|
|
788
|
+
#### 统计查询
|
|
789
|
+
|
|
790
|
+
| 方法签名 | 说明 |
|
|
791
|
+
|----------------------------------------------------------------------------------|--------------|
|
|
792
|
+
| `services.queryStatistics({ range, timezone, type, runnerType })` | 查询任务统计数据 |
|
|
793
|
+
| `services.sseStatistics({ range, timezone, type, runnerType, interval }, reply)` | SSE 实时推送统计数据 |
|
|
794
|
+
|
|
795
|
+
**services.queryStatistics 参数:**
|
|
796
|
+
|
|
797
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
798
|
+
|------------|--------|----|--------|--------------------------------|
|
|
799
|
+
| range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
|
|
800
|
+
| timezone | string | 否 | 服务器时区 | 时区 |
|
|
801
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
802
|
+
| runnerType | string | 否 | - | 按执行方式筛选 |
|
|
803
|
+
|
|
804
|
+
**services.sseStatistics 参数:**
|
|
805
|
+
|
|
806
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
807
|
+
|------------|--------|----|--------|-------------------------|
|
|
808
|
+
| range | string | 否 | `'7d'` | 时间范围 |
|
|
809
|
+
| timezone | string | 否 | 服务器时区 | 时区 |
|
|
810
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
811
|
+
| runnerType | string | 否 | - | 按执行方式筛选 |
|
|
812
|
+
| interval | number | 否 | `5` | 推送间隔(秒) |
|
|
813
|
+
| reply | object | 是 | - | Fastify reply 对象(第二个参数) |
|
|
814
|
+
|
|
815
|
+
### 数据模型
|
|
816
|
+
|
|
817
|
+
#### Task
|
|
818
|
+
|
|
819
|
+
| 属性名 | 类型 | 说明 |
|
|
820
|
+
|-----------------|-----------------|-----------------------------------------------------------------------------------------|
|
|
821
|
+
| type | string | 任务类型 |
|
|
822
|
+
| scriptName | string | 任务脚本名称 |
|
|
823
|
+
| targetId | string | 任务目标对象ID |
|
|
824
|
+
| targetType | string | 任务目标对象类型 |
|
|
825
|
+
| runnerType | string | 执行者类型:`manual` / `system`,默认 `manual` |
|
|
826
|
+
| priority | number | 任务优先级,数值越大越优先,默认 0 |
|
|
827
|
+
| parentTaskId | string | 父任务ID,用于任务依赖 |
|
|
828
|
+
| retryCount | number | 已重试次数,默认 0 |
|
|
829
|
+
| maxRetries | number | 最大重试次数,0 表示不自动重试 |
|
|
830
|
+
| timeout | number | 任务超时时间(毫秒),0 表示不超时,默认 3600000 |
|
|
831
|
+
| startTime | Date | 任务最早执行时间 |
|
|
832
|
+
| startedAt | Date | 任务实际开始执行时间 |
|
|
833
|
+
| completedAt | Date | 任务完成时间 |
|
|
834
|
+
| completedUserId | string | 完成任务的用户ID |
|
|
835
|
+
| input | object | 输入数据 |
|
|
836
|
+
| output | object | 输出数据 |
|
|
837
|
+
| error | string / object | 错误信息 |
|
|
838
|
+
| status | string | 任务状态:`pending` / `running` / `waiting` / `success` / `failed` / `canceled`,默认 `pending` |
|
|
839
|
+
| context | object | 上下文信息 |
|
|
840
|
+
| pollResults | array | 轮询执行结果 |
|
|
841
|
+
| pollCount | number | 轮询次数,默认 0 |
|
|
842
|
+
| progress | number | 任务进度 (0-100),默认 0 |
|
|
843
|
+
| msg | string | 任务消息 |
|
|
844
|
+
| options | object | 任务扩展选项(含 `logs` 日志数组) |
|
|
845
|
+
|
|
846
|
+
**关联关系:**
|
|
847
|
+
|
|
848
|
+
| 关联 | 外键 | 说明 |
|
|
849
|
+
|----------------|-------------------|---------------------------|
|
|
850
|
+
| belongsTo User | `userId` | 创建人,`as: 'createdUser'` |
|
|
851
|
+
| belongsTo User | `completedUserId` | 完成人,`as: 'completedUser'` |
|
|
852
|
+
| belongsTo Task | `parentTaskId` | 父任务,`as: 'parentTask'` |
|
|
853
|
+
|
|
854
|
+
**索引:**
|
|
855
|
+
|
|
856
|
+
| 索引字段 |
|
|
857
|
+
|--------------------------------|
|
|
858
|
+
| `created_at` |
|
|
859
|
+
| `status` |
|
|
860
|
+
| `type` |
|
|
861
|
+
| `runner_type` |
|
|
862
|
+
| `type, status` |
|
|
863
|
+
| `runner_type, status` |
|
|
864
|
+
| `target_id, target_type, type` |
|
|
865
|
+
| `parent_task_id` |
|
|
866
|
+
| `priority` |
|
|
867
|
+
|
|
868
|
+
### 机制说明
|
|
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
|
+
```
|
|
238
952
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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
|
+
```
|
|
246
966
|
|
|
247
|
-
|
|
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
|
+
```
|
|
248
1000
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
+
```
|
|
255
1020
|
|
|
256
|
-
|
|
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
|
+
```
|
|
257
1046
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
|
293
|
-
|
|
294
|
-
|
|
|
295
|
-
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
|
305
|
-
|
|
306
|
-
|
|
|
307
|
-
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
####
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
|
330
|
-
|
|
331
|
-
|
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
|
340
|
-
|
|
341
|
-
|
|
|
342
|
-
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
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
|
+
|
|
1077
|
+
#### 签名验证
|
|
1078
|
+
|
|
1079
|
+
使用 HMAC-SHA256 算法,签名数据格式为 `{id}|{data}`,其中 `data` 为 JSON 字符串或原始字符串。
|
|
1080
|
+
|
|
1081
|
+
| 接口 | 签名 data 内容 |
|
|
1082
|
+
|-------------------------|----------------------------------------|
|
|
1083
|
+
| `processNext` | `result` 参数值(原始 JSON 字符串) |
|
|
1084
|
+
| `logWithSignature` | `{ data, message }` 对象的 JSON 序列化 |
|
|
1085
|
+
| `callbackWithSignature` | `{ code, data, message }` 对象的 JSON 序列化 |
|
|
1086
|
+
|
|
1087
|
+
> **关键设计**:未设置 `context.secret` 时 `verifySignature` 直接返回 `true`,不阻塞无密钥任务的回调。
|
|
1088
|
+
|
|
1089
|
+
#### 重试策略
|
|
1090
|
+
|
|
1091
|
+
任务执行失败时,判断是否满足自动重试条件(`retryCount < maxRetries`):
|
|
1092
|
+
|
|
1093
|
+
| 条件 | 行为 |
|
|
1094
|
+
|----------------------------|-----------------------------------------|
|
|
1095
|
+
| `retryCount < maxRetries` | 重置为 `pending`,`startTime` 设为当前时间 + 退避延迟 |
|
|
1096
|
+
| `retryCount >= maxRetries` | 标记为 `failed`,记录错误信息 |
|
|
1097
|
+
|
|
1098
|
+
退避公式:`delay = retryBaseDelay × 2^(retryCount - 1)`
|
|
1099
|
+
|
|
1100
|
+
> **关键设计**:手动调用 `retry` 接口会重置 `retryCount` 为 0,重新开始重试计数。
|
|
1101
|
+
|
|
1102
|
+
#### 超时检测
|
|
1103
|
+
|
|
1104
|
+
每次 `runner` 执行时先调用 `checkTimeout`,扫描所有 `running` / `waiting` 且 `timeout > 0` 的任务:
|
|
1105
|
+
|
|
1106
|
+
```
|
|
1107
|
+
当前时间 - startedAt > timeout → 标记为 failed
|
|
1108
|
+
```
|
|
1109
|
+
|
|
1110
|
+
> **关键设计**:`taskTimeout`(全局配置)和 `timeout`(任务级别)均使用毫秒作为单位。全局 `taskTimeout` 在 executor 执行时通过
|
|
1111
|
+
`Promise.race` 控制;任务 `timeout` 字段在 cron 轮询时检测。
|
|
1112
|
+
|
|
1113
|
+
#### 任务认领与启动恢复
|
|
1114
|
+
|
|
1115
|
+
| 机制 | 表达式 / 条件 | 说明 |
|
|
1116
|
+
|------|-------------------------------------------------------------|-----------------------------------------------------|
|
|
1117
|
+
| 认领候选 | `runnerType = system`、`status = pending`、`startTime <= now` | 按 `priority DESC`、`startTime ASC` 查询候选任务 |
|
|
1118
|
+
| 原子认领 | `id + runnerType + status + startTime` 条件更新 | 只有更新影响 1 行的任务会被当前实例执行 |
|
|
1119
|
+
| 启动恢复 | `resetAll({ staleOnly: true })` | 启动时只恢复超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务 |
|
|
1120
|
+
| 手动重置 | `resetAll()` | 不传 `staleOnly` 时会重置所有 `running` 任务 |
|
|
1121
|
+
|
|
1122
|
+
> **关键设计**:多实例部署时,任务执行前必须先认领;启动恢复默认只处理陈旧任务,避免误中断其他实例正在执行的任务。
|
|
1123
|
+
|
|
1124
|
+
#### 父子任务依赖
|
|
1125
|
+
|
|
1126
|
+
当父任务执行成功后,自动激活 `parentTaskId` 指向该父任务且状态为 `pending` 的子任务:
|
|
1127
|
+
|
|
1128
|
+
| 子任务 runnerType | 激活行为 |
|
|
1129
|
+
|----------------|-----------------------------|
|
|
1130
|
+
| `system` | 立即调用 `processSystemTask` 执行 |
|
|
1131
|
+
| `manual` | 保持 `pending`,等待手动执行 |
|
|
1132
|
+
|
|
1133
|
+
> **关键设计**:只有父任务 **成功** 后才触发子任务,失败或取消不会激活子任务。
|
|
1134
|
+
|
|
1135
|
+
#### 统计数据采集
|
|
1136
|
+
|
|
1137
|
+
任务完成时通过 `@kne/fastify-statistics` 采集数据,channel 格式为 `{type}:{runnerType}:{completedHour}`,采集维度:
|
|
1138
|
+
|
|
1139
|
+
| 维度 | 单位 | 说明 |
|
|
1140
|
+
|-----------------------------|-------|-------------------------------|
|
|
1141
|
+
| total | count | 总完成数 |
|
|
1142
|
+
| success / failed / canceled | count | 按状态计数 |
|
|
1143
|
+
| waitingTime | ms | 等待时长(startedAt - createdAt) |
|
|
1144
|
+
| executionTime | ms | 执行时长(completedAt - startedAt) |
|
|
1145
|
+
| totalTime | ms | 总时长(completedAt - createdAt) |
|