組み込みサーバー
spring_boot_starter_web は、アプリケーションの中で HTTP サーバーを動かします。サーバーはコンテキストの準備ができると起動し、コンテキストが閉じると停止します。設定は server.* プロパティで行います。
使う理由
HttpServer.bind やリクエストのループを書く必要はありません。Spring Boot が Tomcat を動かしてくれるのと同じように、スターターがそれを行います。
webServerFactoryBean が、server.*プロパティからサーバーを作ります。webServerStartStopLifecycleBean が、Bean の準備ができた後にサーバーを起動し、シャットダウン時に停止します。- すべてのリクエストは
dispatcherHandlerBean に渡され、それがフィルターとコントローラーを実行します。
デフォルトのサーバーは dart:io の HttpServer です。Dart VM、コンパイルした実行ファイル、そして Android、iOS、macOS、Windows、Linux の Flutter アプリで動きます。HTTP/1.1 を話します (必要なら TLS 付きで)。HTTP/2 は話しません。
例
# lib/resources/application.yml
server:
port: 8080
address: 0.0.0.0
context-path: /shop
max-http-request-body-size: 20MB
mime-mappings:
wasm: application/wasm
spring:
main:
register-shutdown-hook: true # Ctrl+C と SIGTERM でサーバーをグレースフルに停止する
mvc:
log-request-details: false
// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'spring_gen/main.spring.dart';
@SpringBootApplication()
void main(List<String> args) => runApplication(args);
dart run build_runner build
dart run bin/main.dart
# INFO Web server started on port 8080 (http)
この設定では、@GetMapping('/books') は GET http://host:8080/shop/books に応答します。
プロパティ
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
server.port |
int |
8080 |
待ち受けるポート。0 は空いているポートを選ぶ。 |
server.address |
String |
すべてのインターフェース。Flutter アプリでは 127.0.0.1 |
待ち受けるアドレス。IP アドレスまたはホスト名。 |
server.context-path |
String |
なし | すべてのパスの接頭辞。/shop など。 |
server.max-http-request-body-size |
DataSize |
10MB |
最大のリクエストボディ。超えると 413。-1: 上限なし。 |
server.mime-mappings.<ext> |
Map<String, String> |
空 | 静的ファイルのための追加のメディアタイプ (ファイル拡張子ごと)。 |
spring.main.web-application-type |
String |
未設定 | none ならサーバーを起動しない。 |
spring.test.web-environment |
String |
未設定 | テストが設定する。どのテスト環境でサーバーを起動するか。 |
spring.mvc.log-request-details |
bool |
false |
リクエストのログにパラメーターとヘッダーの値を表示する。 |
local.server.port |
int |
サーバーが書き込む | サーバーが実際に待ち受けているポート。読むだけで、設定はしない。 |
その他の server.* キーには専用のページがあります: TLS、圧縮、タイムアウト、過負荷、isolate のプール と そのスケーリング、リバースプロキシ、シャットダウン、WebSocket、セッション。完全な一覧は すべてのプロパティ にあります。
server.port
- 型:
int。デフォルト:8080。 - 動作: サーバーが待ち受ける TCP ポート。
0: システムが空いているポートを選びます。実際のポートは、サーバーが待ち受けを始めて初めて分かります。local.server.port、WebServerInitializedEvent、またはWebServer.portから読んでください。- 変更する理由: 他のプログラムが
8080を使っている。プラットフォームがポートを与える (PORT変数)。一台のマシンで複数のインスタンスを動かす。テストに空いているポートが必要。 - 例:
server.port=9090、またはコマンドラインで--server.port=9090、または環境変数でSERVER_PORT=9090。 - 誤った値:
server.port=abcは、server.portを名指しするバインディングの失敗で起動を止めます。 - 使用中のポート: 起動は失敗します。
ApplicationStartedEventも、ランナーも、ApplicationReadyEventもありません。ApplicationFailedEventが発行され、コンテキストが閉じ、プログラムは 0 以外の終了コードで終わります。レポート:
Web server failed to start. Port 8080 was already in use.
Action: Identify and stop the process that is listening on port 8080, or
configure this application to listen on another port (server.port; 0 picks a free one).
同じプロセスがすでにそのポートで待ち受けている場合も、ポートは使用中です。
コードで計算したポートは、WebServerFactoryCustomizer を通します (後述の「コードでのサーバーの変更」を参照)。
local.server.port
- 型:
int。設定するもの: 待ち受けを始めたサーバー。 - 内容: サーバーが実際に得たポート。
server.port=0の場合、設定からポートを知る唯一の方法です。 - 置き場所:
server.portsという名前のプロパティソースで、環境の先頭に置かれます。 - 読む理由: URL をログに出す、サービスをディスカバリーサーバーに登録する、テストでサーバーを呼ぶ。
@Component()
@Log()
class StartupUrl {
@EventListener()
void onServer(WebServerInitializedEvent event) =>
log.info('Open http://localhost:${event.port}/');
}
local.server.port を自分で設定しても何も起きません。ポートを選ぶためにそれを読むものはありません。
server.address
- 型:
String。デフォルト: 未設定。すべてのインターフェース (IPv4 と IPv6) で待ち受けます。Flutter アプリでのデフォルトは127.0.0.1です。 - 値: IPv4 または IPv6 のアドレス (
0.0.0.0、127.0.0.1、::1)、localhost(127.0.0.1として読む)、またはホスト名。ホスト名はサーバーの起動時に名前解決されます (最初に見つかったアドレスを使います)。 - 変更する理由:
127.0.0.1だけで待ち受けて、このマシンからだけサーバーに到達できるようにする (ローカルツール、同じホスト上のプロキシの背後のサーバー)。または Flutter アプリで、意図してローカルネットワークにサーバーを開くために0.0.0.0を設定する。 - 例:
server.address=127.0.0.1。 - 誤った値: バインドできないアドレスや、名前解決できないホスト名は、
WebServerException: cannot listen on <address>:<port>とソケットのエラーで起動を失敗させます。
server.context-path
- 型:
String。デフォルト: なし。 - 動作: すべてのリクエストパスはこの接頭辞で始まらなければなりません。接頭辞はルーティングの前に取り除かれます。そのため
@GetMapping('/books')は/shop/booksに応答し、/shopだけならパス/です。 - 接頭辞の外:
/books(/shopなし) へのリクエストは、どのハンドラーも受け付けないパスと同じく 404 になります。 - 正規化: 先頭の
/がなければ追加され、末尾の/は取り除かれます。shop/は/shopになります。 - 他への影響: セッション Cookie のデフォルトの
Path(server.session.cookie.path)。そのため Cookie はアプリケーションのパスにだけ送られます。 - 変更する理由: プロキシの背後で複数のアプリケーションが一つのホストを共有し (
/shop、/admin)、プロキシが完全なパスを渡す場合。 - 例:
server.context-path=/shop。 - 注意: ディスパッチャーが直接読みます。ファクトリーの設定で
contextPathを変更するWebServerFactoryCustomizerは、ルーティングを変えません。
server.max-http-request-body-size
- 型:
DataSize(512KB、10MB、1GB。単なる数値はバイト)。デフォルト:10MB。-1: 上限なし。 - 動作: これより大きいリクエストボディは、
Content-Typeに関わらず413 Payload Too Largeで応答されます。Content-Lengthですでに大きすぎると分かる場合は、何も読む前に 413 になります。チャンク形式のボディは読みながら数えます。 - アップロード: マルチパートリゾルバーは、これではなく独自の上限
spring.web.multipart.max-request-sizeでmultipart/form-dataを読みます。アップロード を参照してください。 - 一つのリクエスト: ハンドラーは、ボディを読む前に、リクエスト属性
maxRequestBodySizeAttributeで、自身が扱うリクエストに独自の上限を設定できます。
import 'dart:io' show File;
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
@RestController()
class ImageController {
// 最大 4 GB のディスクイメージを、届くそばからファイルに書く。
@PutMapping('/images/{name}')
@ResponseStatus(HttpStatus.noContent)
Future<void> upload(ServerHttpRequest request, @PathVariable() String name) async {
request.attributes[maxRequestBodySizeAttribute] = 4 << 30;
await request.body.pipe(File('/srv/images/$name').openWrite());
}
}
- 変更する理由: 大きな JSON ドキュメントを受け取る API では引き上げる。小さなサービスを大きなボディから守るには引き下げる。
- Spring Boot にはない: Tomcat には、すべてのボディに対するこの種の上限はありません。これはスターター独自のキーです。
server.mime-mappings.*
- 型: ファイル拡張子からメディアタイプへのマップ。デフォルト: 空 (組み込みのタイプが適用される)。
- 動作: 組み込みの表に加えて、拡張子ごとに静的ファイルの
Content-Typeを与えます。ここに挙げた拡張子は組み込みのタイプより優先されます。拡張子は大文字小文字を区別せずに照合されます (WASMとwasmは同じ)。 - 変更する理由: 組み込みの表が知らないファイルタイプ、または別のタイプで送りたいタイプがある場合。
- 例:
server:
mime-mappings:
wasm: application/wasm
webmanifest: application/manifest+json
server.mime-mappings.wasm=application/wasm
server.mime-mappings.webmanifest=application/manifest+json
タイプが不明なファイルは application/octet-stream として送られます。静的リソース を参照してください。
spring.main.web-application-type
- 型:
String。デフォルト: 未設定。サーバーが起動します。 none: Web の Bean (ディスパッチャー、コントローラー、テストでのMockMvc) は存在しますが、サーバーは起動しません。値は大文字小文字を区別せずに比較されます。- それ以外の値: サーバーが起動します。
servletやreactiveの選択肢はありません。サーバーの種類は一つです。 - 変更する理由: ポートを開かずに、同じアプリケーションのコマンドラインのタスク (マイグレーション、レポート) を実行する。またはサーバーを起動できないブラウザー向けにビルドする。
- 例:
dart run bin/main.dart --spring.main.web-application-type=none。
spring.test.web-environment
- 型:
String。デフォルト: 未設定。サーバーが起動します。 - 値:
mock、random-port、defined-port、none。 - 設定するもの: テストサポート。
springBootTest(springApplication, webEnvironment: ...)が設定し (デフォルトはmock)、ApplicationContextRunnerはmockを設定します。application.ymlでは設定しません。 - 各値の動作:
| 値 | サーバー | ポート |
|---|---|---|
mock |
なし。MockMvc がメモリ内でディスパッチャーを呼ぶ |
— |
random-port |
実際のサーバー | server.port に関わらず 0 (空いているポート) |
defined-port |
実際のサーバー | server.port |
none |
なし | — |
それ以外の値でもサーバーは起動しません。テスト を参照してください。
spring.mvc.log-request-details
- 型:
bool。デフォルト:false。 - 動作: ディスパッチャーは、すべてのリクエストを
debugレベルで、ロガーspring.web.servlet.DispatcherServletにログ出力します。デフォルトでは、クエリパラメーターとヘッダーの値は秘密を含む可能性があるためmaskedと表示されます。trueにすると表示されます。 - 常にマスクされるもの: 認証情報は
trueでもmaskedのままです。ヘッダーAuthorization、Proxy-Authorization、Cookie、Set-Cookie、そして名前にtoken、secret、key、password、sessionを含むヘッダーやパラメーターです。 - ヘッダー:
traceレベルでだけ表示されます。 - 変更する理由: 開発者のマシンでのデバッグ。本番では
falseのままにしてください。
logging.level.spring.web.servlet.DispatcherServlet=trace
spring.mvc.log-request-details=true
DEBUG GET "/api/books", parameters={q=[dune], page=[2]}, headers={host: localhost:8080, authorization: masked}
DEBUG Completed 200 OK
log-request-details がなければ、同じリクエストは parameters={masked} と headers={masked} を記録します。
起動時のログ行
サーバーが待ち受けを始めると、スターターは info レベルで、ロガー spring.web.server にログを出します。
Web server started on port 8080 (http)
ポートは実際のものです (server.port=0 のときに便利です)。server.ssl.certificate が設定され、server.ssl.enabled が false でなければ、スキームは https です。サーバーが停止すると Web server stopped と記録します。
スターターのその他のロガー:
| ロガー | 内容 |
|---|---|
spring.web.server |
起動、停止、グレースフルシャットダウン、サーバーのエラー、切断された WebSocket セッション |
spring.web.servlet.DispatcherServlet |
リクエストとその結果ごとに一行 (debug) |
spring.web.mvc |
起動時に見つかったマッピング (debug: その数、trace: 一つずつ)、書き出したエラー |
spring.web.forwarded |
適用または無視されたフォワードヘッダー (debug) |
spring.web.session |
セッション |
spring.web.multipart |
アップロード |
サーバーのライフサイクル
- コンテキストが起動します。
webServerStartStopLifecycleBean は、Spring Boot と同じくフェーズSmartLifecycle.defaultPhase - 2048のSmartLifecycleです。デフォルトのフェーズのライフサイクル Bean より先に起動し、それらより後に停止します。 - サーバーを動かすべきか?
spring.main.web-application-type=noneのときは動かしません。テストではrandom-portとdefined-portのときだけです。 - サーバーが作られます。
dispatcherHandlerをハンドラーとして、webServerFactoryBean にサーバーを求めます。 - ソケットがバインドされます。
dart:ioは非同期にバインドします。SpringApplicationは、ApplicationStartedEventを発行し、ランナーを実行し、ApplicationReadyEventを発行する前にそれを待ちます。そのため、あなたのApplicationRunnerが実行されるときには、サーバーはすでに待ち受けています。 - ポートが公開されます。
local.server.portが設定され、起動時の行がログに記録され、WebServerInitializedEventが発行されます。 - コンテキストが閉じます。 サーバーは
server.shutdownの指定どおりに停止します。シャットダウン を参照してください。
コードでサーバーを待つには (たとえばテストスターターを使わないテストで):
final lifecycle = context.getBean<WebServerStartStopLifecycle>();
final server = await lifecycle.started; // サーバーが動いていなければ null
final uri = Uri.parse('http://localhost:${server!.port}/api/books');
ポートの使用中以外の起動の失敗 (バインドできないアドレス、読めない証明書) も、起動を失敗させます。SpringApplication を使わずに起動したコンテキストでは、失敗は Web server failed to start としてログに記録され、コンテキストが閉じます。
Ctrl+C での停止
ここでは spring.main.register-shutdown-hook はデフォルトで false です (Spring Boot では true)。シグナルを待ち受けると Dart のプログラムが生き続けてしまうためです。true にすると、Ctrl+C (SIGINT) と SIGTERM でコンテキストが閉じます。その場合、サーバーはグレースフルに停止し、@PreDestroy メソッドが実行されます。設定しなければ、シグナルでプロセスは即座に終了します。
サーバーが自分で応答するもの
一部のリクエストは、あなたのフィルターやコントローラーに届きません。サーバーは ProblemDetail (application/problem+json) でそれらに応答します。
| リクエスト | 応答 |
|---|---|
| スターターが知らないメソッド | 501 Not Implemented |
server.ssl.client-auth=need で、クライアント証明書がない |
403 Forbidden |
Host のない HTTP/1.1、壊れた Host、またはホストが Host ヘッダーと一致しない絶対形式のターゲット |
400 Bad Request |
パス中のエンコードされた /、\、NUL (%2F、%5C、%00) |
400 |
; の後ろに隠れた . または .. セグメント (/files/..;x/secret) |
400 |
パスまたはクエリ中の、有効な UTF-8 でない % エスケープ (/%FF) |
400 |
dart:io サーバーのその他のルール:
Serverヘッダーはなく、X-XSS-Protectionもありません。dart:ioのX-Frame-Options: SAMEORIGINとX-Content-Type-Options: nosniffは送られます。- デフォルトの
Content-Typeはありません。 アプリケーションがメディアタイプを設定しなかった応答には、それがありません。 - 1xx、204、304 には
Content-LengthもTransfer-Encodingも付きません。304 にはContent-Typeも付きません。それらに書いたボディは破棄されます。HEADはGETのヘッダーを保ちます。 - 読まれなかったボディ (413 や 415 で応答したアップロード): 応答が先に送られ、その後ボディのうち最大 2 MB を最大 5 秒かけて読んで破棄します。これにより接続は次のリクエストを処理できます。それより長い、または遅いボディは接続を閉じます。
- レスポンスのコミット後のエラー: レスポンスを完了させずに接続が切断されます (最後のチャンクなし)。クライアントには、完了したように見える短いレスポンスではなく、壊れたレスポンスが見えます。
dart:ioが送れないレスポンスヘッダー (非 ASCII 文字、改行) は、何かが送られる前に失敗します。そのヘッダーは破棄され、エラーは 500 で応答されます。- 接続数の上限はありません (Tomcat の
max-connections)。前段にプロキシを置くか、システムのオープンファイル数の上限に頼ってください。
プロキシの背後で問題になる dart:io の既知の制限:
Hostヘッダーが二つある場合: 最後のものが使われます (Tomcat は 400 で応答します)。- 二桁の 16 進数を伴わない
%は、単なる%として読まれます (/a%G1は/a%25G1)。 - ターゲット中の生の
\は/になり、その後..セグメントが解決されます。/files/..\..\secretは/secretとして届きます。パスを見るルールを持つプロキシは、自分で\を拒否する必要があります。 Content-LengthとTransfer-Encodingの両方を持つリクエストは、サーバーが両方のヘッダーを見た場合、400 で応答され、接続が閉じられます。dart:ioが両方を見せるのは一部の書き方だけです (長さが先にあり、エンコーディングが正確にchunkedと書かれていない場合)。それ以外ではContent-Lengthが捨てられ、リクエストはチャンク形式として読まれます。リクエストスマグリングを防ぐため、そうしたリクエストを拒否するプロキシを使ってください。
コードでのサーバーの変更
ほとんどの用途はプロパティで足ります。値を計算する場合は、WebServerFactoryCustomizer Bean を宣言します。スターターは、server.* を適用した後、デフォルトのファクトリーに対してそれぞれを一回呼びます。
import 'dart:io' show Platform;
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
// ホスティングプラットフォームが PORT 変数でポートを与える。
@Component()
class PortCustomizer implements WebServerFactoryCustomizer {
@override
void customize(ConfigurableWebServerFactory factory) =>
factory.settings = factory.settings.copyWith(
port: int.parse(Platform.environment['PORT'] ?? '8080'),
);
}
ServerProperties.copyWith は引数が null のとき値を保つので、address、ssl、タイムアウトを「なし」に戻すことはできません。server.context-path と server.request-timeout はディスパッチャーがプロパティから読むので、カスタマイザーでは変更できません。
サーバーを完全に置き換えるには、独自の WebServerFactory Bean を宣言します。デフォルトのものは身を引きます (@ConditionalOnMissingBean)。
@Configuration()
class ServerConfig {
@Bean()
WebServerFactory webServerFactory() => MyServerFactory(); // WebServer を返す
}
WebServer は start()、stop({Duration? timeout})、port を持ちます。サーバーより上のものはすべて ServerHttpRequest と ServerHttpResponse で動き、dart:io をインポートしないので、別のサーバーに必要なのはこの二つのクラスだけです。IoWebServerFactory と IoWebServer は package:spring_boot_starter_web/io.dart にあり、デフォルトのサーバーをラップしたり、コンテキストの外でサーバーを起動したりするためにインポートできます。
import 'package:spring_boot_starter_web/io.dart';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
Future<void> main() async {
final server = IoWebServerFactory(const ServerProperties(port: 0)).getWebServer(
FunctionHttpHandler((request, response) => response.send(200, 'pong')),
);
await server.start();
print('listening on ${server.port}');
}
Flutter での実行
スターターは、Android、iOS、macOS、Windows、Linux の Flutter アプリで動きます。サーバーはメインの isolate で、ウィジェットと同じ Bean とともに動きます。ローカル API、他のデバイス向けのコンパニオンサーバー、同じマシンのブラウザーに提供するページなどです。
- デフォルトは
127.0.0.1。server.addressで指定しない限り (server.address=0.0.0.0)、アプリはネットワークにポートを開きません。 - UI をブロックしないでください。
HttpServerの I/O は非同期ですが、ハンドラー内の重い同期処理は UI もブロックします。タスクエグゼキューター で別の isolate に移してください。 - isolate は一つ。 Flutter アプリでは
server.isolates.*は無視され、警告が出ます。isolate のプール を参照してください。 - バックグラウンドでは コンテキストが一時停止します。サーバーは停止してポートを解放します。アプリが戻ると再び起動します。
spring.flutter.lifecycle.pause-in-background=falseで動かし続けられます。 - プラットフォームの権限:
- macOS:
com.apple.security.network.serverエンタイトルメント。 - Android: リリース用マニフェストの
INTERNET権限。 - iOS: localhost 以外へのバインドでは、ユーザーにローカルネットワークへのアクセスを求めます (
Info.plistのNSLocalNetworkUsageDescription)。
- macOS:
- Web にはサーバーソケットがなく、スターターのモジュールは
nativeだけのものです。ブラウザービルドでは、生成されるアプリケーションはそれを列挙しないので、アプリはサーバーなしで起動し、スターターのコードを一切持ちません (一つのプラットフォームだけのモジュール を参照)。ブラウザーでモジュールを手作業で指定するコンテキストは、サーバーを動かしてはなりません (spring.main.web-application-type=none)。そうでなければ、次のメッセージで起動が失敗します。
spring_boot_starter_web has no web server on this platform: the web has no server sockets. Run the server on the VM or in a Flutter app on mobile or desktop, or set spring.main.web-application-type=none.
Spring (Java) との対応
@SpringBootApplication
public class ShopApplication {
public static void main(String[] args) {
SpringApplication.run(ShopApplication.class, args);
}
}
server.port=8080
server.address=127.0.0.1
server.servlet.context-path=/shop
重要な違い:
- サーバーは Tomcat、Jetty、Undertow ではなく、
dart:ioのHttpServerです。HTTP/1.1 だけで、server.http2.enabledは読まれません。 server.servlet.context-pathはserver.context-pathです。古い名前 (server.servlet.以下のすべてのキー) は起動を止め、新しいキーを示します。server.max-http-request-body-sizeはこのスターター独自のキーです。spring.main.web-application-typeが知っているのはnoneだけです。servletやreactiveはありません。spring.main.register-shutdown-hookはデフォルトでfalseです。- Flutter アプリはデフォルトで
127.0.0.1で待ち受けます。 server.tomcat.*、server.jetty.*、server.undertow.*のキーはなく、server.max-http-request-header-sizeもありません。