エンティティ

エンティティは @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;
}

@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 はスキーマを利用者に任せます)。

関連項目