Flutter

spring_boot_starter_flutter を使うアプリに対して、ジェネレーターはウィジェットをアプリケーションコンテキストに結び付けるコードを書き出します。ウィジェットは Bean ではありません。Flutter が自身のコンストラクターでそれらを生成するので、何もそこに注入できません。生成コードは、ジェネレーターがコードから読んだアノテーションと型をもとに、ビルド時にその隙間を埋めます。

ジェネレーターは Flutter のスターターに依存しません。他のスターターのアノテーションを認識するのと同じく、スターターのアノテーションとクラスをその URL (たとえば package:spring_boot_starter_flutter/src/annotations.dart#BuildContextAccess) で認識します。それらを何も使わないモジュールの .spring.dart ファイルには、Flutter 固有のものは何も入りません。

使う理由

ウィジェットのコードには Bean が必要です。バスケット、セッション、現在の言語です。生成コードがなければ、ウィジェットは実行時に各 Bean を型で検索します (context.bean<Basket>())。それでも動きますが、次の問題があります。

ジェネレーターはこの作業をビルドに移します。Bean の型付きゲッターを書き、ウィジェットの Bean レコードに値を入れ、ウィジェットが必要とするすべての Bean が存在することをアプリが起動時にチェックできるようにし、代わりにリスナーに通知するプロキシを書き出します。

認識するもの

コード中のもの ビルドが書き出すもの 場所
Bean クラスまたは @Bean メソッドの @BuildContextAccess() extension SpringBeans on BuildContext のゲッター モジュールの .spring.dart
SpringStatelessWidget<R> を継承するクラス、または SpringState<W, R> を継承する State モジュールの SpringWidgetBindings Bean の中のバインディング モジュールの Bean のリスト
@ChangeNotifierComponent() または @NotifyListeners() リスナーに通知するプロキシクラス (前者では ChangeNotifier も mixin する) モジュールの .spring.dart
ローダークラスの @ThemeLoaderKind('name') ThemeLoaderKinds への登録 モジュールのゲッター
@ScreenRoute(...) と @RouteShell(...) のウィジェット (spring_boot_starter_flutter_navigation) ScreenRoutes Bean と、画面ごとに一つのルートの拡張 モジュールの .spring.dart
spring.flutter.theme.* と messages*.properties context.theme と context.messages lib/spring_gen/theme.spring.keys.dart、lib/spring_gen/messages.spring.keys.dart

モジュールとは @SpringBootApplication または @ComponentScan のライブラリのことで、その .spring.dart ファイルは、メインのビルダーが spring_gen/ の中でその隣に書き出すもの (lib/spring_gen/main.spring.dart など) です。ウィジェットは、ゲッターと拡張を使うためにそのファイルをインポートします。

以下のコードの抜粋は、実際の生成ファイルから取ったものです。読みやすくするため、_i10. のようなインポートのプレフィックスは外しています。

@BuildContextAccess: Bean ごとのゲッター

Bean に @BuildContextAccess() を付けると、SpringApplicationWidget の下のすべてのウィジェットが context.<name> でそれに到達できます。

// lib/src/basket/basket.dart
@ChangeNotifierComponent()
@BuildContextAccess()
class Basket {
  Basket(this._shop);
  // ...
}

ビルドはモジュールごとに一つの拡張を書き出し、示された Bean ごとにゲッターを持たせます。

// lib/spring_gen/main.spring.dart (生成)

/// Getters for the `@BuildContextAccess` beans, for widgets below `SpringApplicationWidget`.
extension SpringBeans on BuildContext {
  /// The bean 'session'.
  Session get session =>
      SpringScope.beanOf<Session>(this, qualifier: r'session');

  // ...

  /// The bean 'basket'.
  Basket get basket =>
      SpringScope.beanOf<Basket>(this, qualifier: r'basket');
}
// ウィジェットの中で:
Text('${context.basket.count}');

ゲッターの作られ方:

  1. その名前 は Bean の名前 (クラス Basket なら basket)、または指定した名前です: @BuildContextAccess(name: 'cart')。
  2. その型 は Bean が知られている型です。クラスの Bean ではクラス、@Bean メソッドでは宣言された戻り値の型 (メソッドの本体から推論される型は private な、またはより狭いクラスかもしれないため)、FactoryBean では生成物の型です。
  3. その本体 は SpringScope.beanOf<T>(this, qualifier: '<bean name>') で Bean を検索します。Bean 名が修飾子なので、他の Bean が同じ型を共有していても、ゲッターはこの Bean を正確に見つけます。

@BuildContextAccess は、クラスにも、Bean を生成する @Bean メソッドにも付けられます。

エラー

ビルドはモジュールのすべての不正なゲッターを集め、まとめて報告します。各エラーは Bean とそのソースを示し、修正方法で終わります。

問題 メッセージの例
名前が Dart の識別子でない @BuildContextAccess(name: 'my-cart') on ...: 'my-cart' is not a valid Dart identifier for a getter. Choose another name.
名前が private ...: '_cart' is private, so widgets could not use the getter.
名前が予約語 @BuildContextAccess on bean 'default' (...): 'default' is a reserved word. Give the getter a name: @BuildContextAccess(name: 'myGetter').
名前が BuildContext、Object、スターターの SpringBuildContext のメンバー ...: 'size' clashes with BuildContext.size, which a generated getter cannot replace.
二つの Bean が同じゲッターになる ...: the getter 'cart' is already generated for bean 'cart' (...). Give one of them another name with @BuildContextAccess(name: '...').
クラスが Bean でない @BuildContextAccess on Basket, which is no bean of this application: add @Component() (or another stereotype), or put @BuildContextAccess on the @Bean method that creates it.

ゲッターに使えないメンバーは、BuildContext のもの (widget、owner、mounted、size、findRenderObject、dependOn...、find...、visit...、describe... のメソッドなど)、Object のもの (hashCode、runtimeType、toString、noSuchMethod)、SpringBuildContext のもの (springContext、bean、message) です。そのような名前の拡張ゲッターは本物のメンバーに隠されてしまうので、ビルドはそれを拒否します。

Bean を持つウィジェット

ウィジェットは必要な Bean をレコード型で指定し、build の中で beans からそれらを読みます。

// lib/src/basket/basket_badge.dart
class BasketBadge extends SpringStatelessWidget<(Basket,)> {
  const BasketBadge({super.key});

  @override
  Widget build(BuildContext context) {
    final (basket,) = beans;
    final count = basket.count; // build の中で読む: バスケットが通知するとバッジが再ビルドされる
    return Badge(
      isLabelVisible: count > 0,
      label: Text('$count'),
      child: const Icon(Icons.shopping_basket_outlined),
    );
  }
}

// Bean が多い場合は、typedef でクラスの行を短く保つ。
typedef SettingsPageBeans = (
  ThemeSelection,
  SpringThemes,
  LanguageSelection,
  AppAssets,
);

class SettingsPage extends SpringStatelessWidget<SettingsPageBeans> { ... }

// ステートフルウィジェット: State が Bean を受け取る。
class _CatalogPageState extends SpringState<CatalogPage, (Catalog,)> { ... }

レコードに値を入れるには各フィールドを指定するコードが必要で、Dart には実行時にそれを行うリフレクションがありません。そこでビルドは、レコード型ごとに バインディング を書き出します。モジュールのすべてのバインディングは一つの Bean SpringWidgetBindings にまとめられます。

// lib/spring_gen/main.spring.dart (生成)、モジュールの Bean のリストの中
BeanDefinition<SpringWidgetBindings>(
  name: r'flutterSpringWidgetBindings#application',
  source: r'package:spring_boot_starter_flutter/spring_boot_starter_flutter.dart#SpringWidgetBindings',
  autowireCandidate: false,
  create: (r) => SpringWidgetBindings([
    SpringWidgetBinding(
      widget: r'package:neon_books_app/src/settings/settings_page.dart#SettingsPage',
      beans: SettingsPageBeans,
      types: const [ThemeSelection, SpringThemes, LanguageSelection, AppAssets],
      resolve: (f) => (
        SpringWidgetBinding.bean<ThemeSelection>(f),
        SpringWidgetBinding.bean<SpringThemes>(f),
        SpringWidgetBinding.bean<LanguageSelection>(f),
        SpringWidgetBinding.bean<AppAssets>(f),
      ),
      values: (r) {
        final v = (r as (ThemeSelection, SpringThemes, LanguageSelection, AppAssets));
        return [v.$1, v.$2, v.$3, v.$4];
      },
    ),
    // ... レコード型ごとに一つのバインディング
  ]),
),

各部分の役割:

フィールド 役割
widget レコードを宣言したクラス (package:<app>/<file>.dart#<Class>)。エラーメッセージ用。
beans Type 値としてのレコード型。ウィジェットはこの型でバインディングを見つけます。(Basket,) のようにインラインで書かれたレコードは、レコード型を素の型リテラルとして書けないため、生成された _$typeOf<(Basket,)>() ヘルパーを通して書かれます。
types 存在しなければならない Bean の型。非 nullable なフィールドのものです。SpringApplicationWidget は起動時にそれらをチェックします。
resolve Bean ファクトリーからレコードに値を入れます。
values 値の入ったレコードの Bean を列挙し、ウィジェットが Listenable なものを購読できるようにします。

Bean の名前は flutterSpringWidgetBindings#<module> で、オートワイヤーの候補ではありません。どの Bean も注入でそれを受け取れません。スターターは getBeansOfType でそれを見つけます。

各フィールドへの値の入れ方

レコードのフィールド 生成される呼び出し 実行時
位置、非 nullable: (Basket,) SpringWidgetBinding.bean<Basket>(f) その型の Bean。存在しない場合、または複数あってどれもプライマリーでない場合は失敗する。
名前付き、非 nullable: ({Clock clock}) SpringWidgetBinding.bean<Clock>(f, 'clock') その型の Bean。複数の Bean がその型を持ち、どれもプライマリーでない場合は、名前がフィールド名と同じもの。
nullable: (Basket?,) f.findBean<Basket>() Bean、または null。起動時にはチェックされない。

レコード型ごとに一つのバインディング

ウィジェットはレコード型でバインディングを見つけるので、同じレコードを持つ二つのウィジェットは一つのバインディングを共有します。ビルドはそれを、最初にスキャンしたウィジェットの名前で一度だけ書き出します。BasketBadge と、どちらも (Basket,) を宣言する別のウィジェットは、同じコードを使います。

起動時のチェック

コンテキストが起動した後、SpringApplicationWidget はすべてのバインディングを調べ、types の各型について Bean が存在することをチェックします。足りない Bean があると、ウィジェットが最初にビルドされるときに後で失敗する代わりに、ウィジェットを示す NoSuchBeanDefinitionException で起動が止まります。

ウィジェットのレコードに実行時にバインディングがない場合 (ウィジェットを書いた後にジェネレーターが実行されなかった)、最初のビルドで FlutterError が投げられます: No generated beans for BasketBadge ((Basket,)).。dart run build_runner build を実行するようにとのヒントと、レコード型を変更した後はホットリスタートが必要な場合があることも示されます。

エラー

問題 メッセージ
型引数がレコードでない、または nullable なレコード SpringStatelessWidget BasketBadge: its beans must be a record of bean types, like SpringStatelessWidget<(Basket, AppNavigator)>, not Basket.
フィールドがクラス型やインターフェース型でない (dynamic、Object、Function、Null、レコード、関数型) SpringStatelessWidget BasketBadge: Object (positional field of (Object,)) is not a bean type; every field of the record must be a class or interface type (nullable for an optional bean).

レコードがまだ型パラメーターである抽象クラス (abstract class MyBase<R extends Record> extends SpringStatelessWidget<R> のような基底クラス) はスキップされ、その具象サブクラスがバインディングを受け取ります。レコードが型パラメーターである具象クラスは、最初のエラーで失敗します。

@ChangeNotifierComponent と @NotifyListeners

状態の Bean は、変化したときにウィジェットに伝えなければなりません。スターターの二つのアノテーションは、生成されたプロキシにそれを任せます。

ゲッターは決して通知しません。Future を返すメソッドでは、Future が完了したときにリスナーに通知されます。メソッドが例外を投げた場合も通知されます。

上の Basket のプロキシです (private なメンバーを持つクラスなので、プロキシはサブクラスです)。

// lib/spring_gen/main.spring.dart (生成)
/// Basket: `@ChangeNotifierComponent()`
class _$BasketProxy extends Basket with ChangeNotifier, AdvisedSubclass {
  _$BasketProxy(super.p0);

  /// add: `@ChangeNotifierComponent()`
  @override
  Future<void> add(Book book) {
    final _$invoker = this.aopInvoker;
    return _$invoker == null
        ? super.add(book)
        : _$invoker.invokeAsync<void>(
            proxy: this,
            target: this,
            methodIndex: 0,
            arguments: [book],
            original: (args) => super.add((args[0] as Book)),
          );
  }
  // ... その他のすべてのメンバー
}

通知そのものは、@Transactional と同じくアドバイスです。スターターは、ポイントカットが二つのアノテーションに一致する二つのアドバイザーを登録し、プロキシは各呼び出しをそれらに通します。

そのため、プロキシはゲッターもオーバーライドします。コンテナが渡す Bean は、コンパイラーから見てクラス Basket が Listenable でなくても、Listenable です。Spring のウィジェットは自分でそれを購読します。それ以外の場所では、listenableOf(bean) がそれに Listenable の型を与えます。

これらのプロキシは常に生成されます。ビルドが AOP プロキシを刈り込む とき、@ChangeNotifierComponent クラスのプロキシを取り除いたり遅延したりすることはありません。それがなければ、Bean はそもそも ChangeNotifier にならないからです。@NotifyListeners を持つ Bean は、スターターのポイントカットが一致するアノテーションを宣言している (static const annotationTypes) ので、ビルドはそれらが適用されることを知り、プロキシを保ちます。

エラー

問題 メッセージ
exclude の名前が、クラスの (自身の、または継承した) public なメソッド、セッター、フィールドでない @ChangeNotifierComponent on Counter: exclude names rest, which is no public method, setter or field of Counter.
ChangeNotifier でない @ChangeNotifierComponent クラスが、addListener、removeListener、dispose、notifyListeners、hasListeners を宣言している @ChangeNotifierComponent on Counter: dispose would clash with the ChangeNotifier its proxy mixes in; rename it, or let Counter extend ChangeNotifier.

最初のチェックがなければ、exclude のタイプミスは黙って何も除外しないことになります。

アプリ独自のローダーの種類

テーマはローダーを種類で指定します。spinner、dots、pulse、bar、skeleton は組み込みです。@ThemeLoaderKind('doors') で示され、ThemeLoaderPainter<P> または ThemeLoaderWidget<P> を継承するクラスは、種類を追加します。モジュールは、モジュールが組み立てられる前にそのゲッターの中でそれを登録するので、テーマが読まれるときにはその種類が見つかります。

// lib/spring_gen/main.spring.dart (生成)
BeanModule get $application {
  ThemeLoaderKinds.register<SpringLeafLoaderProps>(
    r'spring-leaf',
    widget: SpringLeafLoader(),
    props: SpringLeafLoaderProps._,
    keys: SpringLeafLoaderProps.keys,
  );
  return BeanModule(r'application', [/* Bean */]);
}

SpringLeafLoader は ThemeLoaderWidget なので widget: として渡されます。ThemeLoaderPainter は painter: として渡されます。props クラス SpringLeafLoaderProps は、テーマがその種類のローダーに与えるキーから、型付きキーのビルダーが書き出します。型付きキー を参照してください。クラスが生成された props クラスの代わりに LoaderValues を受け取る場合、登録には props: と keys: がありません。

次の場合、ビルドは失敗します。

画面とルート

spring_boot_starter_flutter_navigation では、@ScreenRoute('/path') で示されたウィジェットは画面になり、@RouteShell(branches: [...]) で示されたものはブランチごとのスタックを持つシェルになります。ビルドはそれらを、アプリが手で使うのと同じビルダーで書かれた、モジュールごとに一つの ScreenRoutes Bean にまとめます。

// 入力
@ScreenRoute('/components/{*path}', title: '#{docs.title}', content: 'resources:content/components/')
class DocsPage extends StatelessWidget {
  const DocsPage({super.key});
  // ...
}
// lib/spring_gen/main.spring.dart (生成)、モジュールの Bean のリストの中
BeanDefinition<ScreenRoutes>(
  name: r'screenRoutes#application',
  source: r'package:spring_boot_starter_flutter_navigation/spring_boot_starter_flutter_navigation.dart#ScreenRoutes',
  create: (r) => ScreenRoutes.route(source: r'application')
      .screen(
        r'/components/{*path}',
        (r) => const DocsPage(),
        name: r'docs-page',
        title: r'#{docs.title}',
        content: r'resources:content/components/',
        source: r'package:neon_farum_azula/src/pages/docs/docs_page.dart#DocsPage',
      )
      // ... その他の画面
      .notFound((r) => const NotFoundPage())
      .build(),
),

見つからない場合の画面を除く各画面は、その定数と型付きの to(...) を持つ拡張も受け取ります。

// lib/spring_gen/main.spring.dart (生成)

/// The route of [DocsPage]: its path, name, values and `to`.
extension DocsPageRoute on DocsPage {
  /// The path pattern.
  static const pattern = r'/components/{*path}';

  /// The route's name.
  static const routeName = r'docs-page';

  /// The path variable `path`.
  static const path = RouteVar<String>(r'path');

  /// The location of this screen with these values.
  static RouteLocation to({required String path}) =>
      RouteLocation.expand(pattern, pathVariables: {r'path': path});
}

拡張には、パス変数ごとの RouteVar<String>、params: {'page': int} で宣言されたクエリパラメーターごとの RouteParam<T>、extra: のための RouteExtra<T>、そしてパス変数ごとに必須の String、パラメーターごとに省略可能な値を取る to(...) があります。名前を変えたパス、変数、パラメーターは、それを使うコードをコンパイル時に壊します。

ビルドが適用するルール:

次の場合、ビルドは失敗します。@ScreenRoute や @RouteShell を持つクラスがウィジェットでない、または両方を持つ。画面が必須パラメーターのない無名コンストラクターを持たない (ルーターがそれを生成し、画面は値を context.route から読むため)。シェルの無名コンストラクターがその ShellState を唯一の必須パラメーターとして取らない、ブランチを宣言していない、またはブランチが変数なしの / で始まるパスでない。パスが / で始まらない、波括弧の対応が取れていない、末尾以外に {*rest} がある、または同じ変数が二度ある。クエリパラメーターがパス変数と同じ名前を持つ。モジュールの二つの画面が同じパスを宣言している、または二つが見つからない場合の画面である。

画面とシェルは spring_metadata.json (routes、shells) にも列挙されます。エディター向けのメタデータ を参照してください。

Flutter のビルダー

メインのビルダーの他に、五つのビルダーが Flutter アプリに役立ちます。それぞれ、読むものを使わないパッケージには何も書き出さず、それぞれ独自のページがあります。

ビルダー 書き出すもの ページ
spring_flutter_keys lib/spring_gen/theme.spring.keys.dart、lib/spring_gen/messages.spring.keys.dart 型付きキー
spring_flutter_web web_dev_config.yaml Web 開発サーバー
spring_flutter_page_loader web/index.html のブロック ページローダー
spring_flutter_seo web/ の中のルートと Markdown ファイルごとのページ、sitemap.xml、robots.txt、llms.txt 検索エンジン向けのページ
spring_flutter_deep_links Info.plist、Runner.entitlements、AndroidManifest.xml のブロック。apple-app-site-association、assetlinks.json ディープリンク

これらのビルダーがビルド時に読むプロパティは、ビルドが読むプロパティ に列挙されています。

Spring (Java) との対応

Spring には対応するものがありません。コンテナの外でオブジェクトが生成される UI ツールキットを持たないからです。@ChangeNotifierComponent と @NotifyListeners は、@Transactional と同じく、Bean のメソッドの周りのアドバイスという Spring のモデルに従っています。

関連項目