
# spring_boot_starter_data

`spring_boot_starter_data` は Spring for Dart のデータ層で、Spring Boot の `spring-boot-starter-data-jdbc` を Dart に移植したものです。`@Table` で集約を記述し、リポジトリのインターフェースを宣言すれば、ジェネレーターが派生クエリを含むその実装を書きます。同じリポジトリが、プロパティで選んだメモリ上、SQLite、PostgreSQL のいずれでも動きます。

モデルは JPA ではなく Spring Data JDBC のものです。集約は丸ごと読み込まれて保存され、`save` はすぐに書き込み、他の集約は ID で参照します。永続化コンテキストも、遅延読み込みも、エンティティのプロキシもありません。

## 使う理由

ほとんどのアプリケーションは、同じ種類のデータを同じ方法で保存します。集約ごとのテーブル、いくつかのファインダー、ページング、業務処理を囲むトランザクション、起動時のマイグレーションです。手で書くと、同じ SQL とマッピングのコードを何度も書くことになります。スターターは次のものを提供します。

- ビルドが実装を書くリポジトリ。`findByTitleContainingIgnoreCase` のようなメソッドは、ビルド時にエンティティと照合されます。
- SQL、パラメーター、SpEL 式がビルド時にチェックされ、「もしかして」の候補が出る `@Query` メソッド。
- Spring の 7 つの伝播、分離レベル、タイムアウト、読み取り専用、ロールバックのルールを持ち、PostgreSQL 上で Spring 自身とシナリオごとに照合した `@Transactional`。
- 楽観的ロック (`@Version`) と悲観的ロック (`@Lock`)。
- 外部キーによる参照、`@OnDelete`、一意キー、監査。
- マイグレーション (Flyway のファイル命名)、`schema.sql` / `data.sql`、そしてエンティティに対するスキーマのチェック。
- 素の SQL のための `JdbcTemplate`、`NamedParameterJdbcTemplate`、`JdbcClient`。
- テストやプロトタイプのための、外部キーを有効にした SQLite のように動作するメモリ上のストア。
- メモリ上の SQLite データベースを使い、各テストの後にロールバックするテストスライス `@DataTest`。

実行時にリフレクションは使いません。ジェネレーターがエンティティを記述し、リポジトリを書きます。

## セットアップ

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_data: ^0.9.0
  sqlite3: ^3.8.0        # sqlite: の URL のため。PostgreSQL には postgres: ^3.5.0 を挙げる

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # リポジトリを書く
  spring_boot_starter_test: ^0.9.0     # @DataTest
  test: ^1.33.0
```

スターターはドライバーを内蔵していません。欲しいもの (`sqlite3`、`postgres`、または両方) を挙げれば、ジェネレーターが見つけたドライバーのパッケージごとに `JdbcDriver` の Bean を書きます。URL のスキームがその中から選びます。URL がなければ、リポジトリはデータをメモリに保持します。

インポートは一つで足ります。`package:spring_boot_starter_data/spring_boot_starter_data.dart` は `spring_boot_starter_logging` もエクスポートし、それを通して `spring_boot_dart` と `spring_core_dart` もエクスポートします。

## 例

```dart
// bin/main.dart
import 'package:spring_boot_starter_data/spring_boot_starter_data.dart';

import 'spring_gen/main.spring.dart';

@Table('books')
class Book {
  Book({this.id, required this.title, this.year});

  @Id()
  int? id;          // null: 新規。データベースが ID を与える
  String title;
  int? year;

  @Version()
  int version = 0;  // 楽観的ロック。0 は「まだ保存されていない」を意味する
}

// アノテーションは不要: リポジトリのインターフェースを継承するだけでよい。
abstract interface class BookRepository
    implements
        ListCrudRepository<Book, int>,
        ListPagingAndSortingRepository<Book, int> {
  Future<List<Book>> findByTitleContainingIgnoreCase(String text);
  Future<Page<Book>> findByYearGreaterThan(int year, Pageable page);
  Future<int> countByYearBetween(int from, int to);
}

@Service()
class Catalog {
  Catalog(this.books);

  final BookRepository books;

  // 一つのトランザクション: 両方の保存がまとめてコミットされるか、どちらもされない。
  @Transactional()
  Future<void> addSeries(List<String> titles) async {
    for (final title in titles) {
      await books.save(Book(title: title));
    }
  }
}

@SpringBootApplication()
// SQL データベースは接続の上で準備される: 非同期に起動する。
Future<void> main(List<String> args) => runApplicationAsync(args);
```

```properties
# lib/resources/application.properties
spring.datasource.url=sqlite:file:library.db
```

```sql
-- lib/resources/db/migration/V1__books.sql
create table books (
  id integer primary key autoincrement,
  title text not null,
  year integer,
  version integer not null
);
```

```bash
dart run build_runner build   # リポジトリと結び付けを書く
dart run bin/main.dart
```

起動時にマイグレーションが実行され、スターターは `books` テーブルが `Book` エンティティに合っているかを確認し、その後でようやくリポジトリや `JdbcTemplate` がデータベースを使えるようになります。

## 実行する

スターターとともに起動するもの:

- **`@EnableJdbcRepositories` はありません。** スキャンされたコードの、リポジトリのインターフェースを継承するすべてのインターフェースが Bean になります。
- **ビルドがリポジトリをチェックします。** エンティティが対応していないメソッド名 (`findByTitel`) はビルドエラーになります: `No property 'titel' found for type 'Book'; did you mean 'title'?`。
- **ストアは自動で選ばれます。** リポジトリは、`spring.datasource.url` が設定されていれば `jdbc` ストアを、そうでなければ `memory` ストアを使います。`@UseStore('memory')` と `@UseDataSource('stats')` はリポジトリごとに選びます。
- **スキーマはどの使用より前に準備されます。** マイグレーションとスクリプトが実行され、次にエンティティがスキーマと照合されます (デフォルトは `spring.data.jdbc.schema=validate`)。失敗すると、そのメッセージとともに起動が止まります。
- **SQL データベースでは `runApplicationAsync` が必要です。** 同期的な `runApplication(args)` は、その旨を示すレポートとともに起動時に失敗します。

## 内容

モデル:

- [エンティティ](entities.md): `@Table`、`@Id`、`@Column`、`@Transient`、`@Version`、`@MappedCollection` による子。
- [JSON の列](json-columns.md): `@Json`、一つの列に入るクラス、リスト、マップ。そして SQL のストアでの `@Json` のない `Map` や `List`。
- [参照とキー](references.md): `AggregateReference`、`@Reference`、`@OnDelete`、`@Unique`、`@UniqueConstraint`。
- [監査](auditing.md): `@CreatedDate`、`@LastModifiedBy`、`@EnableDataAuditing`。

リポジトリ:

- [リポジトリ](repositories.md): `CrudRepository` とその仲間、`save`、新規か既存か。
- [派生クエリ](derived-queries.md): `findByTitleContaining`、`countBy`、`deleteBy`、`Top`、`OrderBy`。
- [ページングとソート](paging-and-sorting.md): `Pageable`、`Sort`、`Page`、`Slice`。
- [@Query](query.md): 独自の SQL、`@Modifying`、エンティティのプレースホルダー、SpEL、そしてビルドがチェックするもの。
- [ロック](locks.md): `@Version` と `@Lock`。
- [データベース関数](database-functions.md): `@Procedure`、名前で呼び出す関数。
- [行の変更](changes.md): `RowChange`、変更のストリーム、最新に保たれる結果。
- [ストアとその機能](stores.md): ストアにできることと、リポジトリがそのうち使ってよいもの。

トランザクション:

- [トランザクション](transactions.md): `@Transactional`、伝播、分離レベル、ロールバックのルール、`TransactionTemplate`。

データベース:

- [データソース](data-sources.md): URL、プール、複数のデータベース、Bean。
- [SQLite](sqlite.md): ファイル、メモリ上、専用の Isolate。
- [PostgreSQL](postgresql.md): URL のパラメーター、TLS、型、エラー。
- [スキーマとマイグレーション](schema.md): マイグレーション、`schema.sql`、`spring.data.jdbc.schema`。
- [JdbcTemplate と JdbcClient](jdbc.md): 素の SQL。
- [セッションフック](session-hooks.md): `JdbcSessionHook`、トランザクションとステートメントごとのロールやテナント。
- [SQL のロギング](logging.md): `show-sql`、遅いクエリ、マスクされた値。
- [エラー](errors.md): `DataAccessException` の階層。

他のスターターとともに:

- [Web アプリケーションで](web.md): `Pageable` のパラメーター、`Page` の JSON、404、409、400 の応答。
- [テスト](testing.md): `@DataTest`、ロールバック、`@Commit`。

リファレンス:

- [すべてのプロパティ](properties.md): スターターのすべてのキー。
- [Spring との違い](differences.md): Spring Data と動作が異なる点。

## Spring (Java) との対応

```java
@Table("books")
class Book {
  @Id Long id;
  String title;
  Integer year;
  @Version long version;
}

interface BookRepository
    extends ListCrudRepository<Book, Long>, ListPagingAndSortingRepository<Book, Long> {
  List<Book> findByTitleContainingIgnoreCase(String text);
  Page<Book> findByYearGreaterThan(int year, Pageable page);
}
```

重要な違い:

- リポジトリのメソッドはすべて非同期です (`Future` または `Stream`)。
- Dart にはオーバーロードがありません: `findAll()`、`findAllSorted(Sort)`、`findAllPaged(Pageable)`。
- リポジトリはビルドが書き、その派生クエリと `@Query` のテキストは起動時ではなくビルド時にチェックされます。
- すべての違いは [Spring との違い](differences.md) にあります。

## 関連項目

- [spring_core_dart](../spring-core-dart/index.md)
- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [ジェネレーターとデータ](../spring-core-dart-generator/data.md)
- [spring_boot_starter_supabase](../spring-boot-starter-supabase/index.md)
- [ビルドに含まれるもの](optimizations.md)
