静的リソース

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 なしに配信できます。スターターは、優れた静的ファイルサーバーが行うことも行います。

例

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/

リクエストが受け取るもの

ファイルへの応答:

ヘッダー 値
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)。

ウェルカムページ

HTML を受け付けるクライアントからの GET / は、/index.html が受け取るのと同じ index.html を受け取ります。

フォルダーのページ: directory-index

spring.web.resources.directory-index=true にすると、ファイルのないパスで、そのフォルダーに index.html があれば、そのファイルを受け取ります。静的ホスティング (Cloudflare Pages、Netlify) と同じく、/guide と /guide/ はどちらも guide/index.html で応答されます。

シングルページアプリ: spa-fallback

シングルページアプリ (Flutter Web のビルド、JavaScript のルーター) は index.html を一つだけ持ち、ブラウザーの中でルーティングします。ユーザーが /books/42 を直接開いたり、そこでページを再読み込みしたりすると、サーバーにはそのようなファイルがありません。spring.web.resources.spa-fallback=true にすると、そうしたリクエストは index.html を受け取り、アプリのルーターがそのページを開きます。

フォールバックは、次のすべてが成り立つ場合にだけ適用されます。

それ以外はすべて 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 の代わりに送られます。

server.compression.enabled=true は、圧縮可能な型のその他のファイルをその場で gzip 圧縮します。レスポンスの圧縮 を参照してください。

パスのセキュリティ

リクエストがロケーションの外を読むことは決してありません。パスは一度だけデコードされ、ファイルを探す前にチェックされます。次のものは拒否され、リクエストは 404 になります (一部はサーバーの段階ですでに 400 になります)。

見つかったファイルはシンボリックリンクを解決したうえで、ロケーションの外に出る場合、実際のパスのセグメントが許可されない場合、通常のファイルでない場合 (ディレクトリ、パイプ、デバイス) に拒否されます。

プロパティ

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

どれを選ぶか:

同じキーは、静的ホストに置く 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

重要な違い:

関連項目