
# cron 式

cron 式は、カレンダーの時刻を記述します。「15 分ごと」「平日の 9:00」「月の最後の金曜日」などです。Spring と同じく、秒から始まる 6 つのフィールドを持ちます (Unix の cron は 5 つです)。

## 使う理由

多くのジョブは、周期ではなくカレンダーに従います。毎朝のレポート、夜間の後片付け、月の最終営業日の請求処理などです。cron 式はそれを一行で表し、同じ構文が `@Scheduled`、`CronTrigger`、プロパティで使えます。

## 例

```dart
@Scheduled(cron: '0 0 9 * * MON-FRI')       // 平日の 9:00、ローカル時刻
void morningDigest() => mail.sendDigest();

@Scheduled(cron: '0 0 12 LW * *', zone: 'UTC') // 月の最終営業日の UTC の正午
Future<void> invoices() => billing.run();
```

```text
second minute hour day-of-month month day-of-week
```

## 例の一覧

| 式 | 実行されるタイミング |
|---|---|
| `0 * * * * *` | 毎分、0 秒に |
| `*/10 * * * * *` | 10 秒ごと |
| `0 */15 * * * *` | 15 分ごと |
| `0 0 * * * *` | 毎時 |
| `0 0 9-17 * * MON-FRI` | 平日の 9 時から 17 時まで毎時 |
| `0 30 8 * * *` | 毎日 8:30 |
| `0 0 0 1 * *` | 毎月 1 日の午前 0 時 |
| `0 0 18 L * *` | 月の最終日の 18:00 |
| `0 0 12 LW * *` | 月の最終営業日の正午 |
| `0 0 10 15W * *` | 15 日に最も近い営業日の 10:00 |
| `0 0 20 ? * FRIL` | 月の最後の金曜日の 20:00 |
| `0 0 9 ? * MON#1` | 月の最初の月曜日の 9:00 |
| `0 0 9 ? * MON#1,MON#3` | 第 1 と第 3 月曜日の 9:00 |
| `0 0 0 1,L * *` | 月の最初と最後の日の午前 0 時 |
| `0 0 10 * * SAT-SUN` | 週末の 10:00 |
| `0 0 0 25 DEC *` | 12 月 25 日の午前 0 時 |
| `@hourly`、`@daily` (`@midnight`)、`@weekly`、`@monthly`、`@yearly` (`@annually`) | よく使われるマクロ |
| `-` | 決して実行しない: タスクは無効 |

## 構文

- どのフィールドも、`*`、値 (`5`)、リスト (`1,15,30`)、範囲 (`9-17`)、ステップ (`*/5`、`0-30/10`、`5/15` = 5 から 15 ごと) を受け取ります。
- 月は `JAN`-`DEC` で、名前は大文字小文字を区別しません。日のフィールドでは `?` は「任意」を意味します。
- 曜日は Spring と同じく番号が振られます。`MON`-`SUN` は 1-7 で、0 も日曜日です。範囲の始まりの日曜日は 0 とみなされるため、`SAT-SUN`、`MON-SUN`、`SUN-TUE` はどれも動きます。`*/2` は MON、WED、FRI、SUN です。

| 特殊文字 | フィールド | 意味 |
|---|---|---|
| `L` | 日 | 最終日 |
| `L-n` | 日 | 最終日の n 日前 |
| `nW` | 日 | n 日に最も近い営業日 |
| `LW` | 日 | 最終営業日 |
| `nL` (`FRIL`) | 曜日 | 月の最後のその曜日 |
| `n#k` (`MON#1`) | 曜日 | 月の k 番目のその曜日。k は 1 から 5 |

特殊文字は、リストの中で互いに、また値と組み合わせられます (`1,L`、`MON-FRI,SATL`)。

## Unix の cron と異なるルール

- Spring と同じく、日は**両方の**日のフィールドに一致しなければなりません (Unix の cron はどちらかに一致すればよい)。
- 範囲は一周できません。`FRI-MON` はエラーです。`FRI-SUN,MON` と書いてください。
- 秒から始まる 6 つのフィールドです。

## タイムゾーンと夏時間

- `zone` はローカル時刻 (省略) か UTC (`'UTC'`、`'Z'`、`'GMT'`) です。Dart にはタイムゾーンデータベースがないため、他のタイムゾーンはエラーです。
- ローカル時刻は、Spring と同じく実時間の時計に従います。時計が進むときに飛ばされる時間の中の時刻は存在しないためスキップされ (毎日の `0 30 2 * * *` はその日は実行されません)、時計が戻るときに繰り返される時間の中の時刻は、変更の前後で 2 回実行されます。

## コードで式をチェックする

```dart
final cron = CronExpression.parse('0 0 9 * * MON-FRI');
final next = cron.next(DateTime.now());       // 次に実行されるタイミング
CronExpression.isValid('0 0 25 * * *');       // false: 25 時はない
```

`CronExpression.parse` は、誤ったフィールドを示す `FormatException` を投げます。ユーザーが入力した式を `CronTrigger` でスケジュールする前にチェックするのに使ってください。

## Spring (Java) との対応

```java
CronExpression cron = CronExpression.parse("0 0 9 * * MON-FRI");
LocalDateTime next = cron.next(LocalDateTime.now());
```

構文は Spring の `CronExpression` のものです。`#k` は 1-5 を受け取り (Spring は決して一致しないより大きな序数も受け入れます)、タイムゾーンとして提供されるのはローカル時刻と UTC だけです。

## 関連項目

- [@Scheduled](scheduled.md)
- [TaskScheduler](task-scheduler.md)
