
# エフェクト

`@Effect` のメソッドは、Bean が作られたときに一度実行され、読んだものが変わるたびに再び実行されます。自分の Bean や別の Bean の、フィールドまたは計算された値です。

## 使う理由

求められなくても状態に従う仕事があります。バスケットが変わったら保存する、価格を計算し直す、などです。手で書くと、追加し、取り除き、メソッドが実際に読むものと合わせ続けるリスナーになります。エフェクトは、読んだものに従います。

## 例

```dart
@Effect()                          // items が変わるたびに再び実行される
void save() => storage.write(items);
```

```dart
@Effect()
void recalc() {
  final user = untracked(() => session.user);   // 読むが、追跡されない
  price = pricing.of(basket.items, user);        // basket.items のためにだけ実行される
}
```

## ルール

- エフェクトは、パラメーターがなく、何も返さない public なメソッドです。
- 読むものすべてを追跡します。`untracked(() => ...)` の中で読むものは除きます。
- Bean が破棄されると止まります ([状態の寿命](lifetime.md) を参照)。
- それぞれが何回実行されたかは、デバッグタブが示します。

## エフェクトが実行される時

エフェクトは、読んだものが代入されるとただちに実行されます。代入したメソッドの終わりであり、後のフレームではありません。そのため、`basket.add(book)` が戻ったとき、`save` はすでに実行されています。

## 例外を投げるエフェクト

例外を投げるエフェクトは、それを実行させた代入を失敗させません。エラーは報告され (`ChangeNotifier` のリスナーと同じく `FlutterError.reportError`)、フィールドは新しい値を保ち、代入したコードはそのまま進み、エフェクトは追跡していたものの次の変化でまた実行されます。Bean が作られるときの最初の実行で例外を投げると、Bean は作られません。

例外を投げる `@Computed` ゲッターは、投げた例外そのもので読み手を失敗させます。失敗は保持されません。次に読むときに、もう一度計算されます。

エフェクトは、読んだものに代入してもかまいません (値を範囲内に保つためなど)。何も変わらなくなるまで、もう一度実行されます。

## メソッドは一つの変化

このようなメンバーを持つ Bean のメソッドは、何を代入しても、一つの変化です。

```dart
void clear() {
  items.clear();
  coupon = null;
}                    // 読み手には、戻るときに一度だけ伝えられる
```

両方を読むエフェクトは一度だけ実行され、二つの間の状態を見ることはありません。両方を読むウィジェットは、一度だけ再構築されます。追跡されるフィールドではないセッターも、一つの変化です。

非同期のメソッドは、最初の `await` までが一つの変化です。その後は、代入ごとに別の変化になります (まとめて伝えるには `batch` で包みます)。例外を投げるメソッドも、代入したものを一度だけ伝え、エラーは呼び出し元に届きます。

外からの複数の呼び出しには、`batch(() { ... })` が同じ働きをします。

```dart
batch(() {
  basket.add(dune);
  basket.apply('TEN');
});
```

`batch` と `untracked` は、スターターが `signals_core` から再エクスポートする二つの関数です。

## トランザクションやほかのアドバイスと一緒に

追跡される状態を持つ Bean には、ほかのアドバイス (`@Transactional`、`@Cacheable`、アスペクト) も付けられます。どちらも、一つのプロキシの中で実行されます。

```dart
@Service()
class Checkout {
  @Signal()
  OrderStatus status = OrderStatus.open;

  @Transactional()
  Future<void> pay(Order order) async {
    await orders.save(order);
    status = OrderStatus.paid;     // 失敗するかもしれない処理の後で
  }
}
```

- **ロールバックはフィールドを元に戻しません。** トランザクションはデータベースをロールバックしますが、フィールドはメソッドが代入した値を保ち、読み手にはすでに伝えられています。失敗するかもしれない処理の後で代入するか、`catch` の中で前の値を代入し直してください。
- **ほかのアドバイスは、Bean 自身の呼び出しを飛ばします。** ほかの Bean や Spring と同じです。メソッドの `@Transactional` は外からの呼び出しに適用され、Bean が自分自身に対して行う呼び出しには適用されません。状態はどちらの場合も追跡されます。
- **`@Computed` メンバーでは、ほかのアドバイスは値が計算されるときに実行されます。** 保持された値を読むたびではありません。トランザクションは読み込みごとに一度だけ開かれます。
- **`@Computed` メンバーの `@PreAuthorize` は、読むたびにチェックされます。** メソッドセキュリティはほかのすべてのアドバイスより先に実行されるため、保持された値が、読む権限のない相手に渡されることはありません。
- **ガードが守るのは、それが付いたメンバーです。その下にあるものではありません。** ガードされた値の下にある普通の `@Signal` フィールドは、誰でも読み書きできます。それに代入するメソッドにもガードを付けてください。同じ Bean の別のメンバーがガードされた値から作る値は、ガードされません。ガードは、呼び出し元が読むものに付けてください。
- **`@Effect` に付けたチェックは、状態を変える相手に対するものです。** エフェクトを呼ぶ人はいません。Bean が作られるときに実行され、その後は、読んだものに代入した相手のために実行されます。チェックが拒否する相手のためには実行されず (拒否は報告されます)、起動時にユーザーがいなければ Bean は作られません。チェックは、状態を変えるメソッドに付けるものです。

状態を追跡するアドバイスは、既定の順序のアドバイスすべての外側にあります。それより前の順序を持つアドバイス (メソッドセキュリティ、`@Order` を付けたアスペクト) はその外側にあり、読むたびに実行されます。

## 関連項目

- [フィールドと計算された値](fields-and-computed.md)
- [状態の寿命](lifetime.md)
- [デバッグタブとログ](debug-tab.md)
