spring_boot_dart

spring_boot_dart は、Spring for Dart のうちアプリケーションを起動する部分です。Spring Boot の SpringApplication、その外部設定、@ConfigurationProperties のバインド、そして自動構成を Dart に移植したものです。

spring_core_dart だけでも Bean のコンテナは手に入りますが、起動処理は自分で書くことになります。設定ファイルを読み、コンテキストを生成し、ログレベルを設定し、起動時の処理を実行します。spring_boot_dart は、main に付けた一つのアノテーションでそのすべてを行います。

使う理由

どのアプリケーションにも同じ起動コードが必要で、しかも間違えやすいものです。

spring_boot_dart は、これらすべてを Spring Boot の名前とルールで提供します。そのため、Spring プロジェクトの設定や習慣をそのまま持ち込めます。サーバーでも、コマンドラインツールでも、Flutter アプリでも、Dart VM、AOT ビルド、Web のいずれでも同じように動きます。

セットアップ

# pubspec.yaml
dependencies:
  spring_boot_dart: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # 必須: パッケージをスキャンする

spring_boot_dart は spring_core_dart をエクスポートするため、インポートは一つで足ります。それ以外には何にも依存しません。ほとんどのアプリケーションはこれを直接追加しません。すべてのスターター (spring_boot_starter_web、spring_boot_starter_flutter、...) がこれに依存し、エクスポートしているためです。

例

型付きの設定、起動時のタスク、プロファイルを持つ完全なアプリケーションです。

// bin/main.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

import 'spring_gen/main.spring.dart'; // build_runner が書き出す

// shop.* の下のすべてのキーを、型付きで検証済みの一つのオブジェクトに。
@ConfigurationProperties('shop')
@Validated()
class ShopProperties {
  @NotBlank()
  String name = 'NEON Books';

  Duration deliveryTime = const Duration(days: 3); // shop.delivery-time=2d

  @Min(1)
  int maxBasketSize = 10; // shop.max-basket-size
}

// アプリケーションの起動後に一度実行される。
@Component()
@Log()
class Greeting implements ApplicationRunner {
  Greeting(this.shop);

  final ShopProperties shop;

  @override
  void run(ApplicationArguments args) =>
      log.info('${shop.name} is open, ${shop.maxBasketSize} books per basket');
}

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
# lib/resources/application.yml
spring:
  application:
    name: neon-books
shop:
  max-basket-size: 20
logging:
  level:
    root: info
# lib/resources/application-prod.yml: prod プロファイルのときだけ読まれる
shop:
  max-basket-size: 50

実行する

dart run build_runner build          # bin/spring_gen/main.spring.dart を書き出す
dart run bin/main.dart               # max-basket-size 20
dart run bin/main.dart --spring.profiles.active=prod   # 50
SHOP_MAXBASKETSIZE=30 dart run bin/main.dart           # 30: 環境変数がファイルより優先される

起動時のログ (INFO):

Starting neon-books using Dart 3.13.5 with PID 4242
No active profile set, falling back to 1 default profile: "default"
Started neon-books in 0.07 seconds
NEON Books is open, 20 books per basket

shop.max-basket-size=0 ではアプリケーションは起動しません。キーを示すレポートを出力します。

***************************
APPLICATION FAILED TO START
***************************

Description:

Binding to target properties under 'shop' failed:

  - shop.max-basket-size: must be greater than or equal to 1 (was "0")

Action:

Update the application's configuration (lib/resources/application.properties, command line or environment).

仕組み

Dart には実行時のリフレクションがないため、スキャンはビルド時に行われます。dart run build_runner build はパッケージ全体 (lib/ と main のディレクトリ。書くべき @ComponentScan はありません) を読み、次のものを含む spring_gen/main.spring.dart を生成します。

その後 runApplication(args) が、Spring Boot の SpringApplication.run と同じことを行います。その手順は SpringApplication にあります。

内容

起動:

外部設定:

自動構成:

リファレンス:

Spring (Java) との対応

@SpringBootApplication
public class NeonBooks {
  public static void main(String[] args) {
    SpringApplication.run(NeonBooks.class, args);
  }
}

重要な違い:

関連項目