組み込みサーバー

spring_boot_starter_web は、アプリケーションの中で HTTP サーバーを動かします。サーバーはコンテキストの準備ができると起動し、コンテキストが閉じると停止します。設定は server.* プロパティで行います。

使う理由

HttpServer.bind やリクエストのループを書く必要はありません。Spring Boot が Tomcat を動かしてくれるのと同じように、スターターがそれを行います。

デフォルトのサーバーは 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

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

@Component()
@Log()
class StartupUrl {
  @EventListener()
  void onServer(WebServerInitializedEvent event) =>
      log.info('Open http://localhost:${event.port}/');
}

local.server.port を自分で設定しても何も起きません。ポートを選ぶためにそれを読むものはありません。

server.address

server.context-path

server.max-http-request-body-size

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());
  }
}

server.mime-mappings.*

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

spring.test.web-environment

値 サーバー ポート
mock なし。MockMvc がメモリ内でディスパッチャーを呼ぶ —
random-port 実際のサーバー server.port に関わらず 0 (空いているポート)
defined-port 実際のサーバー server.port
none なし —

それ以外の値でもサーバーは起動しません。テスト を参照してください。

spring.mvc.log-request-details

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 アップロード

サーバーのライフサイクル

  1. コンテキストが起動します。 webServerStartStopLifecycle Bean は、Spring Boot と同じくフェーズ SmartLifecycle.defaultPhase - 2048 の SmartLifecycle です。デフォルトのフェーズのライフサイクル Bean より先に起動し、それらより後に停止します。
  2. サーバーを動かすべきか? spring.main.web-application-type=none のときは動かしません。テストでは random-port と defined-port のときだけです。
  3. サーバーが作られます。 dispatcherHandler をハンドラーとして、webServerFactory Bean にサーバーを求めます。
  4. ソケットがバインドされます。 dart:io は非同期にバインドします。SpringApplication は、ApplicationStartedEvent を発行し、ランナーを実行し、ApplicationReadyEvent を発行する前にそれを待ちます。そのため、あなたの ApplicationRunner が実行されるときには、サーバーはすでに待ち受けています。
  5. ポートが公開されます。 local.server.port が設定され、起動時の行がログに記録され、WebServerInitializedEvent が発行されます。
  6. コンテキストが閉じます。 サーバーは 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 サーバーのその他のルール:

プロキシの背後で問題になる dart:io の既知の制限:

コードでのサーバーの変更

ほとんどの用途はプロパティで足ります。値を計算する場合は、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、他のデバイス向けのコンパニオンサーバー、同じマシンのブラウザーに提供するページなどです。

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

重要な違い:

関連項目