埋め込みリソース

ジェネレーターは、デフォルトでパッケージの lib/resources/ のすべてのファイルを、Dart の文字列定数として生成されたモジュールにコピーします。実行時にモジュールがそれらを登録し、resources: の場所 (resources:application.yml、resources:templates/mail.txt) はメモリーからそれらを読みます。これは dart run、AOT 実行ファイル、Flutter、Web で同じように動き、アセットの宣言も不要です。

使う理由

Spring では、src/main/resources/ は jar の中のクラスパスに入り、classpath: の場所はそこから読みます。Dart のプログラムにはクラスパスがありません。

ビルド時にファイルを埋め込むと、どのプラットフォームでもファイルがプログラムの一部になります。application.properties、メッセージバンドル、テンプレート、小さなデータファイルは、pubspec.yaml の flutter: assets: エントリーも、プラットフォームごとに異なるコードもなしに、プログラムが動くどこででも見つかります。

ジェネレーターが書き出すもの

次のフォルダーに対して:

lib/resources/
  application.properties
  banner.txt
  covers/default.png
  data/books.json

モジュールは resources: 引数を受け取ります (リポジトリのサーバーガイドからの抜粋、テキストは短縮)。

_i1.BeanModule get $application => _i1.BeanModule(
  r'application',
  [/* ... */],
  resources: const {
    r'application.properties': _i1.EmbeddedResource.text(
      '# NEON Books server: the configuration every profile shares.\n...',
    ),
    r'banner.txt': _i1.EmbeddedResource.text(
      ' _  _ ___ ___  _  _   ___           _\n...',
    ),
    r'covers/default.png': _i1.EmbeddedResource.base64(
      r'iVBORw0KGgoAAAANSUhEUgAAAHgAAAC0CAIAAADQLH9KAAABCUlEQVR42u3QQQ0A...',
    ),
    r'data/books.json': _i1.EmbeddedResource.text(
      '[\n  {"isbn": "9780441013593", "title": "Dune", ...}\n]\n',
    ),
  },
);

ルール:

lib/resources/static/main.dart.js is larger than 1048576 bytes and is not embedded;
ship it as a Flutter asset or a file instead.

この上限があるのは、埋め込まれたファイルがプログラムにコンパイルされるからです。一つ一つが実行ファイル、アプリ、JavaScript バンドルを大きくし、それと一緒に読み込まれます。大きなファイルは別の場所に置くべきです。Flutter のアセット (asset: の場所)、実行ファイルの隣のファイル (file: の場所)、またはダウンロードです。たとえば、spring_boot_starter_web が配信する Flutter Web のビルドは、main.dart.js と canvaskit.wasm が上限より大きいため、spring.web.resources.static-locations: file:... でフォルダーから読まれます。

どのモジュールが埋め込むか

生成されるすべてのモジュールが、そのパッケージの lib/resources/ を埋め込みます。

パッケージに両方がある場合、両方のモジュールが同じファイルを持ちます。実行時のコストはありません。パスは一度だけ登録されます。

実行時

モジュールは、生成されるとき、設定ファイルが読まれる前にそのファイルを登録します。

Resource の API と場所のプレフィックスについては リソース を参照してください。

lib/ の外にあるアプリケーション

main が lib/ にない (bin/、test/、example/ にある) アプリケーションは、複数のリソースフォルダーを受け取ります。ジェネレーターは、優先順位の低いものから順に次を埋め込みます。

  1. パッケージの lib/resources/。
  2. 続いて、最上位から main のディレクトリまでの各ディレクトリの <dir>/lib/resources/。

main が example/shop/bin/main.dart にある場合:

lib/resources/                     最も低い優先順位
example/lib/resources/
example/shop/lib/resources/
example/shop/bin/lib/resources/    最も高い優先順位

フォルダーが main に近いほど、優先順位が高くなります。二つのフォルダーに同じパスのファイルがある場合、近いほうのファイルがもう一方を完全に置き換えます。ファイルはマージされません。そのため、アプリケーションの設定がライブラリの設定より優先されるのと同じく、サンプルの example/lib/resources/application.properties はパッケージの lib/resources/application.properties より優先されます。一つのフォルダーにしかないファイルはすべて埋め込まれます。

存在しないフォルダーはスキップされます。main が lib/ にある場合は、lib/resources/ だけが読まれます。

@ComponentScan モジュールは常に lib/resources/ だけを埋め込みます。

アクチュエーターアプリの build-info.properties

Spring Boot のビルドプラグインは META-INF/build-info.properties を書き出し、アクチュエーターの info エンドポイントがそれを表示します。ジェネレーターは、アクチュエーターを使うアプリケーションに対して同じことを行います。次の場合:

@SpringBootApplication の出力は、pubspec.yaml から作った build-info.properties を埋め込みます。

build.artifact=neon_books_server
build.name=neon_books_server
build.version=1.4.0

pubspec.yaml に version がなければ build.version は省略されます。ビルド時刻は意図的に含めていません。含めると生成ファイルがビルドのたびに変わり、ホットリロードが使うフィンガープリントも変わってしまいます。時刻や他の値が必要なら、lib/resources/build-info.properties を自分で書いてください。その場合、ジェネレーターはそれをそのまま埋め込みます。

公開されたパッケージのサンプルは、リリースのたびに変わってしまうため、これを受け取りません。アクチュエーターは spring.info.build.location (デフォルトは resources:build-info.properties) からファイルを読みます。

ファイルがアプリに届く方法を選ぶ

lib/resources/ の各ファイルは、2 つのプロパティで選ぶ 4 つの方法のどれかで Flutter の Web アプリに届きます。読むコード (resources:content/...) はどの方法でも同じです。

方法 設定 最初の読み込み 別のページを開くとき
バイナリーの中 (デフォルト) なし アプリと一緒にすべてのファイルをダウンロード ダウンロードなし
1 つずつ spring.resources.embed.exclude: [content/**]、フォルダーを flutter: assets: に アプリだけ そのページのファイルをダウンロード
まとめて、アプリの表示後 上記に加えて spring.resources.prefetch.locations: ['content/**/*.md'] アプリだけ。表示中のページ、そしてスプラッシュの 1 秒後に残り全部が入った 1 ファイル そのファイルが届いた後はダウンロードなし
まとめて、スプラッシュの裏で 上記に加えて spring.resources.prefetch.stage: tasks 表示前にアプリと全部入りのファイル ダウンロードなし

組み合わせられます。exclude と prefetch.locations は glob なので、一部のファイルはバイナリーに残し (設定ファイルは常に残ります)、一部は 1 つずつ (画像)、一部はまとめて (ページ) にできます。検索には専用のファイル、ビルドが書くインデックス (spring.search.prebuilt) があり、それだけで有効・無効にできます。

まとめて届くファイルも Flutter のアセットのままです。最初に開いたページはまとめたファイルが届く前に自分のファイルから読まれ、まとめて届かなかったファイルも単独で届き、アプリは最初からどのファイルがあるかを知っています。

ファイルをバイナリーから外す

埋め込みは即座で、どこでも動きますが、すべてのバイトをプログラムに入れます。何百もの Markdown ページや多くの画像を持つサイトは、訪問者が読むのはわずかでも、そのすべてを抱えることになります。spring.resources.embed.exclude は、ビルドが埋め込まない lib/resources/ 以下の glob を並べます。

# lib/resources/application.yml
spring:
  resources:
    embed:
      exclude: [content/**, images/**]
# pubspec.yaml
flutter:
  assets:
    - lib/resources/content/
    - lib/resources/content/docs/
    - lib/resources/images/
spring.resources.embed.exclude leaves 2 directories out of the binary that are no
Flutter assets, so resources: finds nothing there at run time. Add to pubspec.yaml,
under flutter: assets: ...
    - lib/resources/content/
    - lib/resources/content/docs/

同期読み込み (readAsStringSync) は、埋め込まれたファイルでのみ動きます。アセットとして読まれるファイルは手元にバイト列がないので、readAsString と readAsBytes を使ってください。

埋め込む (デフォルト) 外す (アセット)
起動時に読む小さなファイル: テンプレート、小さなデータ 必要なときに読む多数または大きなファイル: ドキュメントのページ、画像
即座に読める。同期でも非同期でも 非同期読み込み。Web ではファイルごとに一回のダウンロード
バイナリーに含まれる バイナリーは小さいまま

このドキュメントサイトでの数値です。content/** を外した場合 (Markdown ファイル 834 個):

すべて埋め込み 外した場合
main.dart.wasm 11.6 MB 3.7 MB (圧縮後は約 1 MB)
JavaScript のフォールバック 14.5 MB 4.2 MB
ページを開く 834 個すべてのファイルを抱える そのページの Markdown 2 ファイルをダウンロード

検索は、検索された言語のファイルだけを読みます。ドキュメントを参照してください。

ファイルは lib/resources/ だけでなく flutter: assets: の下のどこにでも置け、asset:path として読めます。パターン、相対リンク、検索エンジン向けのページといった同じ機能が使えます。アセットとフォントを参照してください。

まとめてダウンロードする

バイナリーから外したファイルは、読むたびに 1 つずつダウンロードされます。サイトでは、訪問者が開くページごとに待ちが生じます。spring.resources.prefetch は、それらをアプリが表示されたあとに一度だけダウンロードする 1 つのファイルにまとめます。

spring:
  resources:
    embed:
      exclude: [content/**]
    prefetch:
      locations: ['content/**/*.md']   # ファイルに入れるもの
      stage: app                       # app (デフォルト) または tasks
      delay: 1s                        # アプリが表示されてから
# pubspec.yaml
flutter:
  assets:
    - lib/resources/spring_gen/prefetch/

アセットからの検索エンジン向けページ

spring_flutter_seo ビルダーは Markdown のフォルダーからページを作ります (検索エンジン向けのページを参照)。resources: のフォルダーに加えて asset: のフォルダーも読みます。対象は pubspec.yaml の Flutter アセットの Markdown ファイルです (ディレクトリのエントリーは、そのディレクトリ自身のファイルを与えます)。asset:docs/ を指すルートや spring.flutter.web.seo.content[n].location は、resources:content/docs/ と同じページを作ります。バイナリーから外されたファイルもページになります。

ヒント

Spring (Java) との対応

// src/main/resources/templates/mail.txt (jar の中)
Resource resource = new ClassPathResource("templates/mail.txt");

lib/resources/ は src/main/resources/ の役割を、resources: は classpath: の役割を果たします。違いは、ファイルが jar に詰められる代わりにビルド時に生成されたモジュールに埋め込まれること、1 MB を超えるファイルは除外されること、変更には build_runner の再実行が必要なことです。

関連項目