spring-data-jpa

Spring Data JPA の実装

目的

Spring Boot のコードベースにおける永続化の設計または実装に特化したタスクでは、このスキルを使用します。このスキルでは、集約ルートに関するガイダンス、クエリパターンの選択、CQRS の読み取りモデルに関する判断、および同梱されたリポジトリとリレーションシップのテンプレートを活用できます。

重要なルール

• すべてのエンティティにリポジトリを作成しないでください。リポジトリは集約ルートに対してのみ作成します。
• クエリが複雑になった場合、長い派生クエリメソッド名に依存しないでください。
• エンティティの状態遷移が重要な場合、save() を無条件に使用しないでください。persist と merge の動作を理解してください。
• 読み取りが多い処理には、プロジェクションまたは専用のクエリサービスを優先してください。
• 既存のアーキテクチャで意図的に別の方法を採用している場合を除き、トランザクション境界はサービス層に配置してください。

ワークフロー

ステップ 1：永続化に関する問題を特定する

まず、必要最小限のコンテキストを収集します。

1. この型は集約ルートですか。それとも内部エンティティですか？
2. タスクは主に読み取り側、書き込み側、またはその両方に関するものですか？
3. クエリは単純な検索、条件付き検索、集計、プロジェクション、または動的な条件指定のどれですか？
4. この処理はパフォーマンスが重要ですか？
5. リレーションシップのモデリングに影響するモジュール境界や疎結合の制約はありますか？

ステップ 2：実装パターンを選択する

次の表を使って、次に読み込む内容を決めます。

パターン	使用する場面	参照先
シンプルなリポジトリ	基本的な CRUD と 1～2 個の単純な検索	既存のコード、またはなし
@Query リポジトリ	複数のフィルター、結合、並べ替え、読みやすい JPQL	references/query-patterns.md
DTO プロジェクション	読み取り専用で、パフォーマンスが重要なレスポンス	references/dto-projections.md
カスタムリポジトリ	Criteria API、一括操作、EntityManager のロジック	references/custom-repositories.md
CQRS クエリサービス	読み取りモデルと書き込みモデルの分離、レポート、専用の読み取り処理	references/cqrs-query-service.md

次の判断ガイドを使用します。

必要なもの	シンプル	@Query	DTO	カスタム	CQRS
基本的な CRUD	はい	はい	いいえ	はい	はい
カスタムフィルター	いいえ	はい	はい	はい	はい
最適な読み取りパフォーマンス	いいえ	場合による	はい	場合による	はい
複雑な動的ロジック	いいえ	いいえ	いいえ	はい	はい
明確な読み取り／書き込みの分離	いいえ	いいえ	場合による	場合による	はい

ステップ 3：該当するリファレンスを読み込む

現在のタスクに必要なリファレンスのみを読み込みます。

• references/query-patterns.md
• references/dto-projections.md
• references/custom-repositories.md
• references/cqrs-query-service.md
• references/relationships.md
• references/performance-guide.md

ステップ 4：該当するアセットを適用する

パターンを一から作り直すのではなく、assets/ にある同梱テンプレートを使用します。

• assets/query-repository.java
• assets/dto-projection.java
• assets/custom-repository.java
• assets/query-service.java
• assets/relationship-patterns.java

テンプレートでは、creating-springboot-projects と同じプレースホルダー規約を使用します。{{PACKAGE}}、{{MODULE}}、{{NAME}}、{{TABLE_NAME}}、{{TYPE}}、{{FIELD}} です。全項目については、creating-springboot-projects/SKILL.md#placeholder-convention を参照してください。

ステップ 5：リレーションシップとトランザクション境界を検証する

変更を確定する前に、次の点を確認します。

• リポジトリが集約ルートの境界にのみ存在する
• 遅延読み込みの動作が意図どおりである
• 行数が増える可能性のある箇所で、ページネーションまたはプロジェクションが使用されている
• 結合エンティティの方が適切な場合に、@ManyToMany が導入されていない
• 適切な箇所で、読み取りサービスが @Transactional(readOnly = true) を使用している
• 書き込み操作がサービス層のトランザクション内にある

ステップ 6：パフォーマンスが重要な処理を検証する

タスクに次の内容が含まれる場合は、references/performance-guide.md を読みます。

• N+1 のリスク
• フェッチプランの問題
• 上限のないクエリ
• バッチ操作
• プロジェクションを使うべき負荷の高い読み取りビュー

優先すべき有用なパターン

リポジトリの境界

• 集約ルートにはリポジトリを設けます。
• 内部の子エンティティには、通常リポジトリを設けません。

クエリのスタイル

• 単純な検索には派生クエリメソッドを使用します。
• 結合、読みやすいテキストブロック、または複数のフィルターには @Query を使用します。
• レスポンスにエンティティが不要な場合は、DTO プロジェクションを使用します。
• 読み取りモデルが書き込みモデルと異なる場合は、CQRS クエリサービスを使用します。

リレーションシップ

• 可能な場合は @OneToMany より @ManyToOne を優先します。
• ナビゲーションより疎結合が重要な場合は、エンティティ参照ではなく ID を使用します。
• @ManyToMany は警告のサインと見なし、明示的な結合エンティティを優先します。

出力形式

永続化の変更を提案または実装する場合は、次の形式で返します。

## Recommended pattern
- Pattern:
- Why:

## Files to change
- `path/to/file`

## References used
- `references/...`

## Risks to verify
- ...

このスキルを使用しない場合

• Spring Data JPA の範囲外にある一般的な SQL 作業やデータベース管理作業
• プロジェクト全体の移行計画
• creating-springboot-projects に該当する、プロジェクト全体の大規模なひな形作成