ビルドから外されるモジュール
スターターは、自動構成モジュールの一つに build: AutoConfigurationBuild('some.property') を付けることができます。そうすると、アプリケーションの設定が、build_runner の実行時に、そのモジュールをそもそもアプリケーションの一部にするかどうかを決めます。
some.property: true: モジュールはすべてのビルドに含まれます。some.property: false: モジュールはどのビルドにも含まれません。生成コードはそれに触れません。- 未設定: スターターのデフォルト。スターターが別のことを言わない限り「デバッグとプロファイルのビルドに含め、リリースには含めない」です。
典型的な使い道は、spring_boot_starter_flutter のデバッグパネルのような、開発者だけが必要とする機能です。そうすると、リリースビルドにはそのコードが一切含まれません。
使う理由
実行時の条件 (@ConditionalOnProperty) は、アプリケーションの起動時に Bean を無効にします。それらの Bean のコード (クラス、ウィジェット、文字列) は、それでもアプリにコンパイルされます。デバッグパネルにとって、それはすべてのリリースでの無駄な重さであり、パネルに何ができるかをユーザーやリバースエンジニアに見せてしまいます。
ビルド条件は一段階早く働きます。生成されたアプリケーションがモジュールのコードをそもそも参照するかどうかを決めます。何も参照しないコードは Dart のコンパイラーが取り除く (ツリーシェイキング) ので、外されたモジュールは出荷されるアプリで何のコストにもなりません。
設計を形作った三つの目標:
- シンプル。 スターターの作者にはアノテーションの引数が一つ、アプリケーションにはプロパティが一つ。呼ぶものもインポートするものもありません。
- 実際のビルドを決して遅くしない。 プロパティは、あるモジュールが
build:を使う場合にだけ読まれ、プロキシのための追加の作業は、モジュールが実際に取り除かれる場合にだけ行われます。ビルド時間のコスト を参照してください。 - 無効にしたら痕跡なし。
falseと判定されたモジュールは参照されず、(そのライブラリの他の何かが使われない限り) インポートされず、アプリケーションにプロキシクラスを持ちません。生成コードの見た目 を参照してください。
モジュールを宣言する (スターターの作者向け)
アノテーションは、他の自動構成モジュールと同じく、スターターの 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 ファイルを書き直します。
ビルドが読むもの
ビルドは、アプリケーションが設定を読むのと同じようにプロパティを読みますが、次の制限があります。
lib/resources/のapplication.yml、application.yaml、application.propertiesを読みます (lib/の外のエントリーポイントでは、より近いlib/resources/フォルダーも読みます。埋め込みリソース を参照)。- それらを 外部からのプロファイルなし で読みます。プラットフォームのプロファイル (
web、iosなど) も、--spring.profiles.active引数も、環境変数もありません。ファイル自身が有効にするプロファイル (application.ymlに書かれたspring.profiles.active: dev) は、実行中のアプリケーションと同じく適用され、ビルドが読めるspring.config.importのエントリーも適用されます。 - 環境変数も
--dart-defineの値も読みません。デフォルト付きの${...}プレースホルダーは動きます (${INSPECTOR:true}はtrue)。ビルドが解決できないプレースホルダーや、解析できないファイルはビルドを失敗させます。 - 値は前後の空白が取り除かれ、大文字小文字を区別せずに比較されます。
true、TRUE、Trueはすべてtrueを意味します。
プロファイルのファイル (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 と見なします。順を追うと:
- コレクション
ifの条件が定数falseなので、要素はリストから落とされます。 - するとモジュール変数 (
springBootStarterFlutterDebugAutoConfiguration) はどこからも参照されなくなります。 - ツリーシェイキングは、どこからも参照されないものを取り除きます。変数、その Bean 定義、それらの
createクロージャー、そしてそれらを通してだけ到達できるすべてのクラス、ウィジェット、文字列です。 - デバッグとプロファイルのビルドでは条件は
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 を付けてコンパイルします。すべてのモジュールが残ります。
ルール:
build:があれば、両方の条件が成り立つ必要があります。 ビルドプロパティが未設定でplatform: ModulePlatform.nativeを持つモジュールは、if (!const bool.fromEnvironment('dart.vm.product') && (const bool.fromEnvironment('dart.library.io') || const bool.fromEnvironment('SPRING_ALL_PLATFORMS')))の下に列挙されます。ビルドプロパティがfalse(またはnever) と判定されると、プラットフォームが何であってもモジュールは外されます。- 順序は残ります。
autoConfigurationMetadataのモジュールのエントリーは、上の出力のとおり、同じifの下にあります。 - プロキシは従います。 そのようなモジュールだけが定義する Bean のプロキシは同じ条件の下に登録されるので、モジュールと一緒にもう一方のプラットフォームのビルドから外れます。
- 実行時の条件ではありません。 起動時にスキップされる Bean はありません。もう一方のプラットフォームでは、コードがそこにありません。
どのモジュールに指定があるか
ファミリーのすべての自動構成モジュールと、それが含まれる場所:
| パッケージ | モジュール | プラットフォーム | ビルドプロパティ |
|---|---|---|---|
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 と同じように読まれます。そうすると、一つのキーで、パッケージのモジュールと、ジェネレーターがそのために書くものすべてを外せます。
true: パートはキーのないパートと同じように動きます。false: パートは動かず、その生成物は何もありません。- 未設定で
BuildInclusion.notInRelease(デフォルト): パートが書くもの (Bean 定義、モジュールの文、イントロスペクションのリスト、リソース) はif (!const bool.fromEnvironment('dart.vm.product'))の下に置かれます。パートのクラスとトップレベルの宣言は条件の下に置けませんが、何も使わなければリリースビルドが捨てます。
組み込みのパートでキーを取るものはまだなく、パートに分けたことで、例の生成コードは変わっていません。
すべてのビルドに残るもの
意図して、またはまだ切り替えられないコードがあります。
spring_security_coreのmethodSecurityValidatorは、意図してすべてのビルドに残ります。プロキシのないまま残った保護された Bean で起動を止める、セキュリティの安全網だからです。- データスターターの遅いクエリのログ (
jdbcSlowQueryLogSettings) はメインのモジュールにあり、遅い文はすべてのビルドで warn で記録されます。切り替えられるのは、spring.data.jdbc.show-sqlの文のログだけです。 - データスターターのスキーマのステップ (
create、validate) と メモリ上のストア はメインのモジュールにあり、まだ切り替えられません。
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 を設定します。
ビルド時間のコスト
ビルド条件がビルドに加えるものはほとんどなく、スターターがそれを使わないアプリケーションには何も加えません。
- 設定は遅延して一度だけ読まれます。
lib/resources/のファイルは、すべてのアプリケーションですでに読まれています (埋め込まれるからです。埋め込みリソース を参照)。それらが環境に解析されるのは、build:を持つ最初のモジュールのときだけで、その環境は同じビルドステップの他のモジュールのために保持されます。そのようなモジュールがなければ、プロパティの検索は一度も行われません。 - プロファイルのファイルは必要なときだけ見られます。
application-<profile>.*でだけ設定された値のチェックは、プロパティが設定されていない場合にだけ行われます。 - モジュールのコードは、何かが取り除かれるときだけたどられます。 どのプロキシがモジュールと一緒に外れるかを知るため、ジェネレーターはモジュールの宣言と、それが読むトップレベル変数とゲッターをたどり、
AopProxyFactory.deferredの Bean を探します。それを行うのは、モジュールがneverまたはnotInReleaseと判定された場合だけです。常に含まれるモジュールをたどるのは、取り除かれたモジュールがそのような Bean を一つ以上定義する場合だけで、たどった宣言はそれぞれ記憶されます。
テストされていること
ジェネレーターのテストは、偽のスターターに対してアプリケーションをビルドし、生成コードをチェックします。
starter_compatibility_test.dart:trueはモジュールを列挙し、dart.vm.productを書かない。falseはモジュールの何も書かない。未設定はif (!const bool.fromEnvironment('dart.vm.product'))の要素を書く。whenMissing: BuildInclusion.neverは何も書かない。application-web.yml(入れ子またはドット区切りの YAML) やapplication-web.propertiesでだけ設定された値は警告し、未設定としてビルドする。プロファイルなしで設定された値は警告しない。starter_compatibility_test.dart、platform:について:nativeはモジュールをdart.library.ioの下に、webはdart.library.js_interopの下に列挙し、dart.vm.productは書かない。ビルドプロパティが未設定なら両方の条件が結合される。プロパティがfalseならモジュールは書かれない。orderは残り、そのエントリーは同じ条件の下にある。library_proxies_test.dart: 遅延されたプロキシを持つ Bean について、falseはプロキシクラス、source、スターターのインポート、モジュールを残さない。未設定はifの下にプロキシを登録する。trueはそのまま登録する。常に含まれるモジュールにも Bean がある場合のfalseはプロキシを保つ。