
# データ: エンティティ、リポジトリ、クエリ

`spring_boot_starter_data` を使うアプリケーションに対して、ジェネレーターは Spring Data がアプリケーションの起動時に行う作業を行います。エンティティを読み、リポジトリのインターフェースを実装し、派生クエリメソッドの名前を解析し、`@Query` のテキストをチェックします。そのすべてがビルド時に行われるので、アプリの起動時に解析や記述は何も行われず、綴りを間違えたプロパティは起動時の失敗ではなく、提案付きのビルドエラーになります。

データスターターのアノテーションは URL で照合されるので、ジェネレーターはスターターに依存しません。

## 使う理由

Spring Data は実行時に動的プロキシでリポジトリの実装を作り、起動のたびに `findByTitleAndYear` のようなメソッド名を解析します。Dart は実行時にクラスを作れず、起動時の解析はモバイルアプリの起動のたびに時間を食います。ビルドはすでにエンティティ、インターフェース、`lib/resources/` の SQL ファイルを見ているので、実装を書き、すべてをエンティティに対してチェックし、インターフェースのすべての問題を一度に報告できます。

## エンティティ: `EntityIntrospection`

各 `@Table` クラスと、`@Query` メソッドが返す各クラス (DTO) に対して、ジェネレーターは `EntityIntrospection` を書き出します。定数としてのプロパティと、一つのプロパティを読む、コンストラクターを呼ぶ、一つのプロパティを設定するクロージャーです。それ以上はありません。

入力:

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

  @Id()
  int? id;

  String name;

  @Unique()
  String? isni;
}
```

出力 (ジェネレーターのテストから。プレフィックスは外しています):

```dart
EntityIntrospection<Author>(
  r'Author',
  const [
    EntityProperty(r'id', ClassType<int>(nullable: true),
        annotations: [Id()], parameter: true, writable: true),
    EntityProperty(r'name', ClassType<String>(),
        parameter: true, writable: true),
    EntityProperty(r'isni', ClassType<String>(nullable: true),
        annotations: [Unique()], parameter: true, writable: true),
  ],
  annotations: const [Table(r'authors')],
  get: (e, i) => switch (i) {
    0 => e.id,
    1 => e.name,
    _ => e.isni,
  },
  create: (v) => Author(
      name: v[1] as String, id: v[0] as int?, isni: v[2] as String?),
  write: (e, i, v) => switch (i) {
    0 => e.id = v as int?,
    1 => e.name = v as String,
    2 => e.isni = v as String?,
    _ => null,
  },
)
```

- `parameter: true` はコンストラクターが受け取るプロパティを、`writable: true` は設定できるプロパティを示します。イミュータブルなエンティティ (`final` フィールドのみ) には `write` がありません。
- コンストラクターのデフォルトは保たれます (`hasDefaultValue: true, defaultValue: 0`)。
- `@Transient` プロパティも記述されるので、データ層はそれらをスキップできます。`@MappedCollection` プロパティとその子エンティティも記述されます。
- `@Query` メソッドの DTO は、アノテーションなしでエンティティと同じように記述されます。`Future`、`Stream`、`Set`、`Page`、nullable な型の下でも見つけられます。

モジュールのすべての記述は、データ層が読む一つの Bean `entityIntrospections#<module>` (`EntityIntrospections`) にまとめられます。エンティティのないモジュールにはこれがありません。

`@Table` クラスは、`@Introspected` でもない限り、`Introspection` (JSON と SpEL が使う一般的な記述) を **受け取りません**。データ層に必要なのは `EntityIntrospection` だけです。

### エンティティのエラー

データ層がクラスを生成したり値を入れたりできない場合、ビルドは失敗します。

| 問題 | メッセージ (一部) |
|---|---|
| どのフィールドも指さない必須のコンストラクターパラメーター (`Book(String isbn)`) | `Book(isbn)` を示し、`names no field` と伝え、`this.isbn` を提案する |
| public な無名コンストラクターがない | `@Table class Book has no public unnamed constructor ...` と `Add one` |
| private なクラス | `@Table class _Book must be public ...` |
| 抽象クラス | `@Table class Book is abstract ...`。具象クラスを求める |

どのフィールドも指さない省略可能なパラメーターは `create` から除外されます。

## リポジトリ: `SimpleRepository` を継承するクラス

`DataRepository` を (直接、または `CrudRepository`、`ListCrudRepository` などを通して) 継承する各インターフェースに対して、ジェネレーターはクラスを書き出します。それは CRUD メソッドを持つスターターの `SimpleRepository` を継承し、インターフェースのその他のメソッドごとに一行を追加します。スターターが起動時に読むためにメソッドを記述するものはありません。

入力:

```dart
abstract interface class BookRepository
    implements ListCrudRepository<Book, int> {
  Future<List<Book>> findByTitleAndYear(String title, int year);

  @Query('select title from books where year = :year')
  Future<List<BookCard>> cards(int year);
}
```

出力 (プレフィックスは外しています):

```dart
class _$BookRepositoryImpl extends SimpleRepository<Book, int>
    implements BookRepository {
  _$BookRepositoryImpl(super.operations);

  static _$BookRepositoryImpl $create(DependencyResolver r) =>
      _$BookRepositoryImpl(r
          .dependency<RepositoryFactory>()
          .operations<Book, int>(r'BookRepository', queries: [_cards]));

  static const _findByTitleAndYear = PartTree(r'findByTitleAndYear', [
    OrPart([Part(r'title'), Part(r'year')]),
  ]);

  static const _cards = QueryMethod(
    r'cards',
    Query(r'select title from books where year = :year'),
    parameters: [r'year'],
    element: ClassType<BookCard>(),
  );

  @override
  Future<List<Book>> findByTitleAndYear(String title, int year) =>
      this.operations.list(_findByTitleAndYear, [title, year]);

  @override
  Future<List<BookCard>> cards(int year) =>
      this.operations.query<List<BookCard>>(_cards, [year]);
}
```

Bean 定義はインターフェースとそのスーパータイプを `create: (r) => _$BookRepositoryImpl.$create(r)` で登録します。Bean 名はインターフェース名の先頭を小文字にしたもの (`bookRepository`)、または `@Repository('library')` で与えた名前です。インターフェースのアノテーション (`@Repository`、`@UseStore`) は `operations` に渡されます。

CRUD メソッドだけのリポジトリは空のクラスを受け取ります。インターフェースが再宣言した CRUD メソッドは `SimpleRepository` に任されます。ジェネリックな基底インターフェース (`interface Crud<E> extends DataRepository<E, int>`) は Bean にならず、具象の `@Repository` クラスは普通のコンポーネントのままです。

## 派生クエリ: 定数の `PartTree`

名前が `find`、`read`、`get`、`query`、`search`、`stream`、`count`、`exists`、`delete`、`remove` で始まり、任意で単語が続き、その後に `By` が来るメソッドは派生クエリです。ビルドは Spring Data の `PartTree` と同じように名前を読み (`Distinct`、`First`/`Top<n>`、`And`、`Or`、演算子、`IgnoreCase`、`AllIgnoreCase`、`OrderBy...Asc/Desc`)、結果を定数として書き出します。

```dart
static const _findByTitleContaining = PartTree(r'findByTitleContaining', [
  OrPart([Part(r'title', PartType.containing)]),
]);
```

操作はメソッドの戻り値の型に従います。

| 戻り値の型 | 呼び出し |
|---|---|
| `Future<List<Book>>`、`Future<Iterable<Book>>` | `list` |
| `Future<Set<Book>>` | `set` |
| `Future<Book?>` | `one` |
| `Future<Book>` | `single` |
| `Stream<Book>` | `stream` |
| `Future<Page<Book>>` (`Pageable` パラメーター付き) | `page` |
| `Future<Slice<Book>>` (`Pageable` パラメーター付き) | `slice` |
| `countBy...` からの `Future<int>` | `countBy` |
| `existsBy...` からの `Future<bool>` | `existsBy` |
| `deleteBy...` / `removeBy...` からの `Future<int>` または `Future<void>` | `deleteBy` |
| `deleteBy...` からの `Future<List<Book>>` | `deleteByReturning` |

`Sort` と `Pageable` のパラメーターは名前で渡され (`sort: order`)、`@Lock` は呼び出しと一緒に渡されます。

### 派生クエリのエラー

ビルドは各名前を、エンティティ、パラメーター、戻り値の型と照合します。間違った名前、未知のプロパティ、コレクションや入れ子のパスであるプロパティ、合わないパラメーターはビルドを失敗させます。一つのインターフェースのすべての問題は一つのエラーにまとめられ、メソッドの順に、メソッドごとに一行です。

```text
Invalid repository BookRepository:
  - BookRepository.findByTitel: No property 'titel' found for type 'Book'; did you mean 'title'? Available properties: id, title, year.
  - BookRepository.findAll: not a CRUD method of the repository interfaces and not a derived query
  - BookRepository.twice has a body: every method of the interface is implemented by the generated class.
```

- 「did you mean」は、十分に近いプロパティがある場合に現れます。そうでなければ、使えるプロパティだけが列挙されます。
- メソッドは最初の問題だけを報告します (`findByTitelAndYeer` は `titel` を報告します)。
- 問題のある二つのリポジトリは、それぞれ独自のエラーを受け取ります。
- エンティティを指定しないリポジトリ (型引数なしの `implements DataRepository`)、nullable なエンティティ型、private なインターフェースも失敗します。

## `@Query` メソッド

`@Query` を持つメソッドは、小さな `QueryMethod` 定数として書かれます。ビルドは書き出す前に、メソッドとそのテキストをチェックします。

**メソッドとそのアノテーション。** メッセージの一部:

| メソッド | メッセージ (`BookRepository.<method>: ` の後) |
|---|---|
| `@Query('select * from books') Future<void> voidRead();` | `the method returns nothing: a change needs @Modifying, a read a result type` |
| `@Modifying() ... Future<String> modifyingText();` | `@Modifying returns the rows changed (Future<int>), whether any changed (Future<bool>) or nothing (Future<void>), not String` |
| `... Future<Page<Book>> pageAlone();` | `a page needs a Pageable parameter (the window to read)` |
| `Page` を返さないメソッドの `countQuery:` | `countQuery is for a method that returns a Page` |
| `... Future<Map<String, int>> intMap();` | `a row as a map is a Map<String, Object?>, not Map<String, int>` |
| private な `rowMapper` | `the rowMapper of @Query must be public: the generated code refers to it` |

**テキストのパラメーターとプレースホルダー。**

| テキスト | メッセージ (`BookRepository.<method>: ` の後) |
|---|---|
| `... where year = :yeer` (パラメーター `year`) | `:yeer matches no parameter of the method (it has year)` |
| `... where year = :book.year` | `:book.year matches no parameter of the method (it has book) (to read a property write :#{#book.year})` |
| `... where year = ?` | `the query has a plain ? marker: write :name and bind it by the name of a parameter of the method` |
| `select * from #{#tableName} ...` | `#{#tableName} is not allowed in the SQL text: only #{#entityName} is; to bind a value write :#{#tableName}` |
| `select * from {Bok}` | `{Bok}: no @Table class Bok in the application, did you mean 'Book'?` |
| `select {Book.titel} from {Book}` | `{Book.titel}: Book has no property titel, did you mean 'title'? (stored properties: id, title, year, authorId)` |
| `select {Book.cache} from {Book}` | `{Book.cache}: Book.cache is @Transient: it has no column` |

`countQuery` も同じようにチェックされ、`BookRepository.counted (countQuery): ...` のように名前が付きます。エンティティのプレースホルダーは定数の一部になります: `entities: {r'Book': Book}`。

**テーブルとカラム。** ビルドは `lib/resources/` のマイグレーションと初期化スクリプトからスキーマを知ります。それらはスターターが見つけるのと同じように見つけられます (`spring.sql.migration.locations`、デフォルトは `resources:db/migration`。`spring.sql.init.schema-locations`)。SQL ファイルがなければ、エンティティがスキーマです。綴りを間違えたテーブルやカラムは、既知の名前が近い場合にビルドを失敗させます。

```text
  - BookRepository.column: b.titel: no column titel in books, did you mean 'title'?
  - BookRepository.table: bokks: no table bokks, did you mean 'books'?
```

ビルドがスキーマに確信を持てない場合、このチェックは自動的に無効になります。`lib/resources/` の外やプレースホルダー付きの場所、場所を変えうるプロファイルのファイルやインポート、解析できないファイル、カラムに別の名前を付けうるアプリケーションの `NamingStrategy` Bean です。

## `@Query` の中の SpEL: Dart にコンパイル

`@Query` テキストの中の `:#{...}` の値は SpEL 式です。ビルドは可能な場合、パラメーターの型に対してチェックしたうえで、式を Dart にコンパイルします。

```dart
@Query('select * from books where title = :#{#book.title}')
Future<List<Book>> sameTitle(Book book);
```

```dart
static final _sameTitle = QueryMethod(
  r'sameTitle',
  const Query(r'select * from books where title = :#{#book.title}'),
  parameters: const [r'book'],
  element: const ClassType<Book>(),
  expressions: [(arguments, context) => (arguments[0] as Book).title],
);
```

コンパイルされた式は関数なので、`QueryMethod` は `static const` ではなく `static final` になります。コンパイラーが扱えるのは、名前による引数 (`#book`)、位置による引数 (`#p1`、`#a0`、`[0]`)、コンテキストの `#entityName` と `#methodName`、アプリケーションの Bean (`@cutoffs.year` は `context.bean(r'cutoffs')` に対する型付きの呼び出しになります)、環境 (`@environment.getProperty('c', '0')`) です。

式の間違いはビルドエラーです。

| 式 | メッセージ (`BookRepository.<method>: the expression :#{...} is invalid: ` の後) |
|---|---|
| `#book.titel` | `No property 'titel' on type 'Book'; did you mean 'title'?` |
| `#yeer` | `Unknown variable '#yeer'; did you mean '#year'?` |
| `1 +` | `Invalid expression: EL1042E...` |
| `#book.title.substring()` | `Method 'String.substring' takes between 1 and 2 arguments, but 0 were given` |
| `#book?.title.length` | `Cannot read property 'length' on String?` |

コンパイラーが扱えないもの (`T(String).valueOf(...)` の呼び出し、`${property}` プレースホルダーを含むテキスト) は、実行時の SpEL インタープリターに任されます。`expressions` のそのエントリーは `null` です。その場合、そのような式が到達するクラスと、そのメソッドを呼ぶ Bean は、インタープリターが必要とする `Introspection` を受け取ります ([実行されるものだけ](optimizations/introspection.md) を参照)。エンティティがそれを受け取ることはありません。

## `@Procedure`、`watch…By`、`changes…By`

[`@Procedure('name')`](../spring-boot-starter-data/database-functions.md) の付いたメソッド (データベース関数) は、`ProcedureMethod` の定数と、`operations.procedure<R>` の呼び出し (`Stream` では `operations.procedureStream<E>`) として書かれます。

```dart
static const _over = ProcedureMethod(
  r'over',
  Procedure(r'books_over'),
  parameters: [r'minYear'],
  element: ClassType<Book>(),
);

@override
Future<List<Book>> over(int minYear) =>
    this.operations.procedure<List<Book>>(_over, [minYear]);
```

その行から作られるクラスは、`@Query` のものと同じように記述されます。ビルドは、`Page` や `Slice` の結果、`Pageable` や `Sort` のパラメーター、空の関数名、そして `@Query`、`@Modifying`、`@Lock` と一緒の `@Procedure` を拒否します。

[行の変更](../spring-boot-starter-data/changes.md)を報告するストアのために、二つのプレフィックスが find と同じように派生されます。`watch…By` (`Stream<List<T>>`、`operations.watch` の呼び出し) と `changes…By` (`Stream<RowChange<T>>`、`operations.changes` の呼び出し) です。それ以外の戻り値の型は、期待される型を示すビルドエラーです。`changes…By` の名前に書けるのは条件だけです。

## メソッドがストアに必要とするもの

生成されたクラスは、各メソッドがストアに必要とするものを、`StoreRequirement` としてリポジトリの操作に伝えます。`@Lock` (locks)、`@Query` (queries)、`@Procedure` (functions)、`watch` または `changes` のメソッド (changes)、メソッドの `@Transactional` (transactions) です。

```dart
operations<Book, int>(
  r'Ledger',
  annotations: const [UseStore(r'jdbc')],
  functions: [_over],
  requirements: const [
    StoreRequirement(r'over', DataStoreCapability.functions),
    StoreRequirement(r'findByIsbn', DataStoreCapability.transactions),
  ],
)
```

ランタイムは、リポジトリが作成されるときに、それをストアと比較します。ビルドは、ストアを知っている場合、それをより早く行います。アプリケーションの依存関係の `lib/spring_auto_configuration.dart` が宣言またはエクスポートする [`@DataStoreDeclaration`](../spring-boot-starter-data/stores.md) の定数を読み、リポジトリのストアを、その `@UseStore`、`@UseDataSource` (SQL のストア)、`application.yml` または `application.properties` (プロファイルなし) の `spring.data.store`、または `defaultWhen` が成り立つ最初の記述されたストアから判断します。そのとき、ストアにない機能はリポジトリの問題の一つになり、トランザクションなしと記述されたデフォルトのストアでの `@Transactional` の Bean (`transactionManager:` なし) はビルドを失敗させます。何も記述していないストアは、ランタイムに任されます。

アップグレードの後は、リポジトリを生成し直す必要があります。生成されたクラスが `requirements:` を渡すためです。

`DataStoreDescriptor(collectionsNeedJson: true)` で記述されたストア (SQL のストア) では、ビルドはリポジトリのエンティティと、そのマッピングされたコレクションの子もチェックします。[`@Json`](../spring-boot-starter-data/json-columns.md) も `@MappedCollection` もない `Map`、`Set`、そして単純な値以外の `List` は、直し方とともに、リポジトリの問題の一つになります (`Parcel.meta: a Map<String, Object?> property without @Json has no column on a SQL store: add @Json() to keep it as JSON, or @MappedCollection for rows of a child table`)。単純な値のリストはストアに任されます。ストアは、それを配列の列に保持できるかもしれません。

## 関連項目

- [ビルド時のチェック](checks.md)
- [ストアとその機能](../spring-boot-starter-data/stores.md)
- [Bean 定義](bean-definitions.md)
- [テスト: @SpringBootTest と @DataTest](tests.md)
- [実行されるものだけ: イントロスペクション](optimizations/introspection.md)
- [SpEL](../spring-core-dart/spel/index.md)
