
# @Log

`@Log()` (`spring_core_dart` のもの) は、Java の Lombok の `@Slf4j` のように、`SpringLog` を返す `log` ゲッターをクラスに与えます。ジェネレーターは、クラスをスキャンする `@ComponentScan` または `@SpringBootApplication` の `.spring.dart` ファイルに、そのゲッターをクラスの拡張として書き出します。

## 使う理由

ログを出すクラスにはロガーが必要で、通常は `const log = SpringLog('my_app.Checkout');` のような定数です。これをすべてのクラスに手で書くとクラス名を繰り返すことになり、クラスの名前を変えたり移動したりすると名前が古くなります。Dart では外からクラスにフィールドを追加できませんが、拡張ならゲッターを追加できます。そこでジェネレーターは、ビルド時に計算したロガー名を使い、`@Log` クラスごとに一つの拡張を書き出します。

## 例

```dart
// パッケージ my_app の lib/src/checkout.dart
import 'package:spring_core_dart/spring_core_dart.dart';

import '../spring_gen/main.spring.dart'; // 拡張がある場所

@Service()
@Log()
class Checkout {
  void pay(double amount) => log.info('paid $amount');
}

// Bean ではない: @Log はスキャン内の任意のクラスで動く。
@Log(topic: 'neon.payments', fieldName: 'logger')
class Payments {
  void refund() => logger.warning('refund');
}
```

ジェネレーターは、スキャンの `.spring.dart` ファイルに次のように書き出します (簡略化。実際のファイルは `_i1.` のようなインポートのプレフィックスを使います)。

```dart
/// `@Log` of [Checkout]: the logger 'my_app.Checkout'.
extension $CheckoutLog on Checkout {
  SpringLog get log => const SpringLog(r'my_app.Checkout');
}

/// `@Log` of [Payments]: the logger 'neon.payments'.
extension $PaymentsLog on Payments {
  SpringLog get logger => const SpringLog(r'neon.payments');
}
```

クラスの中では、`log.info(...)` が拡張のゲッターを呼びます。ゲッターは定数を返すので、インスタンスごとのオブジェクトも実行時の検索もありません。

`spring_core_dart` のサンプル (`example/spring_gen/main.spring.dart`) からの実際の抜粋で、`@Log(topic: 'tour')` を持つ二つのクラスのものです。

```dart
/// `@Log` of [WelcomeMail]: the logger 'tour'.
extension $WelcomeMailLog on _i2.WelcomeMail {
  _i1.SpringLog get log => const _i1.SpringLog(r'tour');
}

/// `@Log` of [Tour]: the logger 'tour'.
extension $TourLog on _i2.Tour {
  _i1.SpringLog get log => const _i1.SpringLog(r'tour');
}
```

## 引数

| 引数 | デフォルト | 効果 |
|---|---|---|
| `topic:` | `<package>.<Class>` | `SpringLog` に渡すロガー名 |
| `fieldName:` | `log` | 生成されるゲッターの名前 |

デフォルトのロガー名は、パッケージ名とクラス名です。パッケージ `my_app` のどのライブラリにあるクラスでも `my_app.Checkout` になります (`lib/` の下のフォルダーは数えません)。`package:` URI を持たない `lib/` の外のライブラリ (`bin/`、`example/`、`test/` のファイル) では、パッケージの代わりに `.dart` を除いたファイル名が使われます。`bin/main.dart` のクラス `Tour` は `main.Tour` としてログを出します。

複数のクラスを一つのロガーにまとめ、一つの設定でそれらを制御するには `topic:` を使います。

```properties
# lib/resources/application.properties
logging.level.neon.payments=debug
```

レベルは名前のドットに従います (`neon.payments` は `neon.payments.refunds` も対象にします)。[SpringLog](../spring-core-dart/logging/spring-log.md) を参照してください。

`log` がすでに使われている場合は `fieldName:` を使います。`dart:math` と `dart:developer` はどちらもトップレベル関数 `log` を宣言しており、ライブラリのスコープで宣言された `log` は拡張のゲッターより優先されます。それらのいずれかをインポートしている場合は、別の名前を選んでください: `@Log(fieldName: 'logger')`。

## 仕組み

1. **どのクラスか。** モジュールがスキャンするライブラリのすべてのクラスが、Bean かどうかにかかわらず `@Log` についてチェックされます。`@Service`、普通のクラス、スキャンのフィルターが Bean にしないクラスです。どのスキャンにも含まれないクラス (たとえばテストファイルの中のもの) はゲッターを受け取りません。
2. **チェック。** クラスは public でなければならず、`fieldName` は有効なゲッター名でなければならず、クラスがすでにその名前のメンバーを持っていてはいけません ([ビルドエラー](None#ビルドエラー) を参照)。
3. **名前。** `topic:` が与えられない限り、ロガー名はライブラリの URI とクラス名から計算されます。
4. **拡張。** 名前は `$<Class>Log` で、モジュールとアプリケーションの関数の後に書かれます。一つのモジュールの別々のライブラリにある同名の二つの `@Log` クラスは、スキャン順に `$CheckoutLog` と `$CheckoutLog2` を受け取るので、拡張は衝突しません。
5. **ジェネリッククラス。** 拡張は raw 型に対するものです。`@Log() class Repo<T>` は `extension $RepoLog on Repo` になり、すべての `Repo<...>` に一致します。

## ゲッターをインポートする

拡張は、そのライブラリがインポートされている場所でだけ見えます。クラス自身のライブラリは、それをスキャンする `.spring.dart` ファイルをインポートしなければなりません。

| クラスをスキャンするもの | インポート |
|---|---|
| `bin/main.dart` の `@SpringBootApplication` | `bin/spring_gen/main.spring.dart` |
| `lib/main.dart` の `@SpringBootApplication` | `package:my_app/spring_gen/main.spring.dart` |
| `lib/src/beans.dart` の `@ComponentScan` | `package:my_app/spring_gen/src/beans.spring.dart` |

インポートがないと、`log` は未知の名前になり、クラスはコンパイルできません。生成ファイルにインポートされ、それをインポートし返すライブラリは、Dart では普通のインポートの循環です。

## ビルドエラー

動きえないゲッターは、クラスを場所としてビルドを失敗させます。エラーはビルドの他の問題と一緒に集められ、まとめて報告されます。

| 問題 | メッセージ |
|---|---|
| private なクラス | `@Log on _Hidden: the class is private, so the generated getter (an extension in the .spring.dart file) cannot name it; make the class public or declare the logger yourself: const _log = SpringLog('...');` |
| 無効なゲッター名 | `@Log on A: fieldName "class" is not a valid getter name (a public Dart identifier that is no reserved word).` |
| ゲッターと同名のメンバー | `@Log on C: C already has a member "log", which would win over the generated getter; choose another name with @Log(fieldName: '...').` |

有効な `fieldName` は、英字か `$` で始まり、その後に英字、数字、`_`、`$` が続きます。`_` で始まる名前は拒否され (ゲッターが生成ファイルに private になってしまうため)、Dart の予約語と組み込み識別子 (`class`、`get`、`set`、`type`、`late`、`required` など) も拒否されます。

メンバーのチェックは、クラスとそのすべてのスーパータイプのメソッド、ゲッター、セッター、フィールドを見ます。クラスのメンバーは常に拡張のメンバーより優先されるので、スーパークラスのメンバーも数えられます。

```dart
class Base {
  void log() {}
}

@Log() // ✗ @Log on D: D already has a member "log", ...
class D extends Base {}
```

## Spring (Java) との対応

```java
@Slf4j(topic = "neon.payments")
class Payments {
  void refund() { log.warn("refund"); }
}
```

重要な違い:

- Lombok はコンパイル中にクラスに static フィールドを追加します。ここでは、ジェネレーターが `.spring.dart` ファイルに拡張のゲッターを書き出し、クラスのライブラリがそれをインポートしなければなりません。
- デフォルトのロガー名は、完全修飾クラス名ではなく `<package>.<Class>` です。
- Lombok の `@Slf4j` は SLF4J を使います。ここではゲッターは、Spring for Dart の唯一のロギング API である `SpringLog` を返します。

## 関連項目

- [SpringLog](../spring-core-dart/logging/spring-log.md): レベル、ハンドラー、ロギング API。
- [ロギング](../spring-core-dart/logging/index.md)
- [@ComponentScan モジュール](component-scan.md): モジュールがどのライブラリをスキャンするか。
