
# spring_boot_starter_flutter

`spring_boot_starter_flutter` は Spring Boot を Flutter アプリに持ち込みます。サービスとアプリの状態を、`@Component()` を付けた普通のクラスとして書きます。フレームワークはそれぞれのオブジェクト、つまり **Bean** を一つずつ作り、それらを結び付けます。別の Bean を必要とする Bean は、コンストラクターでそれを求めます。すべての Bean は、アプリの起動とともに起動する**アプリケーションコンテキスト**の中にあります。スターターはそのコンテキストをウィジェットツリーに置くため、どのウィジェットも必要な Bean を取得でき、Bean の状態を表示するウィジェットは、それが変わると再構築されます。

使うのに Spring を知っている必要はありません。知っていれば、同じモデルが見つかります: `@Component`、`@Value`、`@ConfigurationProperties`、プロファイル、イベント、`application.yml` です。

## 使う理由

Flutter アプリには、サービスと共有の状態を置く標準の場所がありません。アプリごとに状態ライブラリを選び、コンストラクターでオブジェクトを渡し、設定を Dart のコードに置きます。スターターはそのすべてに一つのモデルを与えます。

- **状態とサービスは Bean です。** ウィジェットは必要な Bean を型に列挙し、`build` でそれを受け取ります。`Provider` のツリーも、コンストラクターの連鎖もありません。
- **状態の Bean は自分で通知します。** `@ChangeNotifierComponent()` を付けたクラスに `notifyListeners()` の呼び出しは不要です。生成されたプロキシが、すべてのメソッドの後にそれを行います。
- **アプリは設定です。** アプリのウィジェット (`WidgetsApp`、またはデザインのスターターによる `MaterialApp` と `CupertinoApp`)、そのタイトル、言語、テーマ、スプラッシュ画面、キーボードショートカットは、コードではなく `application.yml` に書きます。
- **プラットフォームはプロファイルです。** `application-ios.yml` は iPhone でだけ、`application-release.yml` はリリースビルドでだけ読まれ、`@Profile(['android'])` を付けた Bean は Android にだけ存在します。
- **アプリはそのライフサイクルに従います。** バックグラウンドでは `@Scheduled` のタスクと WebSocket の接続が止まり、アプリが戻ると再び始まります。
- **Bean を変更したホットリロードは、新しいコードでコンテキストを再起動します。**

## セットアップ

```yaml
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  spring_boot_starter_flutter: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # 必須: アプリケーションを書き出す
  flutter_test:
    sdk: flutter
  spring_boot_starter_test: ^0.9.0     # テストのための springBootTest と BeanOverride
```

その後:

1. `lib/main.dart` の `main` に `@SpringBootApplication()` を付けます。
2. `dart run build_runner watch` (または `build`) を実行します。ジェネレーターは `lib/spring_gen/main.spring.dart` に `springApplication` を書き出します。これは `lib/` の下で見つかったすべての Bean を持つアプリケーションです。作業中は `watch` を動かしたままにしてください。
3. 設定ファイルとメッセージファイルを `lib/resources/` に置きます。ジェネレーターはそれらを生成コードに埋め込むため、`flutter: assets:` のエントリーは不要です。

Flutter のパッケージには Flutter 3.50 以降 (Dart 3.14) が必要です。

スターターはデザインライブラリを持ちません。インポートするのは `package:flutter/widgets.dart` だけで、デフォルトの型 `widgets` のアプリのビルドには Material も Cupertino も入りません。Material や Cupertino のウィジェットを使うアプリは、[spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) または [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md) と、`material_ui` または `cupertino_ui` を追加します。[デザインライブラリ](design-libraries.md)を参照してください。

インポートは一つで足ります。`package:spring_boot_starter_flutter/spring_boot_starter_flutter.dart` は、`spring_core_dart`、`spring_boot_dart`、`spring_web_dart` (HTTP クライアント)、`spring_boot_starter_logging` もエクスポートします。Flutter が独自のものを持つため、二つの名前が除かれています。Boot の起動時の `Banner` (Flutter には `Banner` ウィジェットがあります) と、バリデーションの制約 `Size` (`dart:ui` に `Size` があります) で、後者は `SizeConstraint` としてエクスポートされます。

## 例

完全なカウンターアプリです。Material の `Scaffold`、`FloatingActionButton`、`Icons` を使うため、Material のスターターと `material_ui` を追加します。

```yaml
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  material_ui: ^1.11.0
  spring_boot_starter_flutter_material: ^0.9.0   # spring_boot_starter_flutter を連れてくる
```

```dart
// lib/main.dart
import 'package:material_ui/material_ui.dart';
import 'package:spring_boot_starter_flutter_material/spring_boot_starter_flutter_material.dart';

import 'spring_gen/main.spring.dart'; // ジェネレーターが書き出す

@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    // その周りのアプリのウィジェットは spring.flutter.app.* から組み立てられる。
    home: const CounterPage(),
  ),
);

// カウントは State ではなく Bean: どのウィジェットやサービスも読み、
// 変更できる。生成されたプロキシがすべてのメソッドの後にリスナーに通知する。
@ChangeNotifierComponent()
class Counter {
  int value = 0;
  void increment() => value++;
}

// 必要な Bean を型に列挙し、それを `beans` として受け取る。
class CounterPage extends SpringStatelessWidget<(Counter,)> {
  const CounterPage({super.key});

  @override
  Widget build(BuildContext context) {
    final (counter,) = beans;
    return Scaffold(
      body: const Center(child: CounterText()),
      // メソッドを呼ぶだけなので、タップでページは再構築されない。
      floatingActionButton: FloatingActionButton(
        onPressed: counter.increment,
        child: const Icon(Icons.add),
      ),
    );
  }
}

// build で counter.value を読むので、increment のたびに再構築される。
class CounterText extends SpringStatelessWidget<(Counter,)> {
  const CounterText({super.key});

  @override
  Widget build(BuildContext context) {
    final (counter,) = beans;
    return Text('${counter.value}');
  }
}
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    app:
      # type は不要: Scaffold には MaterialApp が必要で、唯一のデザインのスターター
      # spring_boot_starter_flutter_material がアプリをそれにする
      title: Counter
    theme:
      seed-color: deepPurple
```

## 実行する

```bash
dart run build_runner watch   # lib/spring_gen/main.spring.dart を書き出す
flutter run
```

起動時に起きること:

- `SpringApplicationWidget` はスプラッシュを表示し、設定ファイルを読み、プラットフォームとビルドのプロファイルを追加し、アセットの中のフォントを読み込み、Bean を作ります。
- Spring のウィジェットが必要とするすべての Bean が存在するかをチェックします。そのため、存在しない Bean は後の `build` ではなく起動を失敗させます。
- コンテキストの準備ができると、`spring.flutter.app.*` からアプリのウィジェットを、`spring.flutter.theme.*` からテーマを組み立て、`home` を表示します。
- ロギングは起動時から、Spring Boot の形式で、コンソールとメモリ上の `LogBuffer` Bean に出力されます。

```text
INFO 82749 --- [main] spring_boot_dart.SpringApplication : The following 3 profiles are active: "desktop", "macos", "debug"
```

## 内容

はじめに:

- [Flutter アプリでの設定](configuration.md): ファイル、プラットフォームとビルドのプロファイル、インポート、`--dart-define`、リモートのファイル。
- [SpringApplicationWidget](application-widget.md): アプリケーションを起動するルートのウィジェット。
- [アプリのウィジェット](app-widget.md): `spring.flutter.app.*` からの `WidgetsApp`、`MaterialApp`、`CupertinoApp`。
- [デザインライブラリ](design-libraries.md): デザインライブラリのないアプリと、スターターによる Material や Cupertino。

Bean と状態:

- [ウィジェットの中の Bean](beans-in-widgets.md): `SpringStatelessWidget`、`SpringStatefulWidget`、`context.bean`、`@BuildContextAccess`。
- [状態の Bean](state-beans.md): `@ChangeNotifierComponent` と `@NotifyListeners`。
- [メッセージと言語](messages.md): `context.message`、型付きの `context.messages`、アプリのロケール。
- [アプリのライフサイクル](lifecycle.md): ライフサイクルのイベントとバックグラウンドでの一時停止。
- [ホットリロード](hot-reload.md): コンテキストが再起動する場合と、そのままの場合。

テーマ:

- [テーマ](themes/index.md): アプリの見た目のすべてを YAML で。色、タイポグラフィ、コンポーネント、状態、モーション、背景、画像、ローダー、Cupertino のページがあります。

起動とツール:

- [スプラッシュと起動](splash.md): ステージ、スプラッシュのタスク、起動中のフレーム、フォントのウォームアップ、トレース。
- [キーボードショートカットとタップ](shortcuts.md): 設定でキーやタップのパターンに割り当てるアクション。
- [デバッグパネル](debug-panel.md): 実行中のアプリのログ、フレーム、設定、Bean、テーマ、起動。
- [フレームメーター](frame-meter.md): アプリが実際に描画する毎秒のフレーム数。

コンテンツとファイル:

- [MarkdownView](markdown.md): テーマの色、表、コードブロック、コールアウトを使う GitHub Markdown。
- [アセットとフォント](assets-and-fonts.md): `asset:` のリソースと、アセットから読み込むフォント。
- [アプリのファイル](files.md): アプリ自身のファイルのための `FileTemplate`。
- [SQLite データベース](sqlite.md): アプリのディレクトリにあり、専用の isolate で動くデータベース。

プラットフォーム:

- [デスクトップのウィンドウ](desktop-window.md): ウィンドウのタイトル、タイトルバー、サイズ。
- [Web](web.md): アプリを囲むページ、ページのローダー、開発サーバー、フォント、アセット、WebAssembly。
- [SEO](seo.md): 検索エンジンとリンクのプレビューのためのアドレスごとのページ、サイトマップ、llms.txt。

リファレンス:

- [テスト](testing.md): `flutter_test` での `springBootTest`、フェイク、ゴールデン。
- [すべてのプロパティ](properties.md): スターターのすべてのキー。
- [Spring との違い](differences.md): Spring Boot と動作が異なる点。
- [0.8 への移行](moving-to-0-8.md): Flutter 3.50、デザインのスターター、アプリにとって変わったこと。

## Spring (Java) との対応

Spring にはウィジェットツリーがありません。`SpringApplicationWidget` に最も近いものは、Spring Boot アプリの `main` メソッドです。

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

重要な違い:

- `@SpringBootApplication()` は `main` 関数に付け、ジェネレーターがビルド時にアプリケーションを書き出します。アノテーションを変更したら `build_runner` を実行してください。
- ウィジェットは Bean ではありません。Flutter が作ります。ウィジェットは注入ではなく、その型 (`SpringStatelessWidget<(Basket,)>`) を通じて Bean を受け取ります。
- プラットフォームとビルドモードは、それ自体がアクティブなプロファイルです。
- すべての違いは [Spring との違い](differences.md) にあります。

## 関連項目

- [spring_core_dart](../spring-core-dart/index.md)
- [設定](../spring-core-dart/config/index.md)
- [Flutter のためのジェネレーター](../spring-core-dart-generator/flutter/index.md)
- [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md)
- [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md)
- [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
- [ビルドに含まれるもの](optimizations.md)
