定时任务
文档版本：20260905
文档当前版本对应的 APP 版本：
- iOS：>= 3.16
- Android：>= 1.8.0
- macOS / Windows（PC 端）：>= 1.0.21
定时任务可以把一条 请求重放 或一整条 组合重放 规则，按 Cron 或自定义间隔自动执行。适合秒杀压测、活动开售瞬间验证、定时巡检接口等「人手点不及时」的场景。
典型场景：电商秒杀窗口极短，人工点击很容易错过。可以先从抓包历史取出下单请求（或编排成组合重放），再建一条定时任务，在开售前按秒级间隔自动提交，并用自动终止条件在「抢购成功 / 活动结束」时停掉任务。
组合重放本身的编排、依赖注入、表达式写法，见 组合重放使用教程。
目录
一、功能概览
| 能力 | 说明 |
|---|---|
| 请求重放 | 按快照重放单条 HTTP/HTTPS 请求（Method / URL / Header / Body） |
| 组合重放 | 按快照执行整条组合规则（拓扑分层、表达式、依赖注入都会跑） |
| Cron | 6 字段表达式（含秒）：秒 分 时 日 月 周 |
| 自定义 | 按间隔秒循环执行；可限制次数、持续时长（iOS / PC 还可指定开始时间） |
| 自动终止 | 仅两种：响应 Body 正则、JSON 字段值全等。命中后任务被停用，不是暂停 |
| 执行历史 | 独立的「执行历史」面板，含 Avg / P95 / P99、成功率 |
二、快速上手
- 先抓包，拿到要定时执行的 HTTP/HTTPS 请求；若要跑流程，先在组合重放里建好规则并保存。
- 进入 定时任务 列表，点 + / 添加定时任务。
- 填写 Job名称，选择目标类型：
- 请求重放：从历史里选一条请求，可以编辑修改请求参数（查询参数、请求头、请求Body）
- 组合重放：从已有组合规则里选一条，可以编辑每个节点（请求）的请求参数
- 选择 Cron 或 自定义，确认设置页里的「最近几次执行时间 / 下次执行时间」预览合理。
- （可选）打开 自动终止，用正则或 JSON 字段匹配「成功 / 结束」响应。
- 确保任务为 已启用，然后：
- iOS / Android：开始抓包（VPN）。未开抓包时任务不会跑。因为定时任务执行期间VPN开着，所以请求也会被捕获进请求历史里，并且配置的重写/脚本也会生效。
- 桌面端：保持 ApiCatcher 窗口运行即可，不依赖 VPN。如需让重写/脚本作用到定时任务发起的请求，需要启动捕获。
- 点进任务查看 执行历史。
三、入口与任务管理
3.1 怎么进「定时任务」
- 抓包首页右上角 + → 定时任务
- 在 请求重放 或 组合重放执行页 右上角点闹钟按钮，可带着当前请求或规则直接创建
3.2 创建 / 编辑 / 删除 / 启用
| 操作 | 方式 |
|---|---|
| 创建 | 列表右上角 +，或空态「添加定时任务」 |
| 看历史 | 单击任务行 |
| 编辑 | 左滑 → 编辑 |
| 删除 | 左滑 → 删除（会一并删除该任务的执行历史） |
| 启用 / 停用 | 编辑页 Toggle「启用」 |
新建时默认启用。
编辑已有任务时，不能更换目标类型，也不能另选一条请求/规则；仍可改名称、启用开关、快照里的请求参数/节点参数、调度方式和自动终止。
四、任务目标
目标只有两种：
| Job目标 | 执行内容 |
|---|---|
| 请求重放 | 执行单个 HTTP 请求，支持表达式注入 |
| 组合重放 | 执行多个 HTTP 请求，按组合重放规则编排的顺序执行，支持依赖注入、表达式注入 |
如果组合重放规则更新后，想要更新Job，就必须要重建一个新的Job。
五、调度配置
两种类型：Cron / 自定义。
设置页会预览最近 / 下次若干次执行时间（最多 5 条）。
5.1 Cron
表达式为 6 段，顺序：
秒 分 时 日 月 周
第 7 段（年）即使写了也会被忽略。少于 6 段则无法算出下次时间，不会调度。
这不是 Linux crontab 的 5 字段写法。例如 */5 * * * *（每 5 分钟）在这里无效。
支持的写法：
*：该字段任意取值?：用在日或周，表示不限定- 单个数字：如秒
0、时9 - 秒字段步长
/：如0/30表示每 30 秒
默认 / 占位示例：
0 * * * * ?
含义：每分钟的第 0 秒。
常用例子：
| 表达式 | 含义 |
|---|---|
0 * * * * ? | 每分钟第 0 秒 |
0 0 * * * ? | 每小时的 0 分 0 秒 |
0 0 9 * * ? | 每天 09:00:00 |
0/30 * * * * ? | 每 30 秒 |
需要「每 N 分钟」时，请用 自定义，把间隔设为 N × 60 秒。
表达式框旁可用 AI 根据自然语言生成 Cron。生成后请看下方预览时间是否符合预期。
空表达式或算不出下次时间：该任务本次不调度，不会因此自动停用。
5.2 自定义
没有单独的「结束时间」字段。按固定间隔循环执行，次数 与 持续时长 满足其一即停（每次执行前检查）。
| 字段 | 单位 | 说明 |
|---|---|---|
| 间隔 | 秒 | 每隔多久执行一次，至少为 1 |
| 最大执行次数 | 次 | 达到次数后停止 |
| 持续时长 | 分钟 | 从首次执行起持续多久后停止 |
次数、时长的计数在引擎内存里。进程重启后计数清零；但若任务已被停用，不会自动再启用。重新打开启用开关后，次数从 0 再计。
跑满次数或达到时长后，任务会被写成 未启用。
六、自动终止
界面名称：自动终止。含义是：一旦命中，不管 Cron 还有没有下次、自定义次数有没有跑完，都不再继续。
只有两种条件，没有按 HTTP 状态码终止：
| 类型 | 匹配对象 | 规则 |
|---|---|---|
| 正则表达式 | 响应 Body 文本 | 任意位置命中即可（不是整串必须等于） |
| 字段选择 | 响应 JSON | 按路径取值后，与「匹配值」做 字符串全等 |
补充：
- 多条条件是 或（OR），任一命中即停。
- 组合重放可指定 观察节点；只看该节点的执行结果。
- JSON 比较是字符串全等：数字
200要填匹配值200；布尔为true/false。
命中后的行为是 停用任务，任务还在，历史还在，不会删除。
七、何时会真正执行
受系统限制，各端的实现不同。
iOS
定时任务需在VPN进程执行，开始抓包后定时任务才会生效。
| 场景 | 是否继续跑 |
|---|---|
| 已开始抓包，主 App 进后台 | 会 |
| 已开始抓包，划掉主 App，VPN 仍开 | 会 |
| 停止抓包 | 全部 timer 取消，停止 |
| 系统因内存回收 VPN 进程 | 停止；再次开始抓包才会重新加载已启用任务 |
| 未开抓包 | 不执行。保存任务只落库，等下次开始抓包再调度 |
请求超时 15 秒。VPN 开启时，重放走本地 MITM（127.0.0.1:8888），因此 重写规则、脚本 会作用在这些请求上，抓包历史里也可能再出现对应记录。
Android
定时任务需在VPN服务执行，开始抓包后定时任务才会生效。
| 场景 | 是否继续跑 |
|---|---|
| 抓包中，仅滑到后台（前台通知还在） | 通常会继续 |
| 停止抓包 | stop()，协程取消，内存里的次数/首次时间清零 |
| 强杀 App | VPN 与进程一起没了，任务停 |
| 系统因省电杀掉进程 | 停止；若前台服务被系统拉起并再次 start()，才会重新调度仍为启用的任务 |
连接 / 读取超时各 30 秒。同样走本地 MITM，抓包历史里可能出现定时重放的流量。
桌面端
在APP进程执行，APP进程存在就能执行，APP进程退出不再执行。
| 场景 | 是否继续跑 |
|---|---|
| 窗口开着（可最小化） | 会 |
| 未开抓包 | 会 |
| 退出应用 | 停止 |
单请求超时 30 秒；组合重放每个节点超时 5 秒。请求走系统代理；若此时本地抓包开着，重写规则、脚本 会作用在这些请求上，抓包历史里也可能再出现对应记录。
组合重放执行规则（三端一致）
- 按依赖拓扑分层；同一层并行，下一层等上一层完成。
- 某节点非 2xx（或发送失败）后，后续层 跳过（不再请求）。
- 快照里的表达式、依赖注入、全局变量都会执行。
八、执行历史与统计
点任务进入 执行历史（不是编辑页）。
顶部「统计详情」按 全部执行记录 聚合（一次定时触发算一条，不是按单条 HTTP）：
- Avg / P95 / P99：先算每一次执行的整段耗时（该条记录的结束时间 − 开始时间），再对全部记录取平均和第 95 / 99 百分位，界面显示为毫秒
- Success Rate / Success / Failure：某一次执行里 所有请求都成功 才算这次成功；组合重放有一个节点失败，整次算失败。再据此统计全部记录的成功率和成功 / 失败次数
点某条记录可查看这次发出去的请求（详情）。如果是组合重放，会先列出各个节点，再点节点看详情。
右上角可以清空该任务的全部历史。删除任务时，历史会一起删掉。
这套数据在独立表里，不是主界面「历史记录 / 请求历史」那张表。但如上一节所述：开着抓包时，重放往往还会再进主历史。
主历史里的这些记录 没有「定时任务」标记，看起来就像普通抓包。
九、典型场景
场景 1：秒杀开售前高频打单
- 抓到下单接口，确认 Body / Header 无误（需要动态时间戳时，用组合重放节点写
${method.timestamp()}）。 - 新建定时任务，目标选该请求或组合规则。
- 自定义：开始时间设为开售前数秒（务必设未来时间），间隔 1 秒。
- 自动终止：JSON 字段
code匹配200，或正则匹配"抢购成功"/"活动已结束"。 - iOS / Android 提前开始抓包；桌面端保持窗口打开。
场景 2：每分钟巡检一条健康检查接口
三端都可用 Cron：
0 * * * * ?
不配自动终止，任务会一直按分钟跑，直到你手动停用，或停止抓包（移动端）/ 退出应用（桌面端）。
场景 3：登录 + 业务接口的定时回归
- 在组合重放里配好：登录 → 业务接口，并做好 token 依赖注入。
- 用该规则创建定时任务。
十、常见问题
Q：任务保存了但不跑？
A：iOS / Android 必须先 开始抓包。桌面端必须让应用保持运行。再确认任务是「已启用」，Cron 至少 6 段且预览能算出时间。
Q：自定义任务保存后立刻变成未启用？
A：把开始时间设置成过去时间，引擎会直接停用且一次都不执行。请改成未来时间后重新启用保存。
Q：改了组合重放规则，定时任务没变化？
A：预期行为。任务绑的是创建时保存的快照。请删除后重建。
Q：为什么主历史里也能看到这些请求？
A：移动端开着 VPN 时，定时重放会走本地 MITM，和普通抓包同一套入库。请到任务的「执行历史」看专用报表；主历史里没有定时任务标记。
Q：自动终止配了状态码 200 怎么不生效？
A：没有「按 HTTP 状态码终止」。请改用 JSON 字段（例如 code == 200）或正则匹配 Body。
Q：为什么有的组合节点没发出去？
A：与手动执行组合重放相同：上一层非 2xx 后，后续层跳过。被跳过的观察节点没有 Body，自动终止也不会命中。
Q：卸载 App / 清数据后任务还在吗？
A：任务和历史都在本地。卸载或清数据会丢失。
Q：需要一直开着重写规则吗？
A：移动端定时请求会进 MITM。若有 Mock / 丢弃 / 修改规则匹配到这些 URL，定时任务打出去的也是被改过的结果。排查「响应不对」时先看重写和脚本。