ビルドが読むプロパティ

ほとんどのプロパティは、アプリが起動時に読みます。いくつかはそれより前、build_runner の実行中にジェネレーターが読みます。それらは、どのコードが生成されるか、どのモジュールがコンパイルに含まれるか、lib/ の外のファイル (web/index.html、Info.plist、web_dev_config.yaml) に何が入るかを決めます。このページでは、それらすべてをビルダーごとにまとめ、各ビルダーがどの設定ファイルを読むかを示します。

使う理由

ビルド時に読まれるプロパティは、実行時に読まれるものとは異なる振る舞いをします。

例

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

ローダーが読むもの (順に):

  1. lib/resources/ と lib/resources/config/ の application.properties、.yml、.yaml。
  2. 追加されたプロファイルのファイル (application-web.yml)。アプリと同じく、手順 1 のファイルより優先されます。
  3. それらのファイルの spring.profiles.active (と .include、.group.*) が指定するプロファイルのファイル、そしてアクティブなものがなければ default プロファイルのファイル (application-default.yml)。
  4. spring.config.import が resources: で指定するファイル (パッケージ自身の lib/resources/ から) と、spring.config.activate.on-profile が一致するドキュメント。

知りえないものと、その代わりにすること:

これらのビルダーはパッケージ自身の 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 ページは各言語で書き出される。最初の言語にはプレフィックスがない

検索エンジン向けのページ を参照してください。

すべてのパッケージで動きます。設定ファイルに 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 からの値はアプリには届きますが、ビルドには決して届きません。