
# 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 アプリの中で、そしてブラウザーで動きます。

## 得意なこと

- **結び付け。** クラスは必要なものをコンストラクターで求めます。コンテナはグラフ全体を正しい順序で組み立て、足りない依存や曖昧な依存があると、クラスとパラメーターを示すメッセージで起動を止めます。[制御の反転と依存性注入](inversion-of-control.md) を参照してください。
- **設定。** 設定値はファイル、環境変数、コマンドラインから来て、その上にプロファイル (`dev`、`prod`、`test`) が重なります。設定のグループは型付きのクラスにバインドされ、起動時にチェックされます。
- **既製の機能。** スターターを `pubspec.yaml` に追加すると、Web サーバー、HTTP クライアント、キャッシュ、スケジュールされたタスク、セキュリティ、ロギング、データベースアクセスが加わります。適切なデフォルトがあり、Bean を一つずつ置き換えられます。[スターター](starters.md) を参照してください。
- **すべてのための一つのコンテキスト。** 自分のコードとすべてのスターターの Bean が一つのアプリケーションコンテキストに入るので、スターターはつなぎのコードなしに協調して動きます。[すべてのスターターのための一つのコンテキスト](shared-context.md) を参照してください。
- **テスト。** テストでは任意の 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` はビルド時にだけ使われます。

```yaml
# 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` のディレクトリにあるものはすべてスキャンされるので、最新に保つべきクラスのリストはありません。

```dart
// 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` です。

```properties
greeting.name=Dart
```

**4. コードを生成して実行します。**

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

```bash
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` を動かしておきます。

## これらのページ

| ページ | 説明する内容 |
|---|---|
| [制御の反転と依存性注入](inversion-of-control.md) | 中心となる考え方: コンテナがオブジェクトを生成して結び付ける。Bean、注入、設定、ライフサイクル、スコープ、テスト。 |
| [比較](../compare/index.md) | 小さな比較の例: get_it と依存性注入、Observer パターン、メソッドの周りのロジック、HTTP クライアント。 |
| [スターター](starters.md) | すべてのパッケージと、それを追加すると得られるものの紹介。 |
| [すべてのスターターのための一つのコンテキスト](shared-context.md) | スターターがどのように見つけられ、互いの Bean をどう使い、自分の Bean がどうそれを置き換えるか。 |
| [独自のスターター](your-own-starter.md) | それに依存するすべてのアプリケーションに Bean を追加するパッケージを書く。 |

## パッケージ

| パッケージ | 内容 | ドキュメント |
|---|---|---|
| `spring_core_dart` | コンテナ: Bean、設定、プロファイル、イベント、バリデーション、JSON、AOP | [spring_core_dart](../components/spring-core-dart/index.md) |
| `spring_core_dart_generator` | アノテーションを読んでコードを書き出す `build_runner` のビルダー | [spring_core_dart_generator](../components/spring-core-dart-generator/index.md) |
| `spring_boot_dart` | `@SpringBootApplication` からアプリケーションを起動し、設定を読み、スターターを追加する | [spring_boot_dart](../components/spring-boot-dart/index.md) |
| `spring_boot_starter_web` | `@RestController` クラスを持つ HTTP サーバー | [spring_boot_starter_web](../components/spring-boot-starter-web/index.md) |
| その他のパッケージ | WebSocket、データ、キャッシュ、スケジューリング、Feign、セキュリティ、OAuth 2.0 クライアント、アクチュエーター、ロギング、テスト、Flutter、ナビゲーション、Flutter のセキュリティ、検索、そしてそれらの基盤となるライブラリ | [スターター](starters.md) |

アプリケーションは使うスターターを列挙し、それらが持ち込むものは列挙しません。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()`。
