serverpod-scheduling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Serverpod Scheduling (Future Calls)

Serverpod 任务调度（Future Calls）

Future calls run at a specified time, are stored in the database, and survive restarts. Each call is claimed for one execution across the cluster. Future calls require database support; execution is started by monolith/maintenance roles, not serverless role.

Future Call 会在指定时间运行，存储在数据库中，且在服务重启后仍能保留。集群中每个任务只会被一个节点认领执行。Future Call 需要数据库支持；由单体/维护角色启动执行，而非无服务器角色。

Defining a future call

定义 Future Call

dart

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

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

Run

serverpod generate

for the type-safe API on

pod.futureCalls

dart

class ExampleFutureCall extends FutureCall {
  Future<void> doWork(Session session) async {
    // 此处编写任务逻辑。
  }

  Future<void> doOtherWork(Session session, MyModel data) async {
    // 处理数据。
  }
}

运行

serverpod generate

以生成

pod.futureCalls

上的类型安全API。

Supported parameter types

支持的参数类型

The same types as for endpoint methods, listed in Serverpod Endpoints.

与端点方法支持的类型相同，详见 Serverpod 端点。

Scheduling

调度任务

dart

// 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

Handle failures inside the call and reschedule if the work must eventually succeed.

dart

// 延迟执行
await pod.futureCalls
    .callWithDelay(const Duration(hours: 1))
    .example.doWork();

// 在指定时间执行（UTC时区）
await pod.futureCalls
    .callAtTime(DateTime.utc(2026, 1, 1))
    .example.doOtherWork(myModel);

// 使用标识符（用于取消任务）
await pod.futureCalls
    .callWithDelay(const Duration(hours: 1), identifier: 'my-job-id')
    .example.doWork();

// 按时间间隔执行的周期性任务，可指定开始时间
await pod.futureCalls
    .callRecurring()
    .every(const Duration(hours: 1), start: DateTime.now())
    .example.doWork();

// 按cron表达式执行的周期性任务
await pod.futureCalls
    .callRecurring()
    .cron("0 * * * *")
    .example.doWork();

await pod.futureCalls.cancel('my-job-id');  // 取消所有带有该标识符的任务

在任务内部处理失败情况，如果任务必须最终成功，请重新调度。

Configuration

配置

yaml

futureCallExecutionEnabled: true  # SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED
futureCall:
  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)

Keep future calls idempotent. A call should tolerate retries or restarts without duplicating irreversible side effects.

yaml

futureCallExecutionEnabled: true  # SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED
futureCall:
  concurrencyLimit: 5             # SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT（默认值1，小于1表示无限制，不推荐）
  scanInterval: 2000              # SERVERPOD_FUTURE_CALL_SCAN_INTERVAL（毫秒，默认值5000）