412-frameworks-quarkus-panache

Hibernate ORM with Panache

Quarkus で Hibernate ORM に Panache パターンを適用します。

このスキルで扱う内容

• アクティブレコード（PanacheEntity）と PanacheRepository の比較 — それぞれの使いどころ
• パラメーター化された JPQL／Panache クエリ：位置パラメーター（?1）と名前付きパラメーター（:param）— 安全でない文字列連結は使用しません
• 再利用可能で、ビルド時に検証されるクエリを実現する、エンティティの @NamedQuery
• 管理対象エンティティを公開しないための、project(Class) による DTO プロジェクション
• Page.of(pageIndex, pageSize) と query.count() によるページネーション
• JPQL クエリでの JOIN FETCH による N+1 の回避
• @Version による楽観的ロックと OptimisticLockException の処理
• @Transactional を使用したアプリケーションサービス
• @QuarkusTest テストで自動ロールバックを行う @TestTransaction
• エンティティのマッピングと、REST 境界での DTO の公開
• 同じトランザクション内で制御された SQL を使用する場合の Hibernate 経由のネイティブクエリ。境界で Hibernate を介さず JDBC を使う場合は @411 と組み合わせます

対象範囲： リファレンスのルールと良い例／悪い例に基づいて、推奨事項を適用します。

制約

永続化の変更前にコンパイルし、変更後に検証してください。

• 必須：変更を適用する前に ./mvnw compile または mvn compile を実行してください
• 前提条件：Panache の改善を適用する前に、プロジェクトがコンパイルできる必要があります
• 安全性：コンパイルに失敗した場合は、直ちに停止してください
• ブロック条件：続行する前に、コンパイルエラーをユーザーが解決する必要があります
• 検証：改善を適用した後、./mvnw clean verify または mvn clean verify を実行してください
• 適用前：詳細なルールと例について、リファレンスを読んでください

このスキルを使用する場面

• Quarkus の Panache エンティティまたはリポジトリーをレビューする
• Panache を使用した Hibernate ORM のデータアクセスを改善する
• Panache クエリに DTO プロジェクション、JOIN FETCH、ページネーション、または楽観的ロックを追加する
• Quarkus Panache の N+1 クエリ問題を修正する、または @Version による同時実行制御を追加する
• Panache のアクティブレコードとリポジトリーの設計を改善する

ワークフロー

1. リファレンスを読み、プロジェクトの状況を確認する

references/412-frameworks-quarkus-panache.md を読み、変更を提案する前に現在のプロジェクト設定を確認してください。

2. 対象範囲を把握し、改善対象を決める

求められる成果、制約、および適用する変更の最小かつ安全な範囲を特定してください。

3. フレームワークに沿った変更を適用する

リファレンスのパターンとプロジェクトの規約に従って、設定／コードを実装またはリファクタリングしてください。

4. 検証を実行し、結果を報告する

適切なビルド／テストを実行し、変更内容、検証した内容、および今後必要な対応をまとめてください。

リファレンス

詳しいガイダンス、例、制約については、references/412-frameworks-quarkus-panache.md を参照してください。