Spire 天擎

外观

Scheduler 快速开始 ​

这一页只做一件事：让你先跑通一个最小可工作的定时任务。

适用场景 ​

  • 第一次接触 soulsoft_scheduler
  • 想先验证任务能不能按时间触发
  • 还不关心 DI、Host 集成和复杂调度规则

核心问题 ​

soulsoft_scheduler 的最小使用路径很短：

  1. 定义一个实现 IJob 的任务类
  2. 用 JobBuilder 定义触发器和标识
  3. 用 SchedulerBuilder 构建调度器并启动

快速开始 ​

Cron 触发器 ​

先看这几行：IJob、withCronTrigger()、scheduleJob()、start()。

cangjie
import soulsoft_scheduler.*
import soulsoft_scheduler.abstractions.*

public class CleanupJob <: IJob {
    public func execute(_: IJobContext): Unit {
        println("cleanup: ${DateTime.now().format('yyyy-MM-dd HH:mm:ss')}")
    }
}

main(): Int64 {
    let scheduler = SchedulerBuilder().build()

    let jobDetail = JobBuilder
        .create<CleanupJob>()
        .withCronTrigger("*/5 * * * * ?")
        .withIdentity("cleanup")
        .build()

    scheduler.scheduleJob(jobDetail)
    scheduler.start()
    return 0
}

这段代码的含义很直接：

  • CleanupJob 是实际执行的任务
  • withCronTrigger("*/5 * * * * ?") 表示每 5 秒触发一次
  • withIdentity("cleanup") 给任务一个唯一标识
  • scheduler.start() 启动调度循环

固定间隔触发器 ​

如果你不想写 Cron，直接用间隔触发器：

cangjie
let jobDetail = JobBuilder
    .create<CleanupJob>()
    .withIntervalTrigger(Duration.second * 5)
    .withIdentity("cleanup")
    .build()

适合这种场景：

  • 每隔固定时间执行
  • 不需要按"某天某时"表达规则
  • 先做本地验证

关键角色 ​

角色作用
IJob定义任务执行逻辑
JobBuilder定义任务、触发器、标识、数据
IScheduler管理任务注册、暂停、恢复、启动、停止
SchedulerBuilder组装调度器实例

常见用法 ​

带任务数据的调度 ​

任务参数优先放进 jobData，不要硬编码到任务类里：

cangjie
let jobDetail = JobBuilder
    .create<ReportJob>()
    .withCronTrigger("0 0 8 * * ?")
    .withIdentity("daily-report", "reports")
    .withJobData { d =>
        d.set<String>("reportType", "daily")
        d.set<Int64>("retryCount", 3)
    }
    .build()

暂停和恢复 ​

cangjie
scheduler.pauseJob(Key("cleanup"))
scheduler.resumeJob(Key("cleanup"))

常见问题 ​

Cron 和间隔触发器怎么选 ​

  • 按自然时间点（每天2点、每周一8点）→ Cron
  • 固定每隔一段时间（每30秒、每5分钟）→ 间隔触发器

start() 之后主线程会怎样 ​

scheduler.start() 不会阻塞主线程——调度器在内部线程中执行。如果你的 main() 需要保持运行，用 sleep() 或配合 Host 生命周期。

相关专题 ​