ビルドが読むプロパティ
ほとんどのプロパティは、アプリが起動時に読みます。いくつかはそれより前、build_runner の実行中にジェネレーターが読みます。それらは、どのコードが生成されるか、どのモジュールがコンパイルに含まれるか、lib/ の外のファイル (web/index.html、Info.plist、web_dev_config.yaml) に何が入るかを決めます。このページでは、それらすべてをビルダーごとにまとめ、各ビルダーがどの設定ファイルを読むかを示します。
使う理由
ビルド時に読まれるプロパティは、実行時に読まれるものとは異なる振る舞いをします。
- 変更にはビルドが必要です。 ファイルを編集し、
dart run build_runner buildを実行します (またはwatchを動かしておきます)。ホットリスタートでは不十分です。 - 数えられるのはファイルだけです。 ビルドからは環境変数、
--dart-defineの値、コマンドライン引数は見えません。それらはアプリの実行時にしか存在しません。それらでしか埋められないプレースホルダーは、ビルド時には不明です。 - プロファイルの読み方はビルダーごとに異なります。 一つのプラットフォームでアプリが読むのと同じようにファイルを読むビルダーもあります (Web のビルダーなら
application-web.yml、iOS ならapplication-ios.yml)。プロファイルにかかわらずすべてのファイルを読むものもあります。プロファイルのないファイルだけを読むものも一つあります。どれがどれかを知っていれば、ビルドに見えるようにキーをどこに置けばよいかがわかります。
例
Web アプリの設定です。ビルド時に読まれる各キーを読むビルダーをコメントに示しています。
# lib/resources/application.yml
spring:
messages:
basename: messages,errors # spring_flutter_keys: 型付きメッセージ
flutter:
debug:
enabled: false # spring_core_dart: デバッグパネルのコードを一切含めない
app:
title: NEON Books # spring_flutter_page_loader: <title>、manifest.json
description: Books, in neon. # spring_flutter_page_loader: <meta name="description">
theme:
active: system # spring_flutter_keys と spring_flutter_page_loader
splash:
loader: ring # spring_flutter_page_loader: ページローダー
navigation:
deep-links:
scheme: neonbooks # spring_flutter_deep_links
domains: [books.example.com]
# lib/resources/application-web.yml (web プロファイル: Web のビルダーが読む)
spring:
flutter:
web:
dev-server:
port: 5050 # spring_flutter_web: web_dev_config.yaml
page:
max-pixel-ratio: 2 # spring_flutter_page_loader: web/index.html のスクリプト
seo:
enabled: true # spring_flutter_seo: ルートごとのページ
site-url: https://books.example.com
各ビルダーの設定の読み方
ジェネレーターは四つの方法で設定を読みます。各ビルダーはそのいずれかを使います。どれを使うかは下の表に示します。
1. 一つのプラットフォームでアプリが読むのと同じように
ビルダーは、アプリが起動時に使うのと同じ設定ローダーで、そのプラットフォームでアプリが追加するプロファイルを使ってファイルを読み込みます。
| ビルダー | 追加されるプロファイル | 用途 |
|---|---|---|
spring_flutter_web |
web |
spring.flutter.web.dev-server.*、spring.flutter.security.web.mode |
spring_flutter_seo |
web |
spring.flutter.web.seo.*、spring.flutter.navigation.languages |
spring_flutter_page_loader |
web |
spring.flutter.app.title、.description、spring.flutter.web.page.*、spring.web.resources.cache.cachecontrol.* |
spring_flutter_deep_links |
mobile の次に ios、mobile の次に android、desktop の次に macos (プラットフォームごとに一度。プラットフォーム自身のファイルが優先) |
spring.flutter.navigation.deep-links.* |
spring_core_dart |
なし | 各 AutoConfigurationBuild のプロパティ |
spring_json_schemas |
なし | spring.json.schemas[n].* |
spring_search_index |
なし | spring.search.markdown[n].*、spring.search.analyzers.*、spring.search.prebuilt |
ローダーが読むもの (順に):
lib/resources/とlib/resources/config/のapplication.properties、.yml、.yaml。- 追加されたプロファイルのファイル (
application-web.yml)。アプリと同じく、手順 1 のファイルより優先されます。 - それらのファイルの
spring.profiles.active(と.include、.group.*) が指定するプロファイルのファイル、そしてアクティブなものがなければdefaultプロファイルのファイル (application-default.yml)。 spring.config.importがresources:で指定するファイル (パッケージ自身のlib/resources/から) と、spring.config.activate.on-profileが一致するドキュメント。
知りえないものと、その代わりにすること:
- 実行中のアプリだけが解決するプレースホルダー (デフォルトがなく、環境変数や
--dart-defineで設定される${ENV})。デフォルトがあればそれが使われます (${APP_PROFILE:dev}はdev)。なければ、そのようなプレースホルダーを含むプロファイル名は除外され、spring.profiles.validateとspring.main.cloud-platformは未設定とみなされ、インポートの場所は読まれず、spring.config.activate.*にそれを含むドキュメントはスキップされます。どの場合もそれを示す警告になり、エラーにはなりません。 - ビルドモードのプロファイル。 アプリは起動時に
debug、profile、releaseを追加します。どのビルダーもそれを追加しないので、spring.profiles.activeがreleaseを指定しない限り、application-release.ymlはビルド時に読まれません。 - ファイルシステム。 ブラウザーにはファイルシステムがなく、スマートフォンのものはビルドマシンのものではありません。
file:、configtree:、package:のインポートは、optional:かどうかにかかわらずスキップされます。ビルドがまったく読めないインポート (http:、asset:、lib/resources/にないresources:のファイル) は黙ってスキップされます。実行時には存在するかもしれないからです。
これらのビルダーはパッケージ自身の lib/resources/ だけを読みます。キーを置ける場所はアプリと同じようにチェックされます。プロファイルのファイル (application-web.yaml) の中の spring.profiles.active は、アプリの起動時と同じくエラーです。
2. プロファイルにかかわらずすべてのファイル
ビルダーは、プロファイルを適用せずに、lib/resources/ のすべての .properties、.yml、.yaml ファイルのキーをパス順に読みます。加えて、spring.config.import が resources: で指定し、依存関係が同梱しているファイル (テーマパッケージの resources:themes/neon.yml) も読みます。
| ビルダー | 用途 |
|---|---|
spring_flutter_keys |
spring.flutter.theme.* (すべてのテーマのキー)、spring.messages.basename |
spring_flutter_page_loader |
spring.flutter.theme.* (スプラッシュ、ローダー、色)、spring.remote.allow-insecure |
spring_metadata |
すべてのテーマの spring.flutter.theme.loaders.* (各ローダーの種類が受け取るキー) |
型付きキーにとってはこれが望ましい動作です。application-dark.yml でだけ宣言されたキーにもアクセサーができます。値にとっては、プロファイルの優先順位が適用されないことを意味します。二つのファイルが同じキーを設定している場合、パス順で後のファイルが優先されます (application.yml は application-web.yml の後に来ます)。単一値のキー spring.messages.basename と spring.remote.allow-insecure は、パス順でそれを設定している最初のファイルのものを取ります。これらの各キーは一つのファイルにまとめておいてください。
3. プロファイルのないファイルだけ、厳密に
スキーマに対する @Query テキストのチェックは、lib/resources/ と lib/resources/config/ の application.properties、.yml、.yaml だけを読み、他は何も読みません。他のものが結果を変えうる場合 (spring.sql.* キーを設定するプロファイルのファイルやプロファイル専用のドキュメント、spring.config.import、lib/resources/ の外やプレースホルダー付きの場所、名前付きのデータソース、解析できないファイル)、確信が持てないため、ビルドはテーブルやカラムの綴り間違いを報告しません。
4. キー名だけ
@SpringBootApplication の出力の --dart-define キーのために、メインのビルダーは lib/resources/ の application* ファイル (すべてのプロファイル) のキー名を集めます。その値は読みません。--dart-define キー を参照してください。
メインのビルダー: spring_core_dart
| プロパティ | 読み方 | 変えるもの |
|---|---|---|
各 AutoConfigurationBuild の property |
アプリと同じように、プラットフォームのプロファイルなし (方法 1) | モジュールをアプリケーションに含めるかどうか: true ならすべてのビルドに、false ならどのビルドにも含めない (コードなし)、未設定ならモジュールの whenMissing (デフォルトは notInRelease) |
spring.flutter.debug.enabled |
同じ: spring_boot_starter_flutter のデバッグモジュールの AutoConfigurationBuild プロパティ |
true: デバッグパネルはすべてのビルドに含まれる。false: デバッグパネルのコードを一切含めない。未設定: デバッグとプロファイルのビルドに含まれ、リリースビルドではコンパイル時に取り除かれる |
spring.flutter.debug.frame-meter.enabled、.motion.enabled、.timeline.enabled、.isolates.enabled |
同じ: それぞれ spring_boot_starter_flutter の専用のデバッグモジュールのもの |
spring.flutter.debug.enabled と同じ。フレームメーター、モーションのスイッチ、タイムライン、タスクマネージャーについて |
spring.flutter.debug.drag.enabled |
同じ | true: デバッグオーバーレイをドラッグできる。false または未設定: そのためのコードなし |
spring.web.debug.qps.enabled |
同じ: spring_boot_starter_web の qps モジュールと Actuator の qps エンドポイントのプロパティ |
true: アプリケーションはリクエストを数え、qps エンドポイントを持つ。false または未設定: そのコードは一切なし → 毎秒のリクエスト数 |
spring.main.startup-checks.enabled |
同じ: スターターの起動時チェックを持つモジュールのプロパティ (data スターターの transactionValidator と dataFailureAnalyzer、cache スターターの cacheOperationValidator、edge スターターの警告のリスト) |
true: チェックはすべてのビルドに含まれる。false: そのコードは一切ない。未設定: デバッグビルドとプロファイルビルドに含まれ、リリースビルドではコンパイル時に取り除かれる。チェックが見つけたはずの誤りは、起動時ではなく最初の呼び出しで失敗する |
spring.data.jdbc.show-sql |
同じ: data スターターの文のログのモジュールのプロパティ | true: show-sql、format-sql、show-parameters がすべてのビルドで働く。false: そのコードは一切ない。未設定: デバッグビルドとプロファイルビルドだけ (application-dev.yml のようなプロファイルは、そこでなお有効にできる。プロファイルなしのファイルが設定していないのにプロファイルが show-sql を設定すると警告される。リリースビルドにはそのコードがない)。slow-query-threshold はすべてのビルドに残る |
spring.observations.annotations.enabled |
同じ: spring_boot_dart の @Observed モジュールのプロパティ |
true: @Observed が効くようになる。false または未設定: アドバイザーなし、そのためのプロキシもなし |
spring.sql.migration.locations、spring.sql.init.schema-locations、spring.sql.init.platform |
プロファイルのないファイルだけ (方法 3) | @Query のチェックが比較するスキーマを、lib/resources/ のどの SQL ファイルが記述しているか |
spring.resources.embed.exclude |
lib/resources/ のプロファイルのないファイル |
lib/resources/ のどのファイルをバイナリーの外に置くか。設定は常に埋め込まれる → 埋め込みリソース |
これらがファミリーの AutoConfigurationBuild プロパティです。すべてのモジュールとそのプラットフォームの表は 一つのプラットフォームだけのモジュール にあります。モジュールのプラットフォーム (AutoConfigurationModule(platform:)) はプロパティではありません。ビルドはそのために何も読みません。独自のスターターは、さらにビルドプロパティを宣言できます。
// スターターの lib/spring_auto_configuration.dart
@AutoConfigurationModule(
build: AutoConfigurationBuild('neon.debug.enabled'),
)
final BeanModule neonDebugAutoConfiguration = BeanModule(...);
true と false (大文字小文字と空白は無視) 以外の値は警告になり、モジュールはプロパティが未設定のときと同じようにビルドされます。プロパティが未設定で、プロファイルのファイル (application-web.yml) がそれを設定している場合、ビルドはそのファイルを読まないことを警告します。
spring_boot_starter_flutter.springBootStarterFlutterDebugAutoConfiguration: spring.flutter.debug.enabled is set only in application-web.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 に置いてください。spring_boot_starter_flutter のデバッグ Bean は、同じプロパティに対する実行時の条件 (@ConditionalOnProperty、未設定のときに一致) も持っているので、プロファイルのファイルの spring.flutter.debug.enabled: false でも、ビルドが含めたパネルを実行時に無効にできます。ビルドから外されるモジュール を参照してください。
main が lib/ の外 (example/) にあるアプリケーションでは、メインのビルダーは main までのすべてのディレクトリの lib/resources/ も読み、同名のファイルでは近いほうが優先されます。
型付きキー: spring_flutter_keys
spring_boot_starter_flutter (またはそれを持ち込むスターター) に依存するパッケージで動きます。すべてのファイルを読みます (方法 2)。
| プロパティ | 変えるもの |
|---|---|
spring.flutter.theme.* と spring.flutter.theme.themes.<name>.* |
context.theme のアクセサーと AppThemes の名前。数えられるのはキーとその種類だけで、値は実行時にアクティブなテーマから読まれます。 |
spring.messages.basename |
context.messages のメッセージファイル。カンマ区切りの各ベースについて <basename>.properties と <basename>_<locale>.properties (デフォルトは messages)。プレースホルダーを含むと警告になり、型付きメッセージは書き出されません。 |
spring.config.import |
その resources: エントリーは、依存関係の lib/resources/ のファイルをキーに持ち込みます。 |
型付きキー を参照してください。
Web 開発サーバー: spring_flutter_web
すべてのパッケージで動きます。設定ファイルが spring.flutter.web.dev-server.* キーか spring.flutter.security.web.mode を設定している場合にだけ設定を読み込みます (方法 1、プロファイル web)。それ以外では何もせず、何も言いません。値はビルド時に解決できなければなりません。実行中のアプリしか埋められないプレースホルダーはエラーです。
| プロパティ | web_dev_config.yaml で変えるもの |
|---|---|
spring.flutter.web.dev-server.host |
server.host: 待ち受けるアドレス (localhost、0.0.0.0) |
spring.flutter.web.dev-server.port |
server.port: 0 から 65535。0 は空いているポートを選ぶ。ブラウザーが拒否するポートは警告 |
spring.flutter.web.dev-server.base-href |
server.base-href: / で始まり / で終わらなければならない |
spring.flutter.web.dev-server.https.cert-path、.https.cert-key-path |
server.https: 両方か、どちらもなしか |
spring.flutter.web.dev-server.headers.<Name> |
server.headers: すべての応答に付くヘッダー |
spring.flutter.web.dev-server.content-security-policy |
Content-Security-Policy ヘッダー |
spring.flutter.web.dev-server.content-security-policy-report-only |
true: ポリシーは代わりに Content-Security-Policy-Report-Only に入る |
spring.flutter.web.dev-server.content-security-policy-connect-src |
spa モードの既製のポリシーに追加されるオリジン |
spring.flutter.web.dev-server.proxy[n].target、.prefix、.regex、.replace |
server.proxy: 他のサーバーに転送されるリクエスト |
spring.flutter.security.web.mode |
spa: アプリが設定していなければ既製の Content Security Policy |
spring.security.oauth2.client.provider.*、.registration.* |
spa モードで: ログインが fetch するオリジンがポリシーの connect-src に入る |
spring.flutter.web.dev-server の下の未知のキーは警告です。spring.flutter.web の直下で dev-server、seo、page 以外のキー (古い spring.flutter.web.port) はビルドを失敗させ、新しいキーを示します。Web 開発サーバー を参照してください。
ページローダーとページのヘッド: spring_flutter_page_loader
spring_boot_starter_flutter に依存し、web/index.html を持つパッケージで動きます。
| プロパティ | 読み方 | 変えるもの |
|---|---|---|
spring.flutter.theme.active、.system-light、.system-dark |
すべてのファイル (方法 2) | ページローダーがどのテーマのスプラッシュを表示するか。system (または未設定) では、ライトのものと、prefers-color-scheme: dark の下ではダークのもの |
spring.flutter.theme.splash.* と spring.flutter.theme.loaders.* (themes.<name>. の下も) |
すべてのファイル | <!-- spring:loader:start --> と <!-- spring:loader:end --> の間のページローダーのブロック: 背景、ロゴ、タイトル、ローダーとその CSS 変数。スプラッシュがなければブロックは取り除かれる |
spring.flutter.theme.loaders.<name>.web、.web-sha256 |
すべてのファイル | 独自のローダーの種類の HTML ファイル (ローカルまたはダウンロード) と、ダウンロードしたものを固定するハッシュ |
テーマの色 (colors.*、シード、参照) |
すべてのファイル | ブロックの色。primary は <meta name="theme-color"> と theme_color に、surface はページの背景のブロックと background_color になる |
spring.remote.allow-insecure |
すべてのファイル、最初のもの | true でローダーの web: アドレスに素の http を許可する |
spring.flutter.app.title |
アプリと同じように、プロファイル web (方法 1) |
web/index.html の <title> と apple-mobile-web-app-title、web/manifest.json の name と short_name |
spring.flutter.app.description |
プロファイル web |
<meta name="description"> と web/manifest.json の description |
spring.flutter.web.page.max-pixel-ratio |
プロファイル web |
1 以上の数値: Flutter が描画するピクセル比に上限を設けるスクリプト。それ以外ではスクリプトなし |
spring.flutter.web.page.translate |
プロファイル web |
false: <html> に translate="no" と <meta name="google" content="notranslate"> を付け、キャンバスに描画されたページの翻訳をブラウザーが提案しないようにする。それ以外ではどちらもなし |
spring.flutter.web.page.swipe-to-close |
プロファイル web |
false: 下へのスワイプでページを開いたままにするブロック。それ以外ではブロックなし |
spring.web.resources.cache.cachecontrol.* |
プロファイル web |
web/_headers (なければ作られる) の # spring:cache:start と # spring:cache:end の間のブロック: すべてのパスに no-cache、/assets/* にキーから作った Cache-Control、ビルドのたびに変わるアセットに再び no-cache。キーがなければブロックは取り除かれる。読めない値はビルドを失敗させる。Web ビルドのブラウザーキャッシュ を参照 |
web プロファイルで設定を読み込めない場合、タイトル、説明、page.* キーは未設定とみなされ、web/_headers はそのまま残ります。理由は他のビルダーが報告します。ページローダー を参照してください。
検索エンジン向けのページ: spring_flutter_seo
すべてのパッケージで動きます。設定ファイルにテキスト seo が含まれる場合にだけ設定を読み込みます (方法 1、プロファイル web)。
| プロパティ | 変えるもの |
|---|---|
spring.flutter.web.seo.enabled |
true でページを書き出す。それ以外では何も書き出さず、以前に書き出したものを削除する |
spring.flutter.web.seo.site-url |
canonical、og:url、サイトマップのためのサイトのアドレス。有効にする場合は必須 |
spring.flutter.web.seo.from-routes |
true: ナビゲーションのルートがページになる |
spring.flutter.web.seo.title |
<title> のパターン。{title} がページのタイトル (デフォルトは {title}) |
spring.flutter.web.seo.description、.image、.site-name |
独自の値を持たないページのデフォルト。og:site_name |
spring.flutter.web.seo.content[n].location、.path、.exclude |
ページになる Markdown のフォルダー (resources: または asset:) |
spring.flutter.web.seo.exclude |
すべての Markdown フォルダーのうち、ページにならないファイル (**/contents*.md) |
spring.flutter.web.seo.pages[n].path、.title、.description、.image、.index |
手で指定するページと、ルートの内容の上書き |
spring.flutter.web.seo.sitemap |
false: sitemap.xml と robots.txt なし (デフォルトは true) |
spring.flutter.web.seo.llms |
false: llms.txt と llms-full.txt なし (デフォルトは true) |
spring.flutter.web.seo.markdown |
false: .md のコピーなし (デフォルトは true) |
spring.flutter.web.seo.page-files |
directory (<path>/index.html、デフォルト) または html (<path>.html) |
spring.flutter.navigation.languages |
ページは各言語で書き出される。最初の言語にはプレフィックスがない |
検索エンジン向けのページ を参照してください。
ディープリンク: spring_flutter_deep_links
すべてのパッケージで動きます。設定ファイルに deep-links または deepLinks が含まれる場合にだけ設定を読み込みます (方法 1、プラットフォームごとに一度)。
| プロパティ | 変えるもの |
|---|---|
spring.flutter.navigation.deep-links.enabled |
false で、それを設定したプロファイルのプラットフォームのブロックを取り除く |
spring.flutter.navigation.deep-links.scheme |
CFBundleURLTypes (iOS、macOS)、インテントフィルター (Android) |
spring.flutter.navigation.deep-links.domains |
Runner.entitlements の applinks:、検証済みのインテントフィルター、ドメインのファイル |
spring.flutter.navigation.deep-links.exclude |
apple-app-site-association の除外されるコンポーネント |
spring.flutter.navigation.deep-links.app-id |
apple-app-site-association のアプリ ID |
spring.flutter.navigation.deep-links.package |
assetlinks.json のパッケージ |
spring.flutter.navigation.deep-links.sha256-cert-fingerprints |
assetlinks.json のフィンガープリント。これがなければファイルは書き出されない |
redirect-uri (OAuth2 の登録の spring.security.oauth2.client.registration.<id>.redirect-uri) |
すべてのファイルのテキストから検索される: ディープリンクのスキームへのリダイレクトは警告 |
ディープリンク を参照してください。
JSON Schema のクラス: spring_json_schemas
設定に schemas を含むパッケージで動きます。設定は方法 1 と同じくプロファイルなしで読みます。
| プロパティ | 変えるもの |
|---|---|
spring.json.schemas[n].location |
読み込む、またはダウンロードするスキーマ。resources:、https://、http://、github: |
spring.json.schemas[n].sha256 |
ダウンロードが持つべきダイジェスト。別のものは拒否される |
spring.json.schemas[n].prefix |
スキーマのクラスの名前の先頭 |
spring.json.schemas[n].name |
ルートクラスの名前 |
JSON Schema のクラス を参照してください。
ビルド時のキーを置く場所
| キーを読むもの | 置く場所 |
|---|---|
spring_core_dart (AutoConfigurationBuild) |
application.yml または application.properties |
| Web のビルダー (開発サーバー、SEO、ページのヘッド) | application.yml または application-web.yml |
| ディープリンク | application.yml、または一つのプラットフォーム向けならそのプラットフォームのファイル (application-ios.yml、application-android.yml、application-macos.yml) |
spring_json_schemas (spring.json.schemas) |
application.yml または application.properties |
| 型付きキーとページローダーのテーマ | 任意のファイル。各キーは一つのファイルにまとめる |
そしてどの場合も、リテラルの値か、デフォルト付きのプレースホルダーにします。環境変数や --dart-define からの値はアプリには届きますが、ビルドには決して届きません。