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。
実行時にリフレクションは使いません。ジェネレーターがエンティティを記述し、リポジトリを書きます。
セットアップ
# 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 もエクスポートします。
例
// 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);
# lib/resources/application.properties
spring.datasource.url=sqlite:file:library.db
-- 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
);
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)は、その旨を示すレポートとともに起動時に失敗します。
内容
モデル:
- エンティティ:
@Table、@Id、@Column、@Transient、@Version、@MappedCollectionによる子。 - JSON の列:
@Json、一つの列に入るクラス、リスト、マップ。そして SQL のストアでの@JsonのないMapやList。 - 参照とキー:
AggregateReference、@Reference、@OnDelete、@Unique、@UniqueConstraint。 - 監査:
@CreatedDate、@LastModifiedBy、@EnableDataAuditing。
リポジトリ:
- リポジトリ:
CrudRepositoryとその仲間、save、新規か既存か。 - 派生クエリ:
findByTitleContaining、countBy、deleteBy、Top、OrderBy。 - ページングとソート:
Pageable、Sort、Page、Slice。 - @Query: 独自の SQL、
@Modifying、エンティティのプレースホルダー、SpEL、そしてビルドがチェックするもの。 - ロック:
@Versionと@Lock。 - データベース関数:
@Procedure、名前で呼び出す関数。 - 行の変更:
RowChange、変更のストリーム、最新に保たれる結果。 - ストアとその機能: ストアにできることと、リポジトリがそのうち使ってよいもの。
トランザクション:
- トランザクション:
@Transactional、伝播、分離レベル、ロールバックのルール、TransactionTemplate。
データベース:
- データソース: URL、プール、複数のデータベース、Bean。
- SQLite: ファイル、メモリ上、専用の Isolate。
- PostgreSQL: URL のパラメーター、TLS、型、エラー。
- スキーマとマイグレーション: マイグレーション、
schema.sql、spring.data.jdbc.schema。 - JdbcTemplate と JdbcClient: 素の SQL。
- セッションフック:
JdbcSessionHook、トランザクションとステートメントごとのロールやテナント。 - SQL のロギング:
show-sql、遅いクエリ、マスクされた値。 - エラー:
DataAccessExceptionの階層。
他のスターターとともに:
- Web アプリケーションで:
Pageableのパラメーター、Pageの JSON、404、409、400 の応答。 - テスト:
@DataTest、ロールバック、@Commit。
リファレンス:
- すべてのプロパティ: スターターのすべてのキー。
- Spring との違い: Spring Data と動作が異なる点。
Spring (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 との違い にあります。