
# エンティティ

エンティティは `@Table` を付けた Dart のクラスで、一つのテーブルに保存される集約のルートです。各プロパティが列になります。ジェネレーターはビルド時にクラスを記述するため、リポジトリはリフレクションなしにそのプロパティを読み、コンストラクターを呼びます。

## 使う理由

Spring Data JDBC のモデルでは、集約は一つの単位です。子とともに、丸ごと読み込まれ、丸ごと保存され、丸ごと削除されます。他の集約は ID で参照され、一緒に読み込まれることはありません。これによりマッピングは予測しやすくなります。遅延読み込みも、変更を追跡するセッションも、オブジェクトを包むプロキシもありません。手にしているのは普通の Dart のオブジェクトで、`save` はそれをすぐに書き込みます。

## 例

```dart
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` ([ロック](locks.md) を参照)。 |
| `@MappedCollection(idColumn:, keyColumn:)` | プロパティ | ルートとともに保存、読み込み、削除される子エンティティの `List`、`Set`、`Map`。 |
| `@CreatedDate()`、`@LastModifiedDate()`、`@CreatedBy()`、`@LastModifiedBy()` | プロパティ | 保存時に設定される監査の値 ([監査](auditing.md) を参照)。 |
| `@Reference(Type)`、`@OnDelete(action)` | プロパティ | ID による別の集約への参照 ([参照とキー](references.md) を参照)。 |
| `@Unique()`、`@UniqueConstraint([...], name:)` | プロパティ、クラス | 一意な値 ([参照とキー](references.md) を参照)。 |

## 名前

デフォルトの命名戦略は、すべての名前をスネークケースで書きます。

| Dart | データベース |
|---|---|
| クラス `OrderLine` | テーブル `order_line` |
| プロパティ `createdAt` | 列 `created_at` |
| クラス `HTTPRequest` | テーブル `http_request` (略語は一つの単語) |
| プロパティ `line2Item` | 列 `line2_item` (数字は前の単語とともに残る) |

アノテーションの値は、書かれたとおりに常に優先されます。アプリケーション全体のルールを変えるには、`NamingStrategy` を継承してメソッド (`tableName`、`columnName`、マッピングされたコレクションの 2 つ) をオーバーライドし、Bean として宣言します。独自の `NamingStrategy` の Bean は、派生した名前を `@Query` のテキストのビルド時のチェックから隠します ([@Query](query.md) を参照)。

## 型

| 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`](json-columns.md) を付けたクラス、`Map`、`List`、`Set` | `TEXT` の JSON | `JSONB` または `JSON` |

nullable な Dart の型は nullable な列になります。非 nullable なものは、スターターが作るスキーマでは `NOT NULL` になり、`spring.data.jdbc.schema=validate` でチェックされます。

`Map`、`List`、`Set` は、それだけでは列になりません。[`@Json`](json-columns.md) を付けるか、子テーブルの行にするなら `@MappedCollection` を付けます。どちらもなければ、SQL のストアは、ビルド時またはアプリケーションの起動時に、直し方とともにそのプロパティを拒否します ([JSON の列](json-columns.md) を参照)。

## イミュータブルなエンティティ

フィールドは `final` でもかまいません。その場合リポジトリは、値を変える必要がある箇所 (生成された ID、新しいバージョン、監査の値) で、コンストラクターを通してコピーを作ります。そのため、常に `save` が返すエンティティを使ってください。

```dart
@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

```dart
@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) との対応

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

## 関連項目

- [参照とキー](references.md)
- [リポジトリ](repositories.md)
- [スキーマとマイグレーション](schema.md)
