エンティティ
エンティティは @Table を付けた Dart のクラスで、一つのテーブルに保存される集約のルートです。各プロパティが列になります。ジェネレーターはビルド時にクラスを記述するため、リポジトリはリフレクションなしにそのプロパティを読み、コンストラクターを呼びます。
使う理由
Spring Data JDBC のモデルでは、集約は一つの単位です。子とともに、丸ごと読み込まれ、丸ごと保存され、丸ごと削除されます。他の集約は ID で参照され、一緒に読み込まれることはありません。これによりマッピングは予測しやすくなります。遅延読み込みも、変更を追跡するセッションも、オブジェクトを包むプロキシもありません。手にしているのは普通の Dart のオブジェクトで、save はそれをすぐに書き込みます。
例
import 'package:spring_boot_starter_data/spring_boot_starter_data.dart';
enum Format { hardcover, paperback, ebook }
@Table('books') // 値がなければ: スネークケースにしたクラス名
class Book {
Book({this.id, required this.title, this.format = Format.paperback});
@Id()
int? id; // null: 新規。データベースが ID を与える
String title; // 列 "title"
@Column('pub_year')
int? year; // "year" の代わりに列 "pub_year"
Format format; // 列挙型の名前として TEXT で保存される
@Transient()
bool selected = false; // 書かれることも読まれることもない
@Version()
int version = 0; // 保存のたびに上がる。0 はまだ保存されていないことを意味する
}
アノテーション
| アノテーション | 付ける場所 | 働き |
|---|---|---|
@Table([name, schema]) |
クラス | クラスはテーブル name に保存される集約のルート (または子)。デフォルトはスネークケースにしたクラス名 (OrderLine → order_line)。schema はテーブルのスキーマで、デフォルトは接続のもの。 |
@Id() |
プロパティ | 集約の ID。null の ID は新規を意味する: save は挿入し、ストアは返すエンティティに生成された ID を設定する。 |
@Column(name) |
プロパティ | 列の名前。プロパティ名をスネークケースにしたもの (createdAt → created_at) でない場合に。 |
@Transient() |
プロパティ | 保存されない: 書かれも読まれもせず、コンストラクターが与えた値を保つ。 |
@Version() |
プロパティ | 楽観的ロック: 保存のたびに上がる int または DateTime (ロック を参照)。 |
@MappedCollection(idColumn:, keyColumn:) |
プロパティ | ルートとともに保存、読み込み、削除される子エンティティの List、Set、Map。 |
@CreatedDate()、@LastModifiedDate()、@CreatedBy()、@LastModifiedBy() |
プロパティ | 保存時に設定される監査の値 (監査 を参照)。 |
@Reference(Type)、@OnDelete(action) |
プロパティ | ID による別の集約への参照 (参照とキー を参照)。 |
@Unique()、@UniqueConstraint([...], name:) |
プロパティ、クラス | 一意な値 (参照とキー を参照)。 |
名前
デフォルトの命名戦略は、すべての名前をスネークケースで書きます。
| Dart | データベース |
|---|---|
クラス OrderLine |
テーブル order_line |
プロパティ createdAt |
列 created_at |
クラス HTTPRequest |
テーブル http_request (略語は一つの単語) |
プロパティ line2Item |
列 line2_item (数字は前の単語とともに残る) |
アノテーションの値は、書かれたとおりに常に優先されます。アプリケーション全体のルールを変えるには、NamingStrategy を継承してメソッド (tableName、columnName、マッピングされたコレクションの 2 つ) をオーバーライドし、Bean として宣言します。独自の NamingStrategy の Bean は、派生した名前を @Query のテキストのビルド時のチェックから隠します (@Query を参照)。
型
| Dart の型 | SQLite | PostgreSQL |
|---|---|---|
int |
INTEGER |
BIGINT |
bool |
INTEGER (0 または 1) |
BOOLEAN |
double、num |
REAL |
DOUBLE PRECISION |
String |
TEXT |
TEXT |
| 列挙型 | TEXT (その名前) |
TEXT (その名前) |
DateTime |
UTC の ISO 8601 の TEXT |
TIMESTAMPTZ (UTC で読み戻される) |
Uint8List、List<int> |
BLOB |
BYTEA |
BigInt |
TEXT |
NUMERIC |
AggregateReference<T, ID> |
ID の型 | ID の型 |
@Json を付けたクラス、Map、List、Set |
TEXT の JSON |
JSONB または JSON |
nullable な Dart の型は nullable な列になります。非 nullable なものは、スターターが作るスキーマでは NOT NULL になり、spring.data.jdbc.schema=validate でチェックされます。
Map、List、Set は、それだけでは列になりません。@Json を付けるか、子テーブルの行にするなら @MappedCollection を付けます。どちらもなければ、SQL のストアは、ビルド時またはアプリケーションの起動時に、直し方とともにそのプロパティを拒否します (JSON の列 を参照)。
イミュータブルなエンティティ
フィールドは final でもかまいません。その場合リポジトリは、値を変える必要がある箇所 (生成された ID、新しいバージョン、監査の値) で、コンストラクターを通してコピーを作ります。そのため、常に save が返すエンティティを使ってください。
@Table('accounts')
class Account {
const Account({required this.iban, required this.owner, this.version = 0});
@Id()
final String iban; // 自分で与える ID には...
final String owner;
@Version()
final int version; // ...バージョンが必要: 0 は save に挿入を指示する
}
final saved = await accounts.save(const Account(iban: 'DE89', owner: 'Ada'));
print(saved.version); // 1
アプリケーションが自分で与える ID (UUID、自然キー) には @Version が必要です。それがないと、null でない ID は「既存」を意味し、save は更新を試みて、一致する行がなければ IncorrectUpdateSemanticsDataAccessException を投げます。
子: @MappedCollection
@Table('orders')
class PurchaseOrder {
PurchaseOrder({required this.customer, this.id, this.lines = const [], this.notes = const {}});
@Id()
int? id;
String customer;
@MappedCollection()
List<OrderLine> lines; // テーブル order_lines: orders_id、orders_key (位置)
@MappedCollection(idColumn: 'order_id', keyColumn: 'topic')
Map<String, OrderNote> notes; // テーブル order_notes: order_id、topic (キー)
}
@Table('order_lines') // 子はテーブル名のために @Table を取る
class OrderLine {
OrderLine({required this.sku, required this.quantity});
String sku;
int quantity;
}
@Table('order_notes')
class OrderNote {
OrderNote({required this.text});
String text;
}
- 子のテーブルは、ルートの ID を参照する
idColumnを持ちます。デフォルトは、ルートのテーブル名に_idを続けたものです。 ListやMapには、位置またはキーであるkeyColumnも必要です。デフォルトは、ルートのテーブル名に_keyを続けたものです。Setにはありません。- 保存は子を書き直します。Spring Data JDBC と同じく、古い行が削除され、現在の行が挿入されます。
- 子はルートの
@Versionでカバーされます。 - 子は単独で保存も読み込みもできず、リポジトリを持ちません。
@MappedCollection なしで型が別のエンティティであるプロパティ (Author author;) は、ヒント付きのマッピングエラーになります。Spring Data JDBC ではそれは子になりますが、スターターは子と参照のどちらを意図したのかを決して推測しません。
新規か既存か
save は新規のエンティティを挿入し、既存のものを更新します。ルールは Spring Data のものです。
| エンティティが持つもの | 新規となる条件 |
|---|---|
int (非 nullable) 型の @Version |
バージョンが 0 |
int? 型の @Version |
バージョンが null (バージョン 0 で保存された行は再び挿入されず、更新される) |
DateTime? 型の @Version |
バージョンが null |
@Version がなく、@Id がある |
ID が null |
| どちらもない | 保存できない: MappingException |
Spring (Java) との対応
@Table("books")
class Book {
@Id Long id;
String title;
@Column("pub_year") Integer year;
@Transient boolean selected;
@Version long version;
}
アノテーションは同じ名前と意味を持ちます。@Unique と @UniqueConstraint は JPA の名前から来ており、@Reference と @OnDelete は追加されたものです (Spring Data JDBC はスキーマを利用者に任せます)。