
# 独自のスターター

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

## 使う理由

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

- アプリケーションは依存関係を一つ追加するだけで、動く Bean を得ます。
- 設定は `application.yml` の一つのプレフィックスの下にあり、型付けされ、エディター向けに説明が付いています。
- 別のものを必要とするアプリケーションは自分の Bean を宣言し、スターターのものは身を引きます。

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

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

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

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

## 完全なスターター

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

### 1. パッケージ

```yaml
# 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 がいつ生成されるかを決めます。

```dart
// 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. 型付きのプロパティ

```dart
// 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` を補完し、その説明とデフォルトを表示します。[エディター向けのメタデータ](../components/spring-core-dart-generator/metadata.md) を参照してください。

### 4. モジュール

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

```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;
```

```dart
// 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` | アプリケーションのプロパティによって、モジュールをビルドから、またはリリースから外す。デバッグパネルのような開発ツールのため。[ビルドから外されるモジュール](../components/spring-core-dart-generator/optimizations/build-conditions.md) を参照 |
| `platform` | モジュールを、そのコードが動く場所だけに留める: `ModulePlatform.native` (`dart:io` が存在する場所。つまりブラウザーではない)、`ModulePlatform.web`、または `ModulePlatform.server` (Dart VM と AOT 実行ファイルだけで、Flutter アプリには決して含まれない。秘密鍵が必要な API のように、アプリに入れてはならないコードのため)。ほかのプラットフォームのビルドには、それが一切含まれない。スターターのサーバー側の半分を `native` の独立したモジュールに置けば、クライアント側の半分を使うブラウザーアプリはサーバーを持たない。[一つのプラットフォームだけのモジュール](../components/spring-core-dart-generator/optimizations/build-conditions.md#一つのプラットフォームだけのモジュール) を参照 |
| `factories` | Bean が一つも存在しないうちに、アプリケーションが型で見つける定数。[ファクトリー: Bean より前に動くもの](#ファクトリー-bean-より前に動くもの) を参照 |

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

### 5. 生成して公開する

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

```bash
dart run build_runner build
dart pub publish
```

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

## 使う

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

```yaml
dependencies:
  neon_audit: ^1.0.0
```

```dart
@Service()
class Checkout {
  Checkout(this.audit);

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

  void pay(String order) => audit.record('paid $order');
}
```

```yaml
# lib/resources/application.yml
neon:
  audit:
    prefix: 'shop: '
```

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

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

## スターターをテストする

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

```dart
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 として渡せません。

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

```dart
// 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` を実装しているものはその順に、そうでなければモジュールの順に並び、どのスターターも持っていなければ空のリストです。

```dart
// 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 がクラスパス上からそれを見つけます。

```properties
# META-INF/spring.factories
com.neon.ocean.ThemeDesign=com.neon.ocean.OceanThemeDesign
```

```java
List<ThemeDesign> designs =
    SpringFactoriesLoader.loadFactories(ThemeDesign.class, classLoader);
```

Dart にはスキャンするクラスパスがないため、ジェネレーターが定数をアプリケーションにコピーします。[ファクトリー](../components/spring-boot-dart/auto-configuration.md#ファクトリー) と [自動構成](../components/spring-core-dart-generator/auto-configurations.md) を参照してください。

## 知っておくとよいこと

- **`@SpringBootApplication` の場合のみ。** コンテキストを手で組み立てるアプリケーションは、モジュールを自分で列挙します。
- **一つのコンテキスト。** スターターの Bean は、アプリケーション自身の Bean や他のすべてのスターターの Bean と並んで、アプリケーションのコンテキストに入ります。互いに注入し合えます。[すべてのスターターのための一つのコンテキスト](shared-context.md) を参照してください。
- **幅の広い制約。** スターターのサードパーティーのバージョン制約は幅広く保ちます (`dio: '>=5.0.0 <7.0.0'`)。そうすれば、アプリケーションは他のスターターと一緒にそれらを解決できます。
- **追加したら再ビルド。** `build_runner` が再び実行されるまで、アプリケーションの生成ファイルは新しいスターターを知りません。
