
# 埋め込みリソース

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

## 使う理由

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

- AOT 実行ファイルは単一のファイルで、通常その隣にプロジェクトのフォルダーはありません。
- スマートフォン上の Flutter アプリにはプロジェクトのフォルダーがまったくなく、宣言されたアセットを通してしかファイルを読めません。
- Web アプリにはファイルシステムがありません。

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

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

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

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

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

```dart
_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/` の下のすべてのファイル**。深さに関係なく、`.dart` ファイルを除きます。キーは `lib/resources/` の下のパスで、区切りは `/` です。
- **パスでソート**されるので、出力はどのマシンでも同じです。
- **テキストか base64。** バイト列が有効な UTF-8 であるファイルは `EmbeddedResource.text` になり、それ以外のファイルは `EmbeddedResource.base64` になります。そのため、別のエンコーディングのテキストファイル (ISO-8859-1 の `.properties` ファイル) は base64 として埋め込まれ、インポートがエンコーディングを指定していれば設定の読み込み処理がそれをデコードします。
- **ファイルごとに最大 1 MB。** 1,048,576 バイトを超えるファイルはビルドの警告とともにスキップされます。

```text
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/` を埋め込みます。

- `@SpringBootApplication` の出力 `$application`。
- ライブラリやスターターのものを含む、すべての `@ComponentScan` モジュール。ライブラリ自身のファイル (デフォルトの設定、テンプレート) は、モジュールとともに、それを使うすべてのアプリケーションに運ばれます。

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

## 実行時

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

- **パスの最初の登録が優先されます**。Java で最初のクラスパスエントリーが優先されるのと同じです。後から同じパスで登録されたファイルは無視されます。
- **ホットリロード。** ファイルはモジュールの名前で登録されるので、ホットリロードの後に再び生成されたモジュールは自身の以前のファイルを置き換え、変更された `application.properties` が反映されます。
- **ディスク上のディレクトリが先です。** `spring_boot_starter_test` は `test/resources/` を追加し、それは埋め込みファイルより先に検索されるので、テストの設定ファイルがパッケージ化されたものより優先されます。
- **埋め込まれていないパス** (`build_runner` を実行せずに追加したファイル) は、作業ディレクトリからの相対パス `lib/resources/<path>` に存在すれば、そこから読まれます。
- **`resources:` は外に出られません。** `lib/resources/` より上を指す `..` を含む場所 (`resources:../../secret`) は何も見つけません。

`Resource` の API と場所のプレフィックスについては [リソース](../spring-core-dart/resources/index.md) を参照してください。

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

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

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

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

```text
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` エンドポイントがそれを表示します。ジェネレーターは、アクチュエーターを使うアプリケーションに対して同じことを行います。次の場合:

- パッケージがアプリケーションである (`pubspec.yaml` に `publish_to: none`)。
- その `dependencies` に `spring_boot_actuator` または `spring_boot_starter_actuator` がある。
- どのリソースフォルダーにも独自の `build-info.properties` がない。

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

```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`](../spring-search-dart/searching.md#ビルドが書くインデックス)) があり、それだけで有効・無効にできます。

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

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

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

```yaml
# lib/resources/application.yml
spring:
  resources:
    embed:
      exclude: [content/**, images/**]
```

```yaml
# pubspec.yaml
flutter:
  assets:
    - lib/resources/content/
    - lib/resources/content/docs/
    - lib/resources/images/
```

- 外されたファイルは Flutter のアセットになります。場所は変わりません。埋め込まれていない `resources:content/docs/beans.md` は、アプリのアセットから見つかります。モバイルやデスクトップのアプリではファイルはパッケージの中にあり、Web ではファイルは読まれたときにだけダウンロードされます。
- Flutter のアセットのディレクトリは、そのディレクトリ自身のファイルだけを含み、サブディレクトリのファイルは含みません。外したファイルがあるディレクトリは、すべて列挙してください。足りないものがあると、ビルドが追加すべき行をそのまま表示します。

```text
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/
```

- 設定は、glob に関係なく常に埋め込まれます。`application*.yml`、`application*.properties`、すべての `.properties` ファイル、`config/` の中のすべてです。起動時にすぐ読まれるためです。
- リストでも、カンマ区切りの glob の一つのテキストでも使えます (`spring.resources.embed.exclude=content/**,images/**`)。ビルドは `lib/resources/` の設定ファイルからこのキーを読みます。
- 1 MB の上限は、埋め込まれるファイルにだけ適用されます。
- 埋め込まれ、しかも `flutter: assets:` にもあるファイルはバイナリから読まれます。アプリがそれを単独でダウンロードすることはありません。`build/web/assets/` に無駄にコピーされるだけなので、除外しないものは `pubspec.yaml` に書かないでください。

同期読み込み (`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 ファイルをダウンロード |

検索は、検索された言語のファイルだけを読みます。[ドキュメント](../spring-search-dart/documents.md#markdown-ファイル)を参照してください。

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

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

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

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

```yaml
# pubspec.yaml
flutter:
  assets:
    - lib/resources/spring_gen/prefetch/
```

- ビルドは `lib/resources/spring_gen/prefetch/resources.json` を部分ごとに 1 行で書きます。埋め込みはしません。`pubspec.yaml` にディレクトリがないときは警告します。
- `stage: app`: スプラッシュが消えてから `delay` 後にダウンロードを始めます。最初のページとその画像が先に届き、PageSpeed にも数えられません。ファイルが届く前に開いたページは、これまでどおり単独でダウンロードされます。
- `stage: tasks`: スプラッシュがそれを待つので、最初のタップからすべてのページがそろいます。遅い回線ではスプラッシュが長くなります。
- ファイルはリソースとしてメモリーに置かれ、部分ごとに読まれるので、アプリは描画を続けます。`resources:` はすぐに見つけます。
- Web だけです。端末上のアプリはアセットを端末から読みます。
- テキストファイルだけです。このサイトでは、両言語の全ページが brotli で 1.2 MB、1 回のリクエストに入っています。

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

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

## ヒント

- `lib/resources/` のファイルを変更したら `build_runner` を実行してください。開発中は生成されたモジュールにないファイルもディスクから読まれますが、AOT 実行ファイルや Flutter アプリには埋め込まれたものしかありません。
- 秘密情報を `lib/resources/` に置かないでください。埋め込まれたファイルはコンパイルされたプログラムの中にあり、プログラムを持つ誰もがそれを読めます。`${SUPPLIER_API_KEY:}` のようなプレースホルダーを使い、値は環境から設定してください。
- 生成コードはファイルを文字列リテラルとして保持します。大きなテキストファイルは生成される `.spring.dart` ファイルも大きくし、エディターでの扱いが悪くなります。

## Spring (Java) との対応

```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` の再実行が必要なことです。

## 関連項目

- [リソース](../spring-core-dart/resources/index.md)
- [Resource](../spring-core-dart/resources/resource.md)
- [静的リソース](../spring-boot-starter-web/static-resources.md)
- [@SpringBootApplication](spring-boot-application.md)
