独自のスターター

どのパッケージもスターターになれます。アプリケーションはそれを pubspec.yaml に追加し、build_runner を再び実行し、自分のコードなしにその Bean を得ます。ロギングから Web サーバーまで、Spring for Dart のすべてのスターターがこの方法で動いていて、そこに特別なものは何もありません。独自のスターターも同じ方法で見つけられます。

使う理由

アプリケーションからアプリケーションへと繰り返されるコードがあります。自社の API のクライアント、監査ログ、メール送信、メトリクスです。それをコピーすると、その結び付けもコピーすることになります。どの Bean を生成するか、それらがどの設定を読むか、アプリケーションが別のものを必要とするときにどうするかです。スターターは、コードとその結び付けを一度だけパッケージにまとめます。

スターターの見つけられ方

ジェネレーターは、@SpringBootApplication を持つアプリケーションをビルドするとき、アプリケーションの依存関係のすべてのパッケージを、直接のものも推移的なものもたどります。各パッケージで、lib/spring_auto_configuration.dart があればそれを読み、@AutoConfigurationModule で示されたすべてのトップレベルの BeanModule 変数を、生成された springApplication に列挙します。

// アプリケーションの bin/spring_gen/main.spring.dart (生成)
SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    neonAuditAutoConfiguration,   // neon_audit で見つかった
    springBootAutoConfiguration,  // spring_boot_dart
    // ... その他のすべてのスターター
  ],
);

保守すべきリストも、アプリケーションに追加すべきアノテーションもありません。発見はビルド時に行われるので、スターターを追加したら、アプリケーションは build_runner をもう一度実行します。モジュールがどのようにソートされ、チェックされるかは 自動構成 にあります。

完全なスターター

例は neon_audit です。AuditSink を通してアプリケーションが行うことを記録し、デフォルトではログに書き、neon.audit.* の下で設定されます。

1. パッケージ

# neon_audit の pubspec.yaml
name: neon_audit
environment:
  sdk: ^3.13.0

dependencies:
  spring_boot_dart: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
  spring_boot_starter_test: ^0.9.0
  test: ^1.33.0

2. Bean とその条件

Bean はアプリケーションと同じように宣言します。@Bean メソッドを持つ @AutoConfiguration クラス (スターター向けの @Configuration) です。条件が、各 Bean がいつ生成されるかを決めます。

// lib/src/audit.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

/// Where audit records go.
abstract interface class AuditSink {
  void record(String event);
}

/// The default sink: the application's log.
class LogAuditSink implements AuditSink {
  LogAuditSink(this.prefix);

  final String prefix;

  @override
  void record(String event) => const SpringLog('neon.audit').info('$prefix$event');
}

@AutoConfiguration()
class AuditAutoConfiguration {
  @Bean()
  // アプリケーション自身の AuditSink が優先される: これは、それがない
  // 場合にだけ生成される。
  @ConditionalOnMissingBean(AuditSink)
  // `neon.audit.enabled=false` でスターターを無効にする。
  @ConditionalOnProperty('neon.audit.enabled', matchIfMissing: true)
  AuditSink auditSink(AuditProperties properties) =>
      LogAuditSink(properties.prefix);
}

@ConditionalOnMissingBean が、スターターを置き換え可能にするものです。アプリケーションの Bean はすべての自動構成より前に登録されるので、条件はそれらを見ます。独自の AuditSink を宣言するアプリケーションは、自分のものだけを得ます。

3. 型付きのプロパティ

// lib/src/audit_properties.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

/// The `neon.audit.*` properties.
@ConfigurationProperties('neon.audit')
class AuditProperties {
  /// Whether the starter records anything.
  bool enabled = true;

  /// Put before every record.
  String prefix = 'audit: ';
}

/// コメントと初期値は、読む人のためだけのものではありません。ジェネレーターはそれらを lib/spring_gen/spring_metadata.json に書き込み、それはパッケージとともに公開されるので、エディターはアプリケーションの application.yml で neon.audit.prefix を補完し、その説明とデフォルトを表示します。エディター向けのメタデータ を参照してください。

4. モジュール

@ComponentScan はそのフォルダーの Bean をモジュールに集め、lib/spring_auto_configuration.dart はそのモジュールをスターターの自動構成として宣言します。ファイル名は決まっています。ジェネレーターが探す場所だからです。

// lib/src/beans.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'package:neon_audit/spring_gen/src/beans.spring.dart';

@ComponentScan()
final BeanModule auditBeans = $auditBeans;
// lib/spring_auto_configuration.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'package:neon_audit/src/beans.dart';

// requires: スターターが動作する spring_boot_dart のバージョン。
@AutoConfigurationModule(requires: '^0.7.0')
final BeanModule neonAuditAutoConfiguration = auditBeans;

requires はアプリケーションのビルド時にチェックされます。範囲外の spring_boot_dart では、ビルドは止まり、使うべきバージョンを示します。@AutoConfigurationModule のその他のオプション:

オプション 効果
requires 互換性のある spring_boot_dart のバージョン。pub のバージョン範囲。null は任意のバージョンを受け付ける
order、before、after その Bean が別のスターターのものに依存する場合の、他のモジュールの中での位置
build アプリケーションのプロパティによって、モジュールをビルドから、またはリリースから外す。デバッグパネルのような開発ツールのため。ビルドから外されるモジュール を参照
platform モジュールを、そのコードが動く場所だけに留める: ModulePlatform.native (dart:io が存在する場所。つまりブラウザーではない)、ModulePlatform.web、または ModulePlatform.server (Dart VM と AOT 実行ファイルだけで、Flutter アプリには決して含まれない。秘密鍵が必要な API のように、アプリに入れてはならないコードのため)。ほかのプラットフォームのビルドには、それが一切含まれない。スターターのサーバー側の半分を native の独立したモジュールに置けば、クライアント側の半分を使うブラウザーアプリはサーバーを持たない。一つのプラットフォームだけのモジュール を参照
factories Bean が一つも存在しないうちに、アプリケーションが型で見つける定数。ファクトリー: Bean より前に動くもの を参照

リポジトリ自身のスターターは、完全な制御のために BeanDefinition を手で書いています。どちらの方法でも同じ種類のモジュールになり、ジェネレーターを使うほうが短く済みます。

5. 生成して公開する

ジェネレーターがファイルを書き出すのはビルドされるパッケージの中だけで、依存関係の中には決して書き出しません。そのため、スターターは自分のコードを生成し、それを公開します。

dart run build_runner build
dart pub publish

lib/spring_gen/ のファイルをパッケージとともにコミットして公開してください。アプリケーションが依存関係の lib/ に対してジェネレーターを実行することはありません。

使う

アプリケーションは依存関係を追加してビルドします。

dependencies:
  neon_audit: ^1.0.0
@Service()
class Checkout {
  Checkout(this.audit);

  final AuditSink audit;   // スターターの Bean。他の Bean と同じように注入される

  void pay(String order) => audit.record('paid $order');
}
# lib/resources/application.yml
neon:
  audit:
    prefix: 'shop: '

そしてデフォルトを置き換えるには、アプリケーションは自分の Bean を宣言します。スターターのものは身を引きます。

@Component()
class DatabaseAuditSink implements AuditSink {
  @override
  void record(String event) { /* ... */ }
}

スターターをテストする

spring_boot_starter_test の ApplicationContextRunner は、与えたモジュールとプロパティだけで、テストごとに小さなコンテキストを起動します。すべてのスターターが持つ三つのケース、デフォルト、身の引き方、スイッチをテストします。

import 'package:neon_audit/spring_auto_configuration.dart';
import 'package:neon_audit/src/audit.dart';
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:test/test.dart';

class MemoryAuditSink implements AuditSink {
  @override
  void record(String event) {}
}

void main() {
  final runner = const ApplicationContextRunner()
      .withAutoConfiguration(neonAuditAutoConfiguration);

  test('a log sink by default', () {
    runner.run((context) {
      expect(context, hasSingleBean<AuditSink>());
      expect(context.getBean<AuditSink>(), isA<LogAuditSink>());
    });
  });

  test("the application's sink wins", () {
    runner.withBean<AuditSink>(MemoryAuditSink.new).run((context) {
      expect(context, hasSingleBean<AuditSink>());
      expect(context.getBean<AuditSink>(), isA<MemoryAuditSink>());
    });
  });

  test('neon.audit.enabled=false switches it off', () {
    runner.withPropertyValues(['neon.audit.enabled=false']).run((context) {
      expect(context, doesNotHaveBean<AuditSink>());
    });
  });
}

ランナーは設定ファイルを読まず、アプリケーションと同じように @ConfigurationProperties をバインドし、with... の呼び出しはそれぞれ新しいランナーを返すので、基本のランナーをテスト間で共有できます。

ファクトリー: Bean より前に動くもの

スターターの Bean が存在するのは、コンテキストが作られてからです。それより前、環境が準備されている間や Flutter アプリがスプラッシュを表示している間に動かなければならないものもあります。Flutter のテーマを読むときに使うデザインライブラリーがその一つです。スプラッシュのテーマは Bean が一つも存在しないうちに読まれるため、デザインのスターターはデザインを Bean として渡せません。

そうしたものがファクトリーです。スターターがそのモジュールに列挙する定数です。

// ocean_design の lib/spring_auto_configuration.dart
import 'package:ocean_design/src/beans.dart';
import 'package:ocean_design/src/ocean_theme_design.dart';
import 'package:spring_boot_dart/spring_boot_dart.dart';

@AutoConfigurationModule(factories: [OceanThemeDesign()])
final BeanModule oceanAutoConfiguration = oceanBeans;

それを必要とするコードは、アプリケーションに型を指定して求めます。SpringApplication.factories.load<T>() は、アプリケーションのモジュールが持つ型 T のファクトリーをすべて返します。Ordered を実装しているものはその順に、そうでなければモジュールの順に並び、どのスターターも持っていなければ空のリストです。

// ApplicationEnvironmentPreparedEvent のリスナーの中で: Bean はまだ一つもない。
final designs = event.springApplication.factories.load<ThemeDesign>();

コンテキストができてからは、同じオブジェクトを springFactories Bean (SpringFactories) として持つので、Bean もファクトリーを読めます。

ジェネレーターがアプリケーションの生成される springApplication に書き込むため、ファクトリーはそれぞれ public な定数でなければなりません。

形 例
リテラルの引数による const コンストラクターの呼び出し OceanThemeDesign()、OceanThemeDesign(contrast: 0.5)
名前付きコンストラクターによる同じもの OceanThemeDesign.dark()
トップレベルの const 変数 oceanThemeDesign
static const フィールド OceanThemeDesign.standard

それ以外の形のファクトリー、たとえば private なクラスや定数は、説明とともにビルドを止めます。アプリケーションがスターターのファクトリーを得るのは、生成されたときです。ファクトリーを持つスターターや、ファクトリーが加わったバージョンを追加したら、build_runner を再実行してください。

ファクトリーは、Bean より前に存在しなければならないものだけにとどめてください。それ以外はすべて Bean のままにします。アプリケーションは Bean を自分のもので置き換えられますが、ファクトリーは置き換えられません。

Spring (Java) では、スターターはそうしたクラスを META-INF/spring.factories に列挙し、Spring がクラスパス上からそれを見つけます。

# META-INF/spring.factories
com.neon.ocean.ThemeDesign=com.neon.ocean.OceanThemeDesign
List<ThemeDesign> designs =
    SpringFactoriesLoader.loadFactories(ThemeDesign.class, classLoader);

Dart にはスキャンするクラスパスがないため、ジェネレーターが定数をアプリケーションにコピーします。ファクトリー と 自動構成 を参照してください。

知っておくとよいこと