Spring for Dart
Spring for Dart は、Java のフレームワークである Spring Framework と Spring Boot のプログラミングモデルを、Dart と Flutter にもたらします。普通のクラスを書き、@Service() や @GetMapping('/books') のようなアノテーションを付けます。フレームワークがオブジェクトを生成し、結び付け、application.properties や application.yml から設定し、アプリケーションを実行します。
Dart には、Flutter、Web、AOT 実行ファイルで実行時のリフレクションがありません。そのため、アノテーションはビルド時に読まれます。build_runner のビルダーである spring_core_dart_generator が、オブジェクトを生成し、リクエストをルーティングし、アスペクトを適用する素の Dart コードを書き出します。同じアプリケーションが、dart run で、コンパイルされた実行ファイルとして、Flutter アプリの中で、そしてブラウザーで動きます。
得意なこと
- 結び付け。 クラスは必要なものをコンストラクターで求めます。コンテナはグラフ全体を正しい順序で組み立て、足りない依存や曖昧な依存があると、クラスとパラメーターを示すメッセージで起動を止めます。制御の反転と依存性注入 を参照してください。
- 設定。 設定値はファイル、環境変数、コマンドラインから来て、その上にプロファイル (
dev、prod、test) が重なります。設定のグループは型付きのクラスにバインドされ、起動時にチェックされます。 - 既製の機能。 スターターを
pubspec.yamlに追加すると、Web サーバー、HTTP クライアント、キャッシュ、スケジュールされたタスク、セキュリティ、ロギング、データベースアクセスが加わります。適切なデフォルトがあり、Bean を一つずつ置き換えられます。スターター を参照してください。 - すべてのための一つのコンテキスト。 自分のコードとすべてのスターターの Bean が一つのアプリケーションコンテキストに入るので、スターターはつなぎのコードなしに協調して動きます。すべてのスターターのための一つのコンテキスト を参照してください。
- テスト。 テストでは任意の Bean をフェイクに置き換えられ、テストはその周りで本物のアプリケーションを起動します。
- 早期のチェック。 多くの間違いは、アプリケーションが実行される前にジェネレーターが見つけます。不正なポイントカット、チェックできない型に付けたバリデーションの制約、
pubspec.yamlにない Flutter のアセットです。その他は、最初のリクエストより前の起動時に見つかります。プロパティが設定されておらずデフォルトもないプレースホルダー、一つのルートに対する二つのハンドラー、足りない Bean、Bean の循環です。
誰のためのものか
- サーバー。 REST API、WebSocket サーバー、Flutter アプリのバックエンド。
spring_boot_starter_webを使います。 - Flutter アプリ。 Bean に置いてウィジェットに渡す状態とサービス、設定ファイルに置くテーマ、テキスト、アプリの設定、プラットフォームのプロファイル (
android、ios、webなど)。spring_boot_starter_flutterを使います。 - コマンドラインツール。 CLI のための設定、ロギング、起動時のタスク。
spring_boot_starter_loggingを使います。
Java や Spring を知っている必要はありません。これらのページは、すべての考え方を最初から説明します。Spring を知っていれば、ほとんどのアノテーションとプロパティ名は知っているものと同じです。各パッケージのページが違いを列挙しています。
5 分ではじめる
一つのサービスと一つのエンドポイントを持つ Web サーバーです。
1. パッケージを作り、pubspec.yaml で依存関係を設定します。Web スターターは、必要な他のすべて (コア、Spring Boot、ロギング) を持ち込みます。ジェネレーターと build_runner はビルド時にだけ使われます。
# pubspec.yaml
name: hello
environment:
sdk: ^3.13.0
dependencies:
spring_boot_starter_web: ^0.9.0
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0
2. アプリケーションを書きます。bin/main.dart です。lib/ と main のディレクトリにあるものはすべてスキャンされるので、最新に保つべきクラスのリストはありません。
// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'spring_gen/main.spring.dart'; // build_runner が書き出す
// Bean: コンテナは Greeter を一つ生成し、必要な場所に渡す。
// 名前は設定から来る。設定されていなければ "World"。
@Service()
class Greeter {
Greeter(@Value(r'${greeting.name:World}') this.name);
final String name;
String greet() => 'Hello, $name!';
}
// GET /hello は挨拶で応答する。
@RestController()
class HelloController {
HelloController(this.greeter); // 型で注入される
final Greeter greeter;
@GetMapping('/hello')
String hello() => greeter.greet();
}
@SpringBootApplication()
void main(List<String> args) => runApplication(args);
r'${greeting.name:World}' は raw 文字列です。${...} は Dart の文字列補間ではなく、Spring のプレースホルダーです。
3. 設定値を追加します。lib/resources/application.properties です。
greeting.name=Dart
4. コードを生成して実行します。
dart pub get
dart run build_runner build # bin/spring_gen/main.spring.dart を書き出す
dart run bin/main.dart
curl localhost:8080/hello
# Hello, Dart!
設定値はファイルに触れずに上書きできます。dart run bin/main.dart --greeting.name=Ada、または GREETING_NAME=Ada dart run bin/main.dart です。
アノテーションを追加したり変更したりしたら build_runner を再び実行するか、dart run build_runner watch を動かしておきます。
これらのページ
| ページ | 説明する内容 |
|---|---|
| 制御の反転と依存性注入 | 中心となる考え方: コンテナがオブジェクトを生成して結び付ける。Bean、注入、設定、ライフサイクル、スコープ、テスト。 |
| 比較 | 小さな比較の例: get_it と依存性注入、Observer パターン、メソッドの周りのロジック、HTTP クライアント。 |
| スターター | すべてのパッケージと、それを追加すると得られるものの紹介。 |
| すべてのスターターのための一つのコンテキスト | スターターがどのように見つけられ、互いの Bean をどう使い、自分の Bean がどうそれを置き換えるか。 |
| 独自のスターター | それに依存するすべてのアプリケーションに Bean を追加するパッケージを書く。 |
パッケージ
| パッケージ | 内容 | ドキュメント |
|---|---|---|
spring_core_dart |
コンテナ: Bean、設定、プロファイル、イベント、バリデーション、JSON、AOP | spring_core_dart |
spring_core_dart_generator |
アノテーションを読んでコードを書き出す build_runner のビルダー |
spring_core_dart_generator |
spring_boot_dart |
@SpringBootApplication からアプリケーションを起動し、設定を読み、スターターを追加する |
spring_boot_dart |
spring_boot_starter_web |
@RestController クラスを持つ HTTP サーバー |
spring_boot_starter_web |
| その他のパッケージ | WebSocket、データ、キャッシュ、スケジューリング、Feign、セキュリティ、OAuth 2.0 クライアント、アクチュエーター、ロギング、テスト、Flutter、ナビゲーション、Flutter のセキュリティ、検索、そしてそれらの基盤となるライブラリ | スターター |
アプリケーションは使うスターターを列挙し、それらが持ち込むものは列挙しません。Web サーバーは spring_boot_starter_web だけを列挙し、それを通して spring_core_dart と spring_boot_dart を得ます。
Spring (Java) との対応
考え方は Spring と同じです。Bean、アプリケーションコンテキスト、自動構成、スターター、プロファイル、@ConfigurationProperties です。違いは Dart から来ます。
- スキャンはビルド時に行われます。アノテーションを変更したら、
build_runnerを再び実行してください。 @SpringBootApplication()はクラスではなくmain関数に付けます。lib/resources/は Java のリソースフォルダーの役割を果たします。そこにあるapplication.propertiesなどのファイルはビルドに埋め込まれます。- アノテーションはコンストラクター呼び出しなので、括弧が付きます:
@Serviceではなく@Service()。