静的リソース
lib/resources/static/ (または lib/resources/public/) のファイルはそのまま配信されます。lib/resources/static/app.css は GET /app.css に応答し、lib/resources/static/index.html は / のウェルカムページになります。Flutter Web のビルドなど、その他のフォルダーは file: のロケーションから配信されます。
使う理由
ほとんどの Web アプリケーションには、コードが手を加える必要のないファイルがあります。フロントエンド、画像、フォント、robots.txt などです。Spring Boot はコードなしで src/main/resources/static/ を配信し、このスターターも同様です。これにより、一つのプロセスが API とサイトの両方を、一つのオリジンで CORS なしに配信できます。スターターは、優れた静的ファイルサーバーが行うことも行います。
- 正しい
Content-Type。内容から推測することはありません。 ETagとLast-Modified。ファイルを持っているブラウザーには304 Not Modified。- 設定に基づく
Cache-Control。 - バイト範囲と
HEAD。 - 事前圧縮された
.brと.gzファイル。 - シングルページアプリのディープリンク (
/books/42はindex.htmlを受け取る)。 - 厳格なパスのチェック。どのリクエストもロケーションの外のファイルを読めません。
例
Flutter Web アプリとその API を一つのサーバーで:
my_app/
build/web/ # flutter build web
index.html
main.dart.js
flutter_bootstrap.js
assets/...
lib/resources/
application.yaml
static/robots.txt # 実行ファイルに埋め込まれる
# lib/resources/application.yaml
spring:
web:
resources:
static-locations: file:build/web/, resources:static/
spa-fallback: true # ブラウザーで開いた /books/42 は index.html を受け取る
directory-index: true # /guide は guide/index.html を受け取る
cache:
cachecontrol:
no-cache: true # 常に再検証する: 変更がなければ 304
chain:
compressed: true # ブラウザーが受け付けるなら main.dart.js.br / .gz
mvc:
static-path-pattern: /** # デフォルト
server:
mime-mappings:
wasm: application/wasm
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
// API はそのパスを保つ: コントローラーはファイルより先に問い合わされる。
@RestController()
@RequestMapping('/api')
class BookController {
@GetMapping('/books')
List<String> books() => ['Dune', 'Foundation'];
}
// 独自のキャッシュ設定を持つマッピングを追加する。
@Configuration()
class WebConfig with WebMvcConfigurer {
@override
void addResourceHandlers(ResourceHandlerRegistry registry) {
// フィンガープリント付きのファイルは決して変わらない: ブラウザーに 1 年間保持させる。
registry
.addResourceHandler(['/static-assets/**'])
.addResourceLocations(['file:build/web/static-assets/'])
.setCacheControl(
CacheControl.maxAge(const Duration(days: 365)).cachePublic().immutable(),
);
}
}
ファイルの読み込み元
ロケーションは次のいずれかです。
| プレフィックス | 意味 | 例 |
|---|---|---|
resources: |
lib/resources/ のフォルダー。ジェネレーターがこれらのファイルを実行ファイルに埋め込む。テストと dart run では、ディスク上のフォルダーとテストのリソースディレクトリも探す。 |
resources:static/ |
file: |
実行時に読むディレクトリ。作業ディレクトリからの相対パス、または絶対パス。 | file:build/web/、file:/srv/shop/web/ |
- 末尾の
/がなければ追加されます。 - ファイルを持つ最初のロケーションがそれを配信します。
- 存在しないロケーションは何も見つけず、何も失敗させません。起動後に作られたディレクトリは、その時点から見つかります。
- その他のプレフィックス (
classpath:、https:) は起動を止めます。resources:だけの指定も同様です。lib/resources/の設定ファイルを配信してしまうためです。 - ジェネレーターが埋め込むのは 1 MB までのファイルです。大きなファイルや Flutter のビルド全体は
file:のロケーションに置いてください。AOT 実行ファイルは、そのフォルダーを隣に置いて配布します。
リクエストが受け取るもの
- コントローラーが優先されます。 静的リソースはすべてのコントローラーの後に問い合わされる (そのハンドラーマッピングの順序は
Ordered.lowestPrecedence - 1) ため、マッピングは常にそのパスを保ちます。 - フィルターが先に実行されます。他のリクエストと同じく、セキュリティのフィルターチェーンも含みます。
HandlerInterceptorは実行されません。コントローラーのメソッドのためのものです。 - マッピングのうち最も具体的なパターンがリクエストを配信します。
/**より/static-assets/**が先です。 - ファイルを読むのは
GETとHEADだけです。OPTIONSはAllow: GET,HEAD,OPTIONS付きの200を受け取り、CORS のプリフライトは CORS のルールから応答され、その他のメソッドは405を受け取ります。 - ファイルのないパスは次のハンドラーマッピングへ進み、最終的にディスパッチャーの
404になります。ディレクトリの一覧が出ることは決してありません。 - コンテキストパス (
server.context-path) は、すべてのマッピングと同じく、すべてのファイルパスの前に付きます。
ファイルへの応答:
| ヘッダー | 値 |
|---|---|
Content-Type |
拡張子から決まる: server.mime-mappings、次に組み込みの型 (ダウンロード を参照)、apple-app-site-association には application/json、それ以外は application/octet-stream。内容から推測することはない。 |
X-Content-Type-Options |
nosniff。ブラウザーにも推測させない。 |
ETag |
弱いタグ: ファイルなら長さと更新時刻、埋め込みファイルなら長さとハッシュ。 |
Last-Modified |
ファイルの更新時刻 (埋め込みファイルにはない)。cache.use-last-modified=false の場合を除く。 |
Cache-Control |
cache.period または cache.cachecontrol.* から。デフォルトではなし。304 にも付く。 |
Accept-Ranges |
bytes。 |
Content-Encoding、Vary |
事前圧縮されたバリアントの場合 (chain.compressed)。 |
ETagを持つIf-None-Match(弱い比較)、またはIf-None-Matchがない場合にLast-Modified以降のIf-Modified-Sinceには304 Not Modifiedを返します。Last-Modifiedより前のIf-Unmodified-Sinceは412です。- 一つの
Rangeは206、末尾を超えれば416です。日付付きのIf-Rangeは、そのバージョンに対してだけ範囲を適用します。ETagは弱いため、タグ付きのIf-Rangeは決して一致せず、ファイル全体が送られます。ルールは ダウンロード にあります。 - 大きなファイルはディスクからストリーミングされ、全体を読み込むことはありません。
ウェルカムページ
HTML を受け付けるクライアントからの GET / は、/index.html が受け取るのと同じ index.html を受け取ります。
spring.mvc.static-path-pattern=/**(デフォルト) かつspring.web.resources.add-mappings=trueの場合だけです。- 「HTML を受け付ける」とは、
text/htmlを 0 より大きい品質で含むAcceptのことで、*/*も含みます。Acceptヘッダーがない場合は*/*とみなします。 - その他のフォルダーが
index.htmlを受け取るのはdirectory-indexの場合だけです。
フォルダーのページ: directory-index
spring.web.resources.directory-index=true にすると、ファイルのないパスで、そのフォルダーに index.html があれば、そのファイルを受け取ります。静的ホスティング (Cloudflare Pages、Netlify) と同じく、/guide と /guide/ はどちらも guide/index.html で応答されます。
index.htmlは他のファイルと同じく、ロケーションの中で、すべてのセグメントに同じチェックをして探されます。- シングルページのフォールバックより先に試されます。
- パスごとに事前レンダリングされたページに使います。Flutter スターターが検索エンジン向けに書き出すページ (
spring.flutter.web.seo.*) や、ドキュメントサイトなどです。
シングルページアプリ: spa-fallback
シングルページアプリ (Flutter Web のビルド、JavaScript のルーター) は index.html を一つだけ持ち、ブラウザーの中でルーティングします。ユーザーが /books/42 を直接開いたり、そこでページを再読み込みしたりすると、サーバーにはそのようなファイルがありません。spring.web.resources.spa-fallback=true にすると、そうしたリクエストは index.html を受け取り、アプリのルーターがそのページを開きます。
フォールバックは、次のすべてが成り立つ場合にだけ適用されます。
- メソッドが
GETまたはHEADである。 - そのパスに応答するコントローラーもファイルもない。
- 最後のセグメントに拡張子がない (
/books/42は該当し、/books/42.jsonや/main.dart.jsは該当しない)。 - パスが
.well-known/の下にない (ディープリンクの検証は HTML ではなく404を見る必要がある)。 Acceptヘッダーがtext/htmlを 0 より大きい品質で指定している。ブラウザーのナビゲーションはそうしますが、存在しない API パスへのスクリプトのfetchは*/*を送るので該当しません。
それ以外はすべて 404 のままです。存在しないスクリプト、存在しない画像、コードが呼んだ不明な API パスなどです。
配信される index.html は /index.html が受け取るものなので、フォールバックには /index.html を含むマッピングが必要です (デフォルトの /** は含みます)。
事前圧縮ファイル: chain.compressed
spring.web.resources.chain.compressed=true にすると、app.js の隣にある app.js.br または app.js.gz が、それを Accept-Encoding で受け付けるクライアントに app.js の代わりに送られます。
- Brotli (
.br) が先に試され、次に gzip (.gz) です。q=0のコーディングは使われません。 - 応答には
Content-Encoding: brまたはgzip、元のファイルのContent-Type、バリアント自身のETagが付きます。 - バリアントが存在する場合は、クライアントがどれも受け付けないときでも
Vary: Accept-Encodingが追加され、キャッシュがバージョンを区別して保持します。 server.compressionがそれを再び圧縮することはありません。- バリアントはビルド時に作ります (
brotli -k、gzip -k)。最高の圧縮レベルでも実行時のコストはかかりません。
server.compression.enabled=true は、圧縮可能な型のその他のファイルをその場で gzip 圧縮します。レスポンスの圧縮 を参照してください。
パスのセキュリティ
リクエストがロケーションの外を読むことは決してありません。パスは一度だけデコードされ、ファイルを探す前にチェックされます。次のものは拒否され、リクエストは 404 になります (一部はサーバーの段階ですでに 400 になります)。
.と..のセグメント、エンコードまたは二重エンコードされた区切り文字やドット (%2e%2e、%252e)、バックスラッシュ。- 空のセグメント (
a//b) と、パス中のあらゆる;(..;x、マトリックスパラメーター)。 - 不正な UTF-8 (冗長な形式、単独のサロゲート)、制御文字、空白、その他リクエストターゲットに生のまま含まれることのない文字。
- Windows のデバイス名 (
CON、NUL、COM1など)、短い名前 (PROGRA~1)、代替データストリーム (:)、ワイルドカード、末尾のドットと空白。 - ドットやスラッシュに見える文字 (全角やその他の紛らわしい形)。
- Spring と同じく、大文字小文字を問わず
WEB-INFとMETA-INF。 - 隠しファイル: ドットで始まるセグメント (
.env、.git/)。ただし最初のセグメントの.well-knownは除くため、/.well-known/assetlinks.jsonと/.well-known/apple-app-site-associationは機能します。
見つかったファイルはシンボリックリンクを解決したうえで、ロケーションの外に出る場合、実際のパスのセグメントが許可されない場合、通常のファイルでない場合 (ディレクトリ、パイプ、デバイス) に拒否されます。
プロパティ
spring.web.resources.static-locations
| 型 | デフォルト |
|---|---|
List<String> |
resources:static/, resources:public/ |
デフォルトのマッピングのファイルを順に読む場所です。ファイルを持つ最初のロケーションが採用されます。カンマ区切りか YAML のリストで指定します。Flutter のビルド (file:build/web/) やサーバー上のディレクトリ (file:/srv/shop/web/) を配信するときに変更します。設定するとデフォルトが置き換えられるため、resources:static/ も必要なら改めて列挙してください。
spring:
web:
resources:
static-locations:
- file:build/web/
- resources:static/
Spring Boot のデフォルトには classpath:/META-INF/resources/ と classpath:/resources/ も含まれますが、Dart には jar がないため除かれており、classpath: は resources: と書きます。
spring.mvc.static-path-pattern
| 型 | デフォルト |
|---|---|
String |
/** |
デフォルトのマッピングがファイルを配信するパスパターンです。/** なら static/app.css を /app.css として、/assets/** なら /assets/app.css として配信します。ファイルをプレフィックスの下にまとめ、他のパスと干渉しないようにするときに変更します。/** 以外のパターンではウェルカムページがなく、別のマッピングが含まない限り、シングルページのフォールバックは /index.html を見つけられません。
spring:
mvc:
static-path-pattern: /assets/**
spring.web.resources.add-mappings
| 型 | デフォルト |
|---|---|
bool |
true |
false は、デフォルトのマッピング (static-path-pattern の下の static-locations) とウェルカムページを無効にします。WebMvcConfigurer が追加するマッピングは残ります。ファイルを配信しない API や、独自のマッピングだけを使いたい場合に使います。
spring:
web:
resources:
add-mappings: false
spring.web.resources.spa-fallback
| 型 | デフォルト |
|---|---|
bool |
false |
前述の「シングルページアプリ」で説明したとおり、ファイルでもハンドラーでもないパスへのブラウザーのナビゲーションに index.html を配信します。パス形式の URL (usePathUrlStrategy) を使う Flutter Web アプリや、任意のクライアントサイドルーターで有効にします。このキーはこのスターター独自のもので、Spring Boot にはこのプロパティはありません。
spring.web.resources.directory-index
| 型 | デフォルト |
|---|---|
bool |
false |
前述の「フォルダーのページ」で説明したとおり、フォルダーのパスに対してそのフォルダーの index.html を配信します。ウェルカムページが / だけを対象とする Spring Boot と同じく、デフォルトでは無効です。このキーはこのスターター独自のものです。
spring.web.resources.chain.compressed
| 型 | デフォルト |
|---|---|
bool |
false |
前述の「事前圧縮ファイル」で説明したとおり、事前圧縮された .br と .gz のバリアントを配信します。ビルドがそれらを書き出す場合に有効にします。
spring.web.resources.cache.period
| 型 | デフォルト |
|---|---|
Duration |
なし |
デフォルトのマッピングのすべてのファイルに対する Cache-Control: max-age=<seconds> です。ブラウザーが問い合わせずにファイルを使える時間を表します。単位のない数値は秒 (3600) で、単位も使えます (1h、7d)。0 は Cache-Control: no-store を送ります。未設定なら Cache-Control ヘッダーはなく、ブラウザーは独自のヒューリスティックを使います。cache.cachecontrol.* のキーがあればそれに置き換えられます。
spring:
web:
resources:
cache:
period: 1h
spring.web.resources.cache.use-last-modified
| 型 | デフォルト |
|---|---|
bool |
true |
ファイルの更新時刻を Last-Modified として送り、If-Modified-Since と照合するかどうかです。更新時刻に意味がない場合 (ロードバランサーの背後のサーバーごとに、デプロイ時に新しい日付でコピーされたファイルなど) は無効にします。その場合も ETag によって 304 は返されます。埋め込みファイルにはいずれにしても更新時刻がありません。
spring.web.resources.cache.cachecontrol.*
Cache-Control ヘッダーをディレクティブごとに指定します。これらのキーのどれかが設定されていると、cache.period を置き換えます。ヘッダーは Spring Boot と同じ方法で組み立てられます。設定されていればまず no-store、なければ設定されていれば no-cache、なければ設定されていれば max-age、その後にその他のディレクティブです。
| キー | 型 | デフォルト | ディレクティブと意味 |
|---|---|---|---|
spring.web.resources.cache.cachecontrol.max-age |
Duration |
なし | max-age=<seconds>: 問い合わせずに応答を再利用できる時間。単位のない数値は秒。no-store または no-cache が設定されていると無視される。 |
spring.web.resources.cache.cachecontrol.no-cache |
bool |
なし | no-cache: 保存はできるが、サーバーが確認した後にのみ再利用する (ETag による安価な 304)。max-age より優先される。 |
spring.web.resources.cache.cachecontrol.no-store |
bool |
なし | no-store: 決して保存しない。no-cache と max-age より優先される。 |
spring.web.resources.cache.cachecontrol.must-revalidate |
bool |
なし | must-revalidate: 古くなったら、オフラインでも、サーバーに問い合わせずには使わない。 |
spring.web.resources.cache.cachecontrol.no-transform |
bool |
なし | no-transform: プロキシは内容を変更してはならない (画像の再圧縮など)。 |
spring.web.resources.cache.cachecontrol.cache-public |
bool |
なし | public: 共有キャッシュ (CDN、プロキシ) も保存できる。 |
spring.web.resources.cache.cachecontrol.cache-private |
bool |
なし | private: ユーザー自身のブラウザーだけが保存できる。 |
spring.web.resources.cache.cachecontrol.proxy-revalidate |
bool |
なし | proxy-revalidate: 共有キャッシュだけに対する must-revalidate。 |
spring.web.resources.cache.cachecontrol.s-max-age |
Duration |
なし | s-maxage=<seconds>: 共有キャッシュが保持できる時間。共有キャッシュに対しては max-age を上書きする。 |
spring.web.resources.cache.cachecontrol.stale-while-revalidate |
Duration |
なし | stale-while-revalidate=<seconds>: 新しい応答をバックグラウンドで取得する間、古い応答を使える時間。 |
spring.web.resources.cache.cachecontrol.stale-if-error |
Duration |
なし | stale-if-error=<seconds>: サーバーが失敗したときに古い応答を使える時間。 |
# max-age=60, must-revalidate, no-transform, public, proxy-revalidate,
# s-maxage=30, stale-if-error=5, stale-while-revalidate=10
spring:
web:
resources:
cache:
cachecontrol:
max-age: 60
must-revalidate: true
no-transform: true
cache-public: true
proxy-revalidate: true
s-max-age: 30
stale-if-error: 5
stale-while-revalidate: 10
どれを選ぶか:
- 内容とともに名前が変わるファイル (フィンガープリント付き:
app.3f9a.js): 1 年のmax-age、public、そしてWebMvcConfigurerのマッピングでimmutable(immutableのプロパティはありません)。 - 名前が変わらないファイル (
index.html、Flutter のビルドのmain.dart.js):no-cache。ブラウザーは毎回問い合わせ、変更がなければ本文のない304を受け取るため、新しいデプロイがすぐに反映されます。 - プライベートなファイルはそもそも静的リソースにするべきではありません。アクセスをチェックするコントローラーから配信してください。
同じキーは、静的ホストに置く Flutter の Web ビルドのヘッダーも決めます。Flutter アプリの設定にあれば、ジェネレーターがそれを Cloudflare Pages と Netlify 向けの web/_headers に書き込みます。そこでは値はアプリのアセット (/assets/*) にだけ付き、ハッシュのないファイルには no-cache が付きます。Web ビルドのブラウザーキャッシュ を参照してください。
server.mime-mappings.*
| 型 | デフォルト |
|---|---|
Map<String, String> |
空 |
組み込みのものに加えて、ファイルの拡張子ごとのメディアタイプを追加します。ここに列挙した拡張子が優先されます。拡張子は大文字小文字を区別せず、先頭のドットの有無にかかわらず照合されます。ファイルに必要で、組み込みの表にない型を追加してください。
server:
mime-mappings:
wasm: application/wasm
glb: model/gltf-binary
epub: application/epub+zip
マッピングの追加: addResourceHandlers
WebMvcConfigurer Bean は、独自のパターン、ロケーション、キャッシュ設定を持つマッピングを追加します。spring.mvc.static-path-pattern と同じパターンのマッピングは、デフォルトのものを置き換えます。
ResourceHandlerRegistry |
意味 |
|---|---|
addResourceHandler(List<String> pathPatterns) |
パターンのマッピングを追加し、その登録を返す。 |
hasMappingForPattern(String pattern) |
ちょうどこのパターンをマッピングする登録があるかどうか。 |
registrations |
追加された順の登録。 |
ResourceHandlerRegistration |
デフォルト | 意味 |
|---|---|---|
addResourceLocations(List<String> locations) |
なし | resources: または file: のロケーションを、すでに追加されたものの後に追加する。 |
setCachePeriod(int? seconds) |
null |
Cache-Control: max-age=<seconds>。0 は no-store を送り、null は何も送らない。 |
setCacheControl(CacheControl? cacheControl) |
null |
Cache-Control 全体。setCachePeriod より優先される。 |
setUseLastModified(bool use) |
true |
Last-Modified を送ってチェックするかどうか。 |
setCompressed(bool compressed) |
false |
事前圧縮された .br と .gz のバリアントを配信するかどうか。 |
どのメソッドも登録を返すため、呼び出しを連鎖できます。デフォルトのマッピングは spring.web.resources.* の設定を受け取り、自分で追加したマッピングは、そこに設定したものだけを受け取ります。
@Configuration()
class DocsConfig with WebMvcConfigurer {
@override
void addResourceHandlers(ResourceHandlerRegistry registry) {
// /docs/ の下のハンドブックを専用のフォルダーから配信し、再検証させる。
registry
.addResourceHandler(['/docs/**'])
.addResourceLocations(['file:/srv/handbook/'])
.setCacheControl(CacheControl.noCache())
.setCompressed(true);
}
}
ロケーションのファイルを自分のコード (コントローラーやフィルター) から配信するには、ResourceHttpRequestHandler(locations: [...]) を作ります。getResource(path) は同じチェックの後にファイルを見つけ、handleResource(found, request, response, writer) はそのファイルで応答します。writer には ResponseWriter Bean を渡します。
CORS
グローバルな CORS のルールはファイルにも適用されます。WebMvcConfigurer の addCorsMappings、または corsConfigurationSource という名前の CorsConfigurationSource Bean です。@CrossOrigin はコントローラーのためのものなので適用されません。CORS を参照してください。
Spring (Java) との対応
spring.web.resources.static-locations=classpath:/static/,file:build/web/
spring.web.resources.cache.cachecontrol.max-age=1h
重要な違い:
- ロケーションは
classpath:ではなくresources:とfile:です。その他のプレフィックスは起動を止めます。 spa-fallbackとdirectory-indexはこのスターター独自のキーです。- 事前圧縮ファイルは
chain.compressed(プロパティ) またはsetCompressed(マッピング) で指定します。Spring はresourceChain(true).addResolver(new EncodedResourceResolver())を使います。spring.web.resources.chain.enabled、chain.cache、バージョン戦略、webjars のマッピングはサポートされません。 - チェックはより厳格です。ドットファイルは配信されず (
.well-known/は配信されます)、;と空のセグメントは404になり、ロケーションの外に出るシンボリックリンクは拒否され、Windows だけが別のファイルとして読むパスも拒否されます。 - ファイルには弱い
ETag(Spring はetagGeneratorを設定しない限り送りません)、X-Content-Type-Options: nosniff(Spring では Spring Security が追加します)、そして304にもCache-Controlが付きます。 - ファイルのないパスはディスパッチャーの
404(No endpoint GET /x.) になります。Spring 6.1 はNo static resource x.と応答します。
関連項目
- ダウンロード: コントローラーからのファイル
- WebMvcConfigurer
- レスポンスの圧縮
- フィルター
- CORS
- Flutter の Web ビルドのブラウザーキャッシュ
- すべてのプロパティ