serverpod-scheduling

Serverpod 定时调度（未来调用）

未来调用会在指定时间运行，存储在数据库中，并在重启后保留。集群中的每次调用只会被认领并执行一次。未来调用需要数据库支持；执行由单体／维护角色启动，而非无服务器角色。

定义未来调用

class ExampleFutureCall extends FutureCall {
  Future<void> doWork(Session session) async {
    // Work here.
  }

  Future<void> doOtherWork(Session session, MyModel data) async {
    // Work with data.
  }
}

运行 serverpod generate，以在 pod.futureCalls 上使用类型安全的 API。

支持的参数类型

与端点方法相同，详见 Serverpod 端点。

调度

// Delay
await pod.futureCalls
    .callWithDelay(const Duration(hours: 1))
    .example.doWork();

// At specific time (UTC)
await pod.futureCalls
    .callAtTime(DateTime.utc(2026, 1, 1))
    .example.doOtherWork(myModel);

// With identifier (for cancellation)
await pod.futureCalls
    .callWithDelay(const Duration(hours: 1), identifier: 'my-job-id')
    .example.doWork();

// Recurring task from `Duration` interval with an optional start time
await pod.futureCalls
    .callRecurring()
    .every(const Duration(hours: 1), start: DateTime.now())
    .example.doWork();

// Recurring task from `cron` expression
await pod.futureCalls
    .callRecurring()
    .cron("0 * * * *")
    .example.doWork();

await pod.futureCalls.cancel('my-job-id');  // Cancels all with that identifier

在调用内部处理失败；如果工作最终必须成功，请重新调度。

配置

futureCall:
  enabled: true                   # SERVERPOD_FUTURE_CALL_ENABLED (default true)
  executionEnabled: true          # SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED
  concurrencyLimit: 5             # SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT (default 1, <1 maps to unlimited and is not recommended)
  scanInterval: 2000              # SERVERPOD_FUTURE_CALL_SCAN_INTERVAL (ms, default 5000)

futureCallExecutionEnabled: false 仅会停止执行；仍可调度调用。futureCall.enabled: false 会完全禁用未来调用：不会创建未来调用管理器，且 serverpod generate 会省略 pod.futureCalls getter。所有运行模式配置文件中的值必须一致，否则生成会失败。

保持未来调用的幂等性。调用应能容忍重试或重启，而不会重复产生不可逆的副作用。