@Log

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

使う理由

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

例

// パッケージ 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. のようなインポートのプレフィックスを使います)。

/// `@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') を持つ二つのクラスのものです。

/// `@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: を使います。

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

レベルは名前のドットに従います (neon.payments は neon.payments.refunds も対象にします)。SpringLog を参照してください。

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

仕組み

  1. どのクラスか。 モジュールがスキャンするライブラリのすべてのクラスが、Bean かどうかにかかわらず @Log についてチェックされます。@Service、普通のクラス、スキャンのフィルターが Bean にしないクラスです。どのスキャンにも含まれないクラス (たとえばテストファイルの中のもの) はゲッターを受け取りません。
  2. チェック。 クラスは public でなければならず、fieldName は有効なゲッター名でなければならず、クラスがすでにその名前のメンバーを持っていてはいけません (ビルドエラー を参照)。
  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 など) も拒否されます。

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

class Base {
  void log() {}
}

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

Spring (Java) との対応

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

重要な違い:

関連項目