spring_boot_starter_web

spring_boot_starter_web は Spring for Dart の HTTP サーバーで、Spring Boot の spring-boot-starter-web と Spring MVC を Dart に移植したものです。@GetMapping('/books/{isbn}') のようなアノテーションを付けたメソッドを持つコントローラークラスを書きます。スターターは各リクエストを適切なメソッドに送り、パス、クエリ、ヘッダー、ボディからその引数を埋め、戻り値をレスポンスに変換します。

使う理由

REST API では、どのエンドポイントの周りでも同じ作業が必要です。パスを解析し、クエリを読み、JSON をデコードして検証し、エラーを一つの形で返し、JSON を書き戻します。dart:io の HttpServer の上で手書きすると、このコードはエンドポイントごとに増えていきます。スターターがこれを代わりに行います。

Dart のバックエンドや、モバイル・デスクトップの Flutter アプリ内のローカルサーバー (ローカル API、コンパニオンサーバー) に使います。サーバーは dart:io の HttpServer で、差し替え可能なファクトリーの背後にあります。ルーティングのコードはすべてジェネレーターがビルド時に書き出すため、実行時のリフレクションはありません。

セットアップ

# pubspec.yaml
dependencies:
  spring_boot_starter_web: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # 必須: コントローラーを記述する
  spring_boot_starter_test: ^0.9.0     # テスト用の MockMvc と springBootTest
  test: ^1.33.0

インポートは一つで足ります。package:spring_boot_starter_web/spring_boot_starter_web.dart は spring_boot_dart、spring_web_dart (アノテーション、ResponseEntity、ProblemDetail、サーバーのリクエストとレスポンス)、spring_boot_starter_logging もエクスポートします。他の Spring Boot スターターと同じく、アプリケーションに必要な依存関係はこれだけです。

例

1 ファイルで完結するアプリケーション:

// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

import 'spring_gen/main.spring.dart';

class Book {
  const Book({required this.isbn, required this.title});

  final String isbn;
  final String title;
}

class NewBook {
  const NewBook({required this.isbn, required this.title});

  @NotBlank()
  @Size(min: 4, max: 13)
  final String isbn;

  @NotBlank()
  final String title;
}

@Service()
class BookService {
  final _books = <String, Book>{
    '978-0': const Book(isbn: '978-0', title: 'Dune'),
  };

  Book? find(String isbn) => _books[isbn];

  Book add(NewBook book) =>
      _books[book.isbn] = Book(isbn: book.isbn, title: book.title);
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);

  final BookService books;

  // GET /api/books/978-0 → 200 {"isbn":"978-0","title":"Dune"}
  @GetMapping('/{isbn}')
  Book find(@PathVariable() String isbn) =>
      books.find(isbn) ??
      (throw ResponseStatusException(HttpStatus.notFound, 'No book $isbn'));

  // POST /api/books → Location ヘッダー付きの 201。不正なボディは 400。
  @PostMapping()
  ResponseEntity<Book> create(@RequestBody() @Valid() NewBook book) {
    final added = books.add(book);
    return ResponseEntity.created(Uri.parse('/api/books/${added.isbn}'))
        .body(added);
  }
}

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
# lib/resources/application.properties
server.port=8080
spring.main.register-shutdown-hook=true

Book と NewBook には JSON のためのアノテーションは不要です。コントローラーが受け取り、返すクラスが同じパッケージにあれば、ジェネレーターはそれぞれをコントローラーでの使われ方に応じて記述します。返されるだけのクラスにはゲッターを、@RequestBody のクラスにはコンストラクターとセッターを (@Valid() 付きなら制約を持つプロパティのゲッターも) 記述します。JSON として書き出す Object など、ビルドから見えない値には、そのクラスに @Introspected() が必要です (JSON を参照)。

実行する

dart run build_runner build   # bin/spring_gen/main.spring.dart を書き出す
dart run bin/main.dart

アノテーションを追加・変更したら build_runner を再実行します。コンテキストの準備ができるとサーバーが起動し、ロガー spring.web.server で次のログを出力します。

INFO  Web server started on port 8080 (http)

続いて:

curl localhost:8080/api/books/978-0
# {"isbn":"978-0","title":"Dune"}

curl -i localhost:8080/api/books/123
# HTTP/1.1 404 Not Found
# content-type: application/problem+json
# {"type":"about:blank","title":"Not Found","status":404,"detail":"No book 123","instance":"/api/books/123"}

起動するもの:

内容

はじめに:

コントローラー:

エラー:

ストリームとファイル:

Web の機能:

サーバー:

リファレンス:

Spring (Java) との対応

@RestController
@RequestMapping("/api/books")
class BookController {
  @GetMapping("/{isbn}")
  Book find(@PathVariable String isbn) { ... }

  @PostMapping
  ResponseEntity<Book> create(@RequestBody @Valid NewBook book) { ... }
}

@SpringBootApplication
class ShopApplication {
  public static void main(String[] args) {
    SpringApplication.run(ShopApplication.class, args);
  }
}

重要な違い:

関連項目