
# 参照とキー

集約は、相手のオブジェクトを持つのではなく、ID で互いを参照します。書き方は 2 つあります。`AggregateReference<Author, int>` のプロパティか、`@Reference(Author)` を付けた単なる `int authorId` です。どちらも、スターターが作るスキーマでは外部キーになり、メモリ上のストアでも同じ方法で強制されます。

## 使う理由

オブジェクトではなく ID を持つことで、各集約は一つの単位に保たれます。本を読み込んでもその著者は読み込まれず、本を保存してもその著者は保存されません。必要なときに、著者はそれ自身のリポジトリで読み込みます。外部キーと `@OnDelete` は、著者がいなくなったときにデータベースが何をするかを示すため、ルールはすべてのサービスではなく一か所にまとまります。

## 例

```dart
@Table('books')
@UniqueConstraint(['authorId', 'title'], name: 'uq_books_author_title')
class Book {
  Book({this.id, required this.title, required this.authorId, this.editor});

  @Id()
  int? id;

  String title;

  // 単なる ID: 型は Author の @Id から来て、起動時にチェックされる。
  // 派生クエリ (findByAuthorId) と @Query は、他の列と同じくこれを扱う。
  @Reference(Author)
  @OnDelete(OnDeleteAction.cascade)    // 著者を削除すると、その本も削除される
  int authorId;

  // または AggregateReference。@OnDelete がなければ noAction。
  AggregateReference<Editor, int>? editor;
}

@Table('authors')
class Author {
  Author({this.id, required this.name});

  @Id()
  int? id;

  @Unique()                           // 同じ名前の 2 人目の著者: DuplicateKeyException
  String name;
}
```

```dart
abstract interface class BookRepository implements ListCrudRepository<Book, int> {
  Future<List<Book>> findByAuthorId(int authorId);
  Future<List<Book>> findByEditor(AggregateReference<Editor, int> editor);
}

final books = await repository.findByEditor(const AggregateReference(7));
print(books.first.editor?.id); // 7
```

## AggregateReference か @Reference か

| | `AggregateReference<Author, int>` | `@Reference(Author) int authorId` |
|---|---|---|
| Spring Data JDBC | あり | なし (追加されたもの) |
| プロパティの型 | 参照 | ID の型 |
| 列 | プロパティ名をスネークケースにしたもの (`editor`)、または `@Column` | プロパティ名をスネークケースにしたもの (`author_id`)、または `@Column` |
| 型のチェック | 型引数 `ID` | プロパティの型は `Author` の `@Id` の型でなければならない (nullable かどうかは別)。そうでなければ両方を示して起動が失敗する |
| 派生クエリ | `findByEditor(AggregateReference<Editor, int>)` | `findByAuthorId(int)` |

参照されるクラスは集約のルート、つまり `@Id` を持つ `@Table` クラスでなければなりません。

## @OnDelete

参照に付けた `@OnDelete(OnDeleteAction.x)` は、参照される集約が削除されたときに、参照している行に何が起こるかを選びます。

| アクション | 起こること |
|---|---|
| `noAction` | それを参照する行がある間は削除が失敗する。文の終わりにチェックされる。デフォルトで、`@OnDelete` がない場合も同じ。 |
| `restrict` | `noAction` と同じだが、行ごとに即座にチェックされる: 互いに参照する行 (自己参照) の削除は、`noAction` なら通るところで失敗することがある。 |
| `cascade` | 参照している集約も削除され、それを参照するものも再帰的に削除される。 |
| `setNull` | 参照しているプロパティが null に設定される。nullable でなければならず、そうでなければ起動が失敗する。 |
| `setDefault` | 参照しているプロパティがそのデフォルトに設定される: フィールドの定数の初期化子 (`int? publisherId = 1`) またはコンストラクターのパラメーターの定数のデフォルトで、生成されたスキーマでは列の `DEFAULT` として書かれる。デフォルトのないプロパティは起動を止める。 |

これを行うのはリポジトリではなくデータベースです。カスケードや `setNull` はリポジトリの `delete` や `save` を通らないため、`@Version` はチェックされず、監査も影響を受ける行に触れません (Hibernate の `@OnDelete` にも同じ制限があります)。メモリ上のストアは、データベースと同じように動作するため、同じことをします。そのカスケードは再帰的で、トランザクションの中で実行されるため、ロールバックで取り消されます。

## @Unique と @UniqueConstraint

- プロパティに `@Unique()`: その値はテーブル内で一意でなければなりません。SQL と同じく、複数の行が null を持てます。
- クラスに `@UniqueConstraint(['authorId', 'title'], name: ...)`: 列挙したすべてのプロパティで同じ値を持つ 2 つの行があってはいけません (その中に null を含む行は決して衝突しません)。名前は Dart のプロパティ名で、起動時にチェックされます。繰り返し付けられます。
- 名前がなければ、制約は `uq_<table>_<columns>` です。
- それに違反する保存は、データベースでもメモリ上のストアでも `DuplicateKeyException` を投げます。

Dart では `@Column('x')` に名前付きの `unique:` を追加できない (位置引数と名前付き引数を混ぜられない) ため、一意性は独立したアノテーションになっています。

## スキーマ

- `spring.data.jdbc.schema=create` では、すべての参照は (その `ON DELETE` を伴う) 外部キー (`REFERENCES "authors"("id")`) になり、その列にインデックスが作られます。`@Unique` と `@UniqueConstraint` は `UNIQUE` 制約になります。外部キーはテーブルの後に来るため、循環する参照も動きます。
- `spring.data.jdbc.schema=validate` (デフォルト) では、データベースにない明示的な `@OnDelete`、`@Unique`、`@UniqueConstraint` はエラーです。外部キーのない参照は警告です。その整合性は強制されません。

## メモリ上のストア

メモリ上のストアは `foreign_keys = ON` の SQLite とまったく同じように動作するため、メモリ上で通るテストが本番で失敗することはありません。

- 存在しない集約への参照は `DataIntegrityViolationException` です。
- 削除は `@OnDelete` に従います。
- 重複は `DuplicateKeyException` です。
- null の参照と null の一意な値は、決してチェックされません。

## Spring (Java) との対応

```java
@Table("books")
class Book {
  @Id Long id;
  String title;
  AggregateReference<Author, Long> author;
}
```

Spring Data JDBC には `AggregateReference` しかなく、外部キー、カスケード、一意制約は利用者自身のスキーマに任されます。JPA の `@ManyToOne` は、オブジェクトグラフを除けば `@Reference` に最も近いものです。

## 関連項目

- [エンティティ](entities.md)
- [スキーマとマイグレーション](schema.md)
- [エラー](errors.md)
