第1回〜第4回で、永続化コンテキスト・エンティティのライフサイクル・flush/commit/rollbackの対応関係、そして@Transactionalの実装まで、JPA/Hibernateの内部動作を一通り追いかけてきました。
最終回は視点を変えて、JPA関連アノテーションを機能別に整理します。
それぞれのアノテーションがこれまでの回で解説したどの内部動作と結びついているかを明示しながら整理していきます。
1. エンティティ定義の基本
| アノテーション | 役割 |
|---|---|
@Entity |
このクラスがJPA管理対象であることを宣言。永続化コンテキストに乗るオブジェクトの起点(第1回) |
@Table(name = "...") |
マッピング先のテーブル名を指定。省略時はクラス名がテーブル名として扱われる |
@MappedSuperclass |
継承元だがテーブルは持たない。フィールドだけを子クラスに提供する(監査カラムの共通化等に使う) |
@Id |
主キーを示す |
@GeneratedValue(strategy = ...) |
主キーの生成方式を指定(4章で詳述、第2回参照) |
@Column(name, nullable, length, updatable...) |
カラムのマッピング詳細(DBカラム名、NULL許容、桁数、更新可否等) |
@Transient |
このフィールドはDBにマッピングしない(JPAの管理対象外) |
@Entityと@MappedSuperclassの使い分け:監査カラム(作成日時・更新日時等)のような全テーブル共通のフィールドは@MappedSuperclassの基底クラスに集約し、各エンティティが継承する構成が定石です。@Inheritance(テーブルを分ける継承)とは目的が異なる点に注意が必要です。
2. 監査(Auditing)関連
AuditorAwareと対になるアノテーション群です。
| アノテーション | 役割 |
|---|---|
@EntityListeners(AuditingEntityListener.class) |
このエンティティにJPA Auditingのリスナーを紐付ける |
@CreatedDate |
persist()時に自動で現在時刻をセット |
@LastModifiedDate |
persist()/merge()時(ダーティチェックで更新検知時)に自動更新(第1回のダーティチェック参照) |
@CreatedBy |
AuditorAwareが返す値を作成者としてセット |
@LastModifiedBy |
同上、更新者としてセット |
これらは単体では動かず、@EnableJpaAuditingとAuditorAware実装がセットで必要です。AuditorAwareの中でSecurityContextHolderから現在の認証情報を取得するのが典型的な実装パターンです。
3. 楽観ロック
| アノテーション | 役割 |
|---|---|
@Version |
楽観ロック用のバージョンカラム。更新のたびに自動インクリメントされ、WHERE version = ?がUPDATE文に付与される |
第1回で説明した「ダーティチェックによるUPDATE文生成」に、このカラムがある場合だけWHERE句にversion条件が追加される、というのが正確な理解です。@Versionはダーティチェックの仕組みに間借りする形で楽観ロックを実現している、という位置づけです。
競合が検出された場合(0件更新になった場合)はjakarta.persistence.OptimisticLockExceptionがスローされます。
これをアプリケーション独自の例外(例:409 Conflictを返すビジネス例外)にラップするのが典型的な実装パターンです。
4. 主キー生成戦略(@GeneratedValue)
第2回で扱った「なぜIDENTITYだとJDBCバッチが効かないか」の実装アノテーションです。
strategy |
内容 | flushへの影響 |
|---|---|---|
GenerationType.IDENTITY |
DBのAUTO_INCREMENT任せ | persist()時に即座にINSERT発行(バッチ化不可) |
GenerationType.SEQUENCE |
DBシーケンスから事前採番 | flushまでINSERTを遅延できる(バッチ化可能) |
GenerationType.TABLE |
採番専用テーブルを使う | ほぼ使われない(性能面で不利) |
GenerationType.AUTO |
Hibernateが方言に応じて自動選択 | DB依存で予測しづらいため明示指定が推奨 |
大量一括INSERTが頻発するようなユースケースではSEQUENCEの採用が有力な選択肢になります(第2回参照)。
5. リレーション(関連)系
| アノテーション | 役割 |
|---|---|
@OneToMany |
1対多。デフォルトFetchType.LAZY。mappedByで外部キー管理の所有権を子に譲る |
@ManyToOne |
多対1。デフォルトFetchType.EAGER(ここだけデフォルトが異なる点に注意) |
@OneToOne |
1対1 |
@ManyToMany |
多対多。中間テーブルが必要(実務では中間エンティティを明示的に作ることが多い) |
@JoinColumn(name = "...") |
外部キーカラム名の指定(@ManyToOne側、所有側) |
@JoinTable |
@ManyToManyで使う中間テーブルの定義 |
**@ManyToOneのデフォルトがEAGERであるという点は、意外と見落とされがちな要注意ポイントです。子エンティティから親を辿る@ManyToOne関連を無自覚にデフォルトのまま使うと、想定外のEager Loadingが連鎖し、パフォーマンス問題の原因になります。明示的にfetch = FetchType.LAZYを指定するのが安全策です。
6. フェッチ戦略の制御
| アノテーション | 役割 |
|---|---|
@EntityGraph(attributePaths = {...}) |
宣言的にJOIN FETCHを指定。Repositoryのメソッドに付与 |
@BatchSize(size = N)(Hibernate固有) |
エンティティ/コレクション単位でバッチフェッチサイズを指定 |
@Fetch(FetchMode.SUBSELECT)(Hibernate固有) |
コレクション取得をサブクエリでまとめて行う |
@EntityGraphはJPA標準ではなくSpring Data JPAが提供する便利機能です(内部的にはJPA標準のEntityGraph APIを組み立てています)。N+1問題対策の第一選択肢として使われます。
public interface OrderRepository extends JpaRepository<Order, Long> {
@Override
@EntityGraph(attributePaths = {"items", "customer"})
Page<Order> findAll(Pageable pageable);
}
7. カスケード・ライフサイクル連動
| アノテーション/属性 | 役割 |
|---|---|
| cascade = CascadeType.ALL | 親エンティティの永続化操作(persist/merge/remove等)を子にも伝播 |
| orphanRemoval = true | 親の関連コレクションから子を取り除いただけで、その子を自動的にDELETE対象にする |
CascadeTypeにはPERSIST, MERGE, REMOVE, REFRESH, DETACHと個別指定できる選択肢がありますが、ALLはその全部という意味です。
双方向@OneToManyの親エンティティに、子要素を追加・削除する専用のヘルパーメソッド(addChild()/removeChild()のようなもの)を定義し、そこからcascade/orphanRemovalが正しく機能するようにするのが定石のパターンです。
@OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
private List<OrderItem> items = new ArrayList<>();
public void addItem(OrderItem item) {
this.items.add(item);
item.setOrder(this); // 双方向の同期を1箇所に集約する
}
8. ライフサイクルコールバック
第2回の「Transient/Persistent/Detached/Removed」の状態遷移のタイミングにフックできるアノテーション群です。
| アノテーション | 発火タイミング |
|---|---|
@PrePersist |
persist()実行前(INSERT前) |
@PostPersist |
INSERT後 |
@PreUpdate |
UPDATE前(ダーティチェックで変更検知された時) |
@PostUpdate |
UPDATE後 |
@PreRemove |
remove()実行時(DELETE前) |
@PostRemove |
DELETE後 |
@PostLoad |
エンティティがDBから読み込まれた直後 |
前述の通り、監査カラムのセットのような「横断的関心事」をここに実装すると、エンティティがSpring Security等の外部依存を持つことになりやすいため、AuditorAwareのような専用の仕組みに任せる方が設計上クリーンです。
一方で、エンティティ自身の整合性検証(例:@PrePersistで必須フィールドの最終チェックを行う)のようなエンティティ自身の責務に閉じた処理であれば、ライフサイクルコールバックの利用は適切です。
9. クエリ関連
| アノテーション | 役割 |
|---|---|
@Query("JPQL文") |
JPQLまたはネイティブSQLを直接指定(Repositoryメソッドに付与) |
@Param("name") |
@Query内の名前付きパラメータとメソッド引数を紐付け |
@Modifying |
@Queryが更新・削除系であることを示す(付けないと例外になる) |
@Modifying(clearAutomatically = true) |
実行後に永続化コンテキストを自動クリア |
@NamedQuery |
エンティティクラスに事前定義したJPQLに名前を付ける(実務ではほぼ使われず@Queryが主流) |
@Modifyingを付けたクエリは、第1回で説明した永続化コンテキスト(ダーティチェックの対象)を経由せず、直接DBにSQLを発行します。
そのため実行後は「メモリ上のエンティティの状態が古いままになる」問題が起こり得ます。clearAutomatically = trueはこれを防ぐための必須設定です。
@Modifying(clearAutomatically = true)
@Query("""
UPDATE Product p
SET p.price = p.price - :discount,
p.version = p.version + 1
WHERE p.category = :category
""")
int bulkDiscountByCategory(@Param("category") String category, @Param("discount") int discount);
versionカラムをクエリ内で明示的にインクリメントしているのは、バルク演算がHibernateの楽観ロック機構(3章参照)を自動的には通らないためです。
10. Spring Data JPA固有(JPA仕様ではないが対で使う)
| アノテーション | 役割 |
|---|---|
@Repository |
Spring管理下のBeanであることの宣言(例外変換の起点にもなる) |
@Transactional |
JPA仕様の外側(第4回で深掘りした内容)。SimpleJpaRepositoryクラス自体にデフォルトでreadOnly = trueが付与されている |
全体の位置付けを俯瞰する
【永続化の骨格】(第1・2回)
@Entity / @Table / @Id / @GeneratedValue / @Column / @MappedSuperclass
【関連とN+1対策】(第1回のダーティチェック・第2回のライフサイクルと関連)
@OneToMany / @ManyToOne / @JoinColumn / cascade / orphanRemoval
+ @EntityGraph / @BatchSize(対策側)
【状態管理】(第1回:ダーティチェック / 第2回:ライフサイクル)
@Version(楽観ロック) + ライフサイクルコールバック群
【監査】(第1回のダーティチェックの応用)
@EntityListeners + @CreatedDate/@LastModifiedDate/@CreatedBy/@LastModifiedBy
+ AuditorAware
【クエリ】(第1回の永続化コンテキストとの関係)
@Query / @Modifying / @Param
【トランザクション】(第3・4回で深掘りした部分)
@Transactional / @PersistenceContext
→ TransactionInterceptor → JpaTransactionManager