ビルドから外されるモジュール

スターターは、自動構成モジュールの一つに build: AutoConfigurationBuild('some.property') を付けることができます。そうすると、アプリケーションの設定が、build_runner の実行時に、そのモジュールをそもそもアプリケーションの一部にするかどうかを決めます。

典型的な使い道は、spring_boot_starter_flutter のデバッグパネルのような、開発者だけが必要とする機能です。そうすると、リリースビルドにはそのコードが一切含まれません。

使う理由

実行時の条件 (@ConditionalOnProperty) は、アプリケーションの起動時に Bean を無効にします。それらの Bean のコード (クラス、ウィジェット、文字列) は、それでもアプリにコンパイルされます。デバッグパネルにとって、それはすべてのリリースでの無駄な重さであり、パネルに何ができるかをユーザーやリバースエンジニアに見せてしまいます。

ビルド条件は一段階早く働きます。生成されたアプリケーションがモジュールのコードをそもそも参照するかどうかを決めます。何も参照しないコードは Dart のコンパイラーが取り除く (ツリーシェイキング) ので、外されたモジュールは出荷されるアプリで何のコストにもなりません。

設計を形作った三つの目標:

モジュールを宣言する (スターターの作者向け)

アノテーションは、他の自動構成モジュールと同じく、スターターの lib/spring_auto_configuration.dart のモジュール変数に付けます (自動構成 を参照)。

// パッケージ `neon_inspector` の lib/spring_auto_configuration.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';
import 'spring_gen/src/inspector.spring.dart';

// すべてのアプリケーションが受け取るモジュール。
@AutoConfigurationModule()
final BeanModule neonInspectorAutoConfiguration = $neonInspectorBeans;

// 開発者ツール: `neon.inspector.enabled` で決まる。
// 未設定: デバッグとプロファイルのビルドだけ (デフォルトの whenMissing)。
@AutoConfigurationModule(
  build: AutoConfigurationBuild('neon.inspector.enabled'),
)
final BeanModule neonInspectorToolsAutoConfiguration = $neonInspectorToolsBeans;

AutoConfigurationBuild には二つのパラメーターがあります。

パラメーター 型 デフォルト 意味
property (位置引数) String 必須 判定に使う、アプリケーションの設定のプロパティ。
whenMissing BuildInclusion BuildInclusion.notInRelease プロパティが設定されていないとき、モジュールをどこに含めるか。

BuildInclusion には三つの値があります。

値 モジュールが含まれるもの
BuildInclusion.always すべてのビルド
BuildInclusion.notInRelease デバッグとプロファイルのビルド。リリースビルドではコンパイル時に取り除かれる
BuildInclusion.never どのビルドにも含まれない

build: を持つモジュールは order、before、after を保ち、他のモジュールは自身のそれらでそのモジュールを指定してもかまいません。

プロパティを設定する (アプリケーション)

アプリケーションは、lib/resources/ にある自身の設定ファイルでプロパティを設定します。

# lib/resources/application.yml
neon:
  inspector:
    enabled: false   # このアプリのどのビルドにもインスペクターのコードを含めない

または

# lib/resources/application.properties
neon.inspector.enabled=true

その後、dart run build_runner build を実行します (または watch を動かしておきます)。lib/resources/ の設定ファイルはビルドの入力なので、それを変更すると build_runner はアプリケーションの .spring.dart ファイルを書き直します。

ビルドが読むもの

ビルドは、アプリケーションが設定を読むのと同じようにプロパティを読みますが、次の制限があります。

プロファイルのファイル (application-dev.yml、application-web.properties) でだけ設定された値は読まれません。ビルドはそれについて警告します (警告 を参照)。

判定

build: を持つ各モジュールについて、ジェネレーターはプロパティを一度検索し、次のように判定します。

プロパティ モジュール 警告
true 常に含まれる なし
false 決して含まれない なし
未設定、または空 whenMissing のとおり (デフォルトは notInRelease) なし。ただしプロファイルのファイルが設定している場合を除く
application-<profile>.* でだけ設定されている whenMissing のとおり あり: ビルドはプロファイルのファイルを読まない
その他の値 (yes、1、off) whenMissing のとおり あり: true でも false でもない

「常に含まれる」と「決して含まれない」は、生成コードの中で確定します。「リリースには含まれない」は、以下で説明するとおり、Dart のコンパイラーがビルドモードから判定します。

生成コードの見た目

ジェネレーターは @SpringBootApplication の出力 (main.spring.dart。アプリケーション を参照) を書き出します。その springApplication ゲッターが自動構成モジュールを列挙します。以下の例は example/flutter_guide の実際の出力から、インポートのプレフィックス (_i67.) だけを外したものです。

true、または whenMissing: always

モジュールは他のものと同じように列挙されます。

SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    springBootStarterFlutterDebugAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
    // ...
  ],
  // ...
);

false、または whenMissing: never

モジュールはリストにありません。ファイルの他の場所もそれに触れません。

SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
    // ...
  ],
  // ...
);

スターターの spring_auto_configuration.dart の他の何も使われない場合は、そのライブラリのインポートもなくなります。ジェネレーターのテストは、false の出力に、モジュールへの参照、その Bean のプロキシクラス、それらの source 文字列、スターターのインポートがないことをチェックしています (library_proxies_test.dart)。

未設定、デフォルトの whenMissing: notInRelease

モジュールはコレクション if の下に列挙されます。

SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterCacheAutoConfiguration,
    springBootStarterFeignAutoConfiguration,
    springBootStarterFlutterAutoConfiguration,
    if (!const bool.fromEnvironment('dart.vm.product'))
      springBootStarterFlutterDebugAutoConfiguration,
    springBootStarterFlutterNavigationAutoConfiguration,
    // ...
  ],
  // ...
);

そのようなモジュールが order、before、after を持つとき、autoConfigurationMetadata のそのエントリーは同じ if の下にあるので、順序付けはモジュールと一緒にリリースから外れます。

リリースでコンパイラーが取り除くものと、その理由

dart.vm.product はコンパイル時の環境定数です。Flutter は flutter build --release でそれを true に、デバッグとプロファイルのビルドでは false に設定します (Flutter の kReleaseMode は同じ定数です)。dart compile exe も true に設定しますが、dart run は設定しません。

dart.vm.product が true のとき、コンパイラーは !const bool.fromEnvironment('dart.vm.product') を定数 false と見なします。順を追うと:

  1. コレクション if の条件が定数 false なので、要素はリストから落とされます。
  2. するとモジュール変数 (springBootStarterFlutterDebugAutoConfiguration) はどこからも参照されなくなります。
  3. ツリーシェイキングは、どこからも参照されないものを取り除きます。変数、その Bean 定義、それらの create クロージャー、そしてそれらを通してだけ到達できるすべてのクラス、ウィジェット、文字列です。
  4. デバッグとプロファイルのビルドでは条件は true です。要素はリストにあり、モジュールは通常どおり動きます。

これは実際のビルドで確認されています。デバッグパネルを持つアプリのリリースの Web ビルドにはパネルの文字列が一切含まれず、プロファイルビルドには含まれます。dart compile js -Ddart.vm.product=true と dart compile exe でコンパイルした小さなプログラムでも同じで、そのような if を通してだけ到達できる文字列は出力に含まれません。

コンパイラーが何を取り除けるかは、他に何がそのコードを参照しているかによります。モジュールが使うクラスをアプリケーションが別の場所でも使っていれば、別の経路で到達できるので残ります。

モジュールの Bean のプロキシ

スターターの生成されたモジュールは、その Bean の AOP プロキシクラスを含みません。AopProxyFactory.deferred のプレースホルダーでアプリケーションに任せ、アプリケーションのビルドがそのアスペクトが必要とするプロキシクラスを書き出します (AOP プロキシ を参照)。これらのプロキシは、そのモジュールのビルドに従います。

Bean を定義するもの アプリケーションでのそのプロキシ
never と判定されたモジュールだけ 書き出されない: プロキシクラスなし、aopProxies のエントリーなし、Bean のライブラリのインポートなし
notInRelease と判定されたモジュールだけ (または never と notInRelease) 同じ if の下に登録されるので、リリースではコンパイル時に取り除かれる
一つのプラットフォームだけのモジュールだけ (一つのプラットフォームだけのモジュール を参照) そのプラットフォームの if の下に登録される
常に含まれるモジュールが一つ以上 通常どおり書き出される

notInRelease のモジュールにだけある Bean では、アプリケーションのモジュールは次のようになります (ジェネレーターのテストから。プレフィックスは外し、ファクトリーの引数は短縮しています)。

BeanModule get $application => BeanModule(
  r'application',
  [
    // アプリケーションの Bean
  ],
  aopProxies: {
    if (!const bool.fromEnvironment('dart.vm.product'))
      r'package:starter/task.dart#Task': AopProxyFactory(
        signatures: const [/* ... */],
        create: (target, invoker) => _$TaskProxy(target as Task, invoker),
      ),
  },
);

クラス _$TaskProxy はそのエントリーからだけ参照されるので、リリースではそれと一緒に取り除かれます。

一つのプラットフォームだけのモジュール

モジュールは、同じアノテーションの platform: で、そのコードが動くプラットフォームだけに留めることもできます。

// スターターのサーバー側の半分: サーバーが動ける場所でだけ。
@AutoConfigurationModule(platform: ModulePlatform.native)
final BeanModule neonInspectorServerAutoConfiguration = $neonInspectorServerBeans;
ModulePlatform モジュールが含まれるもの 生成コードでの条件
native dart:io が存在するビルド: Dart VM、AOT 実行ファイル、スマートフォンやデスクトップの Flutter アプリ const bool.fromEnvironment('dart.library.io') || const bool.fromEnvironment('SPRING_ALL_PLATFORMS')
web ブラウザービルド。JavaScript または WebAssembly const bool.fromEnvironment('dart.library.js_interop') || const bool.fromEnvironment('SPRING_ALL_PLATFORMS')
server Dart VM と AOT 実行ファイル: dart:io が存在し、Flutter の dart:ui は存在しない。Flutter アプリではなく、ブラウザーでもない (const bool.fromEnvironment('dart.library.io') && !const bool.fromEnvironment('dart.library.ui')) || const bool.fromEnvironment('SPRING_ALL_PLATFORMS')

プロパティは読まれません。プラットフォームはアプリケーションが選ぶものではないからです。ジェネレーターはモジュールを定数の下に列挙し、それぞれのコンパイラーが自分のプラットフォームについて判定します。以下は example/server_guide の実際の出力から、インポートのプレフィックスを外したものです。

SpringApplication get springApplication => SpringApplication(
  [$application],
  autoConfigurations: [
    springBootAutoConfiguration,
    springBootStarterCacheAutoConfiguration,
    springBootStarterFeignAutoConfiguration,
    springBootStarterLoggingAutoConfiguration,
    springBootStarterOauth2ClientAutoConfiguration,
    springBootStarterSchedulingAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterSecurityAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterSecurityOAuth2ClientAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterWebAutoConfiguration,
    springBootStarterWebsocketAutoConfiguration,
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterWebsocketServerAutoConfiguration,
    springSecurityCoreAutoConfiguration,
  ],
  autoConfigurationMetadata: {
    if ((const bool.fromEnvironment('dart.library.io') ||
        const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))
      springBootStarterSecurityAutoConfiguration:
          const AutoConfigurationModule(
            after: ['springBootStarterOauth2ClientAutoConfiguration'],
          ),
    // ...
  },
  // ...
);

サーバーでは dart.library.io は true で、すべてのモジュールが含まれます。ブラウザー向けにコンパイルすると false です。要素は落とされ、モジュール変数はどこからも参照されなくなり、ツリーシェイキングが、それらだけが到達するすべてのクラスと一緒に取り除きます。リリースについての 上記 と同じです。そのため、同じ生成ファイルが両方のプラットフォームで使え、依存関係が Web スターターを持ち込む Flutter の Web アプリはサーバーを持ちません。

意図して別のプラットフォームでサーバーのモジュールを動かすプログラム(たとえばリポジトリの、サーバーのコードをミニファイした JavaScript として Node で確かめるチェック)は、-DSPRING_ALL_PLATFORMS=true を付けてコンパイルします。すべてのモジュールが残ります。

ルール:

どのモジュールに指定があるか

ファミリーのすべての自動構成モジュールと、それが含まれる場所:

パッケージ モジュール プラットフォーム ビルドプロパティ
spring_boot_dart springBootAutoConfiguration すべて
springBootObservedAnnotationsAutoConfiguration すべて spring.observations.annotations.enabled (未設定: 含めない)
spring_boot_starter_logging springBootStarterLoggingAutoConfiguration すべて
spring_boot_starter_scheduling springBootStarterSchedulingAutoConfiguration すべて
spring_boot_starter_cache springBootStarterCacheAutoConfiguration すべて
springBootStarterCacheStartupChecksAutoConfiguration (cacheOperationValidator) すべて spring.main.startup-checks.enabled
spring_boot_starter_feign springBootStarterFeignAutoConfiguration すべて
spring_boot_starter_data springBootStarterDataAutoConfiguration すべて
springBootStarterDataStartupChecksAutoConfiguration (transactionValidator、dataFailureAnalyzer) すべて spring.main.startup-checks.enabled
springBootStarterDataSqlLoggingAutoConfiguration (文のログ、jdbcLogSettings) すべて spring.data.jdbc.show-sql
spring_boot_starter_oauth2_client springBootStarterOauth2ClientAutoConfiguration すべて
spring_boot_starter_edge springBootStarterEdgeAutoConfiguration (fetch サーバー、ランタイム) すべて
springBootStarterEdgeStartupChecksAutoConfiguration (edgeWarnings) すべて spring.main.startup-checks.enabled
spring_security_core springSecurityCoreAutoConfiguration すべて
spring_search_dart springSearchDartAutoConfiguration すべて
spring_boot_starter_websocket springBootStarterWebsocketAutoConfiguration (クライアント) すべて
springBootStarterWebsocketServerAutoConfiguration (サーバーのエンドポイント) native
spring_boot_starter_supabase springBootStarterSupabaseDataAutoConfiguration (データストアのデフォルト) すべて
springBootStarterSupabaseAutoConfiguration (Bean) すべて
springBootStarterSupabaseAdminAutoConfiguration (supabaseAuthAdmin) server
springBootStarterSupabaseServerAutoConfiguration (リソースサーバーのデフォルト) server
spring_boot_starter_web springBootStarterWebAutoConfiguration native
springBootStarterWebRateLimitAutoConfiguration (レートリミッター) native
springBootStarterWebDebugQpsAutoConfiguration native spring.web.debug.qps.enabled (未設定: 含めない)
spring_boot_starter_security springBootStarterSecurityAutoConfiguration native
springBootStarterSecurityOAuth2ClientAutoConfiguration native
spring_boot_starter_actuator springBootStarterActuatorAutoConfiguration native
springBootStarterActuatorQpsAutoConfiguration native spring.web.debug.qps.enabled (未設定: 含めない)
spring_boot_starter_flutter springBootStarterFlutterAutoConfiguration すべて
springBootStarterFlutterDebugAutoConfiguration すべて spring.flutter.debug.enabled
springBootStarterFlutterDebugFrameMeterAutoConfiguration すべて spring.flutter.debug.frame-meter.enabled
springBootStarterFlutterDebugMotionAutoConfiguration すべて spring.flutter.debug.motion.enabled
springBootStarterFlutterDebugTimelineAutoConfiguration すべて spring.flutter.debug.timeline.enabled
springBootStarterFlutterDebugIsolatesAutoConfiguration すべて spring.flutter.debug.isolates.enabled
springBootStarterFlutterDebugDragAutoConfiguration すべて spring.flutter.debug.drag.enabled (未設定: 含めない)
spring_boot_starter_flutter_scene springBootStarterFlutterSceneAutoConfiguration すべて spring.flutter.scene.enabled (未設定: 含める)
springBootStarterFlutterSceneDebugAutoConfiguration (デバッグパネルのシーンのタブ) すべて spring.flutter.scene.debug.enabled
spring_boot_starter_flutter_signals springBootStarterFlutterSignalsAutoConfiguration すべて
springBootStarterFlutterSignalsDebugAutoConfiguration (デバッグパネルの状態のタブ) すべて spring.flutter.signals.debug.enabled
spring_boot_starter_flutter_material springBootStarterFlutterMaterialAutoConfiguration すべて
spring_boot_starter_flutter_cupertino springBootStarterFlutterCupertinoAutoConfiguration すべて
spring_boot_starter_flutter_navigation springBootStarterFlutterNavigationAutoConfiguration すべて
spring_boot_starter_flutter_security springBootStarterFlutterSecurityAutoConfiguration すべて

注記のないビルドプロパティは、未設定のとき「リリースには含まれない」です。データ、キャッシュ、edge の各スターターの起動チェックのモジュールは spring.main.startup-checks.enabled を共有します。一つのキーで三つとも外せます。データスターターの SQL 文のログは独立したモジュールで、spring.data.jdbc.show-sql で決まります。各スターターのページ「ビルドに含まれるもの」は、そのスターター自身のモジュールと、ジェネレーターがそのために書くものを挙げています。たとえば データスターターのページ です。

native なのは、サーブするものです。Web サーバー、そのセキュリティ、その上の Actuator のエンドポイント、WebSocket のサーバーのエンドポイントです。server は、アプリに入れてはならない、つまり誰でも読めるものに入れてはならないコードのためのものです。サービスロールキーを使う Supabase スターターの管理 API と、リソースサーバーのデフォルトです。Flutter アプリ (スマートフォン、デスクトップ、Web) はどちらも持ちません。ファミリーに web だけのモジュールはありません。どこにでも含まれるモジュールは、プラットフォーム固有の部分を条件付きインポートで自分で選びます。WebSocket のトランスポート、タスクエグゼキューター、Flutter セキュリティスターターのシークレットストアです。

ブラウザーアプリの依存関係であるパッケージは、それでもブラウザーでコンパイルできなければなりません。platform: はモジュールをプログラムから取り除きますが、ブラウザー向けにまったくコンパイルできないライブラリを許すものではありません。WebAssembly を参照してください。

キーで決まるジェネレーターのパート

パッケージのジェネレーターのパート (パッケージのパート を参照) も、同じようにキーに従えます。PackageBuild('some.property', whenMissing: ...) は AutoConfigurationBuild と同じように読まれます。そうすると、一つのキーで、パッケージのモジュールと、ジェネレーターがそのために書くものすべてを外せます。

組み込みのパートでキーを取るものはまだなく、パートに分けたことで、例の生成コードは変わっていません。

すべてのビルドに残るもの

意図して、またはまだ切り替えられないコードがあります。

JavaScript や WebAssembly にコンパイルするとき

dart compile js と dart compile wasm は dart.vm.product を定義しないので、その出力は notInRelease の意味でのリリースビルドではありません。edge function は、キーが false でない限り、notInRelease のモジュール (edge スターターの警告の一覧など) を残します。Flutter のリリースビルドと AOT 実行ファイル (dart compile exe) はそれらを外します。

警告

ビルド条件がビルドを失敗させるのは、ビルドがプロパティを読めない場合だけです。環境変数や --dart-define だけが解決するデフォルトなしの ${...} プレースホルダー、または解析できない設定ファイルです。エラーはモジュールとプロパティを示し、修正方法を伝えます。

neon_inspector.neonInspectorToolsAutoConfiguration: the build reads
neon.inspector.enabled to decide whether the module is built, and could not:
PlaceholderResolutionException: Could not resolve placeholder 'FLAG' in value
"${FLAG}"
Give neon.inspector.enabled a value the build can read in application.yml or
application.properties, or a placeholder with a default (${FLAG:true}):
environment variables and --dart-define values do not exist at build time.

それ以外の場合は、モジュールを <package>.<variable> として示して警告します。

プロパティがプロファイルのファイルでだけ設定されている。

neon_inspector.neonInspectorToolsAutoConfiguration: neon.inspector.enabled is
set only in application-dev.yml, which the build does not read: it decides by
application.yml or application.properties without a profile. The module is
built as when it is not set.

設定を application.yml か application.properties に移すか、実行時のスイッチとしてプロファイルのファイルに残します (次の節を参照)。

値が true でも false でもない。

neon_inspector.neonInspectorToolsAutoConfiguration: neon.inspector.enabled is
'yes', not true or false; the module is built as when it is not set.

ビルド条件と実行時の条件

二種類の条件は異なる仕事をし、一緒に働きます。

ビルド条件 (build:) 実行時の条件 (@ConditionalOnProperty、@Profile など)
決めるもの モジュールのコードがアプリに存在するかどうか アプリの起動時に Bean が登録されるかどうか
評価される時 build_runner の実行時、そして notInRelease ではコンパイラーによって 起動のたび
読むもの 外部のプロファイルなしの application.yml / application.properties 実行中のアプリのすべてのプロパティソース: プロファイル、環境変数、引数、--dart-define
アプリのサイズへの効果 コードを取り除く なし: コードはコンパイルに含まれる
もう一方が無効にしたものを有効にできるか できない できない

つまり、ビルド条件はコードを取り除くことができ、コードが存在する場所では実行時の条件が引き続きその Bean を無効にできます。逆は不可能です。ビルドが外したモジュールを実行時のプロパティで呼び戻すことはできません。そのコードがそこにないからです。

両方を望むスターターは、デバッグパネルと同じく両方を宣言します。モジュールに build: を付け、その Bean に同じプロパティで matchIfMissing: true の @ConditionalOnProperty を付けます。

実例: デバッグパネル

spring_boot_starter_flutter はデバッグパネルを次のように宣言しています (短縮)。

// spring_boot_starter_flutter/lib/spring_auto_configuration.dart

// 実行中のアプリのパネル: ビルドに含まれていても、プロファイルの
// spring.flutter.debug.enabled=false で無効になる。
const _debugOn = ConditionalOnProperty(
  'spring.flutter.debug.enabled',
  havingValue: 'true',
  matchIfMissing: true,
);

@AutoConfigurationModule(
  build: AutoConfigurationBuild('spring.flutter.debug.enabled'),
)
final BeanModule springBootStarterFlutterDebugAutoConfiguration = BeanModule(
  'springBootStarterFlutterDebugAutoConfiguration',
  [
    BeanDefinition<DebugPanel>(
      name: 'debugPanel',
      conditions: const [_debugOn],
      create: (_) => DebugPanel(),
      // ...
    ),
    // セクション: ログ、フレーム、設定、Bean、テーマ、起動。
    // そしてパネルをアプリの上に置く debugPanelCustomizer
  ],
);

application.yml (または application.properties) の spring.flutter.debug.enabled の値によって、アプリが受け取るもの:

spring.flutter.debug.enabled デバッグとプロファイルのビルド リリースビルド
未設定 パネルのコードが含まれる。実行中のアプリが false を読まない限り (プロファイルのファイル、引数)、パネルは有効 コードなし
true コードが含まれる。実行中のアプリが false を読まない限り、パネルは有効 コードが含まれる。実行中のアプリが false を読まない限り、パネルは有効
false コードなし コードなし

ほとんどのアプリは何も設定しません。開発者はパネルを得て、ユーザーには決して出荷されません。リリースビルドに残すには true を (社内テスト用のビルド)、どのビルドにも含めないには false を設定します。

ビルド時間のコスト

ビルド条件がビルドに加えるものはほとんどなく、スターターがそれを使わないアプリケーションには何も加えません。

テストされていること

ジェネレーターのテストは、偽のスターターに対してアプリケーションをビルドし、生成コードをチェックします。

関連項目