Spring JPA永続化コンテキスト入門 - EntityManagerとキャッシュの仕組み

Spring JPAを使用したアプリケーション開発において、永続化コンテキスト（Persistence Context）とEntityManagerの理解は、パフォーマンスの最適化やデータ整合性の確保に不可欠です。本記事では、JPAの内部動作の核心である永続化コンテキストの仕組み、EntityManagerのライフサイクル管理、1次キャッシュによるパフォーマンス向上、エンティティの4つの状態遷移、そしてダーティチェックによる自動更新メカニズムを体系的に解説します。これらを正しく理解することで、意図しないデータ更新やN+1問題などのパフォーマンス課題を未然に防ぐことができます。

実行環境と前提条件

本記事の内容を実践するにあたり、以下の環境を前提としています。

項目	バージョン・要件
Java	17以上
Spring Boot	3.4.x
Spring Data JPA	3.4.x（Spring Boot Starterに含まれる）
Hibernate	6.6.x（Spring Data JPAに含まれる）
データベース	H2 Database（開発・テスト用インメモリDB）
ビルドツール	Maven または Gradle
IDE	VS Code または IntelliJ IDEA

事前に以下の準備を完了してください。

JDK 17以上のインストール
Spring Boot + Spring Data JPAプロジェクトの基本構成
Maven または Gradle によるプロジェクトビルド環境

永続化コンテキストとは

永続化コンテキスト（Persistence Context）は、JPAにおけるエンティティの管理領域です。Jakarta Persistence仕様では「永続化されたエンティティIDに対して一意のエンティティインスタンスが存在するマネージドエンティティインスタンスの集合」と定義されています。

簡単に言えば、永続化コンテキストはアプリケーションとデータベースの間に位置する「一時的なキャッシュ領域」であり、EntityManagerを通じてエンティティのライフサイクルを管理します。

flowchart TB
    subgraph Application["アプリケーション層"]
        Service["Service"]
        Repository["Repository"]
    end
    
    subgraph PersistenceLayer["永続化層"]
        EM["EntityManager"]
        subgraph PC["永続化コンテキスト"]
            Cache["1次キャッシュ"]
            Entity1["Entity A"]
            Entity2["Entity B"]
            Entity3["Entity C"]
        end
    end
    
    subgraph Database["データベース"]
        Table1["テーブルA"]
        Table2["テーブルB"]
        Table3["テーブルC"]
    end
    
    Service --> Repository
    Repository --> EM
    EM --> PC
    PC <--> Database

永続化コンテキストの主な役割

永続化コンテキストは以下の4つの重要な役割を担います。

エンティティの同一性保証: 同じ永続化コンテキスト内では、同じ主キーを持つエンティティは常に同一のJavaオブジェクトを参照します
1次キャッシュ: データベースアクセスを最小化し、パフォーマンスを向上させます
トランザクショナルライトビハインド: 変更をバッファリングし、トランザクションコミット時に一括でデータベースに反映します
ダーティチェック: エンティティの変更を自動的に検出し、UPDATE文を生成します

EntityManagerのライフサイクルとスコープ

EntityManagerは永続化コンテキストと対話するためのAPIであり、エンティティの永続化、検索、削除などの操作を提供します。Spring環境では、EntityManagerのライフサイクル管理方式によって動作が異なります。

コンテナ管理EntityManager（推奨）

Spring Bootでは、@PersistenceContextアノテーションを使用してEntityManagerをインジェクションします。この方式では、Springコンテナが自動的にEntityManagerのライフサイクルを管理します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@Service
@Transactional
public class UserService {
    
    @PersistenceContext
    private EntityManager entityManager;
    
    public User findById(Long id) {
        return entityManager.find(User.class, id);
    }
    
    public void save(User user) {
        entityManager.persist(user);
    }
}

コンテナ管理EntityManagerには2種類のスコープがあります。

スコープ	説明	用途
トランザクションスコープ（デフォルト）	トランザクション開始時に永続化コンテキストが作成され、コミット/ロールバック時に破棄される	一般的なWebアプリケーション
拡張スコープ	Stateful Session Beanのライフサイクルに紐づき、複数トランザクションをまたいで永続化コンテキストを保持する	会話的なUIフロー

アプリケーション管理EntityManager

EntityManagerFactoryから直接EntityManagerを生成する方式です。この場合、アプリケーション側でライフサイクル管理の責任を負います。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@Service
public class UserService {
    
    @PersistenceUnit
    private EntityManagerFactory emf;
    
    public User findById(Long id) {
        EntityManager em = emf.createEntityManager();
        try {
            return em.find(User.class, id);
        } finally {
            em.close(); // 明示的にクローズが必要
        }
    }
}

アプリケーション管理EntityManagerは、バッチ処理や特殊なトランザクション制御が必要な場面で使用しますが、通常のWebアプリケーションではコンテナ管理を推奨します。

Spring Data JPAにおけるEntityManager

Spring Data JPAを使用する場合、JpaRepositoryインターフェースの背後でEntityManagerが自動的に利用されます。明示的にEntityManagerを操作する必要はありませんが、カスタムリポジトリ実装では直接アクセスすることも可能です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@Repository
public class CustomUserRepositoryImpl implements CustomUserRepository {
    
    @PersistenceContext
    private EntityManager entityManager;
    
    @Override
    public List<User> findByCustomCriteria(String criteria) {
        return entityManager.createQuery(
            "SELECT u FROM User u WHERE u.status = :criteria", User.class)
            .setParameter("criteria", criteria)
            .getResultList();
    }
}

1次キャッシュの動作とパフォーマンスへの影響

永続化コンテキストが保持する1次キャッシュ（First Level Cache）は、JPAのパフォーマンス最適化において中核的な役割を果たします。

1次キャッシュの動作原理

1次キャッシュは、エンティティの主キーをキーとして、エンティティインスタンスを値とするMapのような構造を持ちます。

flowchart LR
    subgraph FirstLevelCache["1次キャッシュ"]
        direction TB
        Entry1["ID: 1 → User#1"]
        Entry2["ID: 2 → User#2"]
        Entry3["ID: 3 → User#3"]
    end
    
    Find["find(User.class, 1)"] --> Check{"キャッシュに\n存在？"}
    Check -->|Yes| Return["キャッシュから返却"]
    Check -->|No| DB["DBクエリ実行"]
    DB --> Store["キャッシュに格納"]
    Store --> Return

1次キャッシュによるパフォーマンス向上

同一トランザクション内で同じエンティティを複数回取得する場合、1次キャッシュにより2回目以降のデータベースアクセスが不要になります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


@Service
@Transactional
public class OrderService {
    
    @PersistenceContext
    private EntityManager entityManager;
    
    public void processOrder(Long userId) {
        // 1回目: データベースからUser取得 → 1次キャッシュに格納
        User user1 = entityManager.find(User.class, userId);
        
        // 2回目: 1次キャッシュから取得（SQLは発行されない）
        User user2 = entityManager.find(User.class, userId);
        
        // 同一オブジェクトであることを確認
        System.out.println(user1 == user2); // true
    }
}

上記のコードを実行すると、Hibernateのログには1回のSELECT文のみが出力されます。

Hibernate: select u1_0.id,u1_0.email,u1_0.name from users u1_0 where u1_0.id=?

1次キャッシュの注意点

1次キャッシュはトランザクション単位でクリアされるため、以下の点に注意が必要です。

メモリ使用量: 大量のエンティティを読み込むバッチ処理では、定期的にentityManager.clear()でキャッシュをクリアすることを検討してください
データの鮮度: 他のトランザクションによる更新は1次キャッシュには反映されません。最新データが必要な場合はentityManager.refresh()を使用します

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@Transactional
public void batchProcess(List<Long> ids) {
    int batchSize = 100;
    
    for (int i = 0; i < ids.size(); i++) {
        User user = entityManager.find(User.class, ids.get(i));
        // 処理...
        
        // 100件ごとにキャッシュをクリアしてメモリを解放
        if (i > 0 && i % batchSize == 0) {
            entityManager.flush();
            entityManager.clear();
        }
    }
}

エンティティの4つの状態

JPAにおけるエンティティは、永続化コンテキストとの関係性に応じて4つの状態（ライフサイクルステート）を持ちます。この状態遷移を正しく理解することは、データの永続化とトラブルシューティングに不可欠です。

stateDiagram-v2
    [*] --> New: new Entity()
    New --> Managed: persist()
    Managed --> Removed: remove()
    Managed --> Detached: detach() / clear() / close()
    Removed --> Managed: persist()
    Removed --> [*]: flush() / commit()
    Detached --> Managed: merge()
    New --> [*]: （GC対象）
    
    note right of New
        永続化コンテキストに
        関連付けられていない
    end note
    
    note right of Managed
        永続化コンテキストで
        管理されている
    end note
    
    note right of Detached
        以前は管理されていたが
        現在は切り離されている
    end note
    
    note right of Removed
        削除対象として
        マークされている
    end note

New（新規）状態

newキーワードでインスタンス化されたばかりのエンティティは、New状態です。この状態のエンティティはまだ永続化コンテキストに関連付けられておらず、主キーも割り当てられていない場合があります。

1
2
3
4
5


// New状態のエンティティ
User user = new User();
user.setName("田中太郎");
user.setEmail("tanaka@example.com");
// この時点ではデータベースに保存されていない

期待される結果: New状態のエンティティに対する変更は、persist()を呼び出すまでデータベースに反映されません。

Managed（管理）状態

persist()メソッドの呼び出し、またはfind()やクエリによってデータベースから取得されたエンティティは、Managed状態になります。この状態のエンティティは永続化コンテキストによって監視され、変更が自動的に追跡されます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Transactional
public void createUser() {
    User user = new User();
    user.setName("田中太郎");
    
    // persist()でManaged状態に遷移
    entityManager.persist(user);
    
    // Managed状態なので、この変更は自動的にDBに反映される
    user.setName("田中次郎");
    
    // 明示的なsave()やupdate()は不要
}

期待される結果: トランザクションコミット時に、nameカラムが「田中次郎」でINSERTされます。

Detached（分離）状態

永続化コンテキストがクローズされた後、またはエンティティが明示的にdetach()された場合、Detached状態になります。この状態のエンティティへの変更はデータベースに反映されません。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@Transactional
public User getUser(Long id) {
    User user = entityManager.find(User.class, id);
    return user; // トランザクション終了後、userはDetached状態になる
}

public void updateDetachedUser(User detachedUser) {
    detachedUser.setName("新しい名前");
    // この変更はDBに反映されない！
}

Detached状態のエンティティを再び永続化コンテキストに関連付けるには、merge()を使用します。

1
2
3
4
5
6


@Transactional
public User updateUser(User detachedUser) {
    // merge()でManaged状態のコピーを取得
    User managedUser = entityManager.merge(detachedUser);
    return managedUser;
}

注意点: merge()は元のインスタンスをManaged状態にするのではなく、Managed状態の新しいインスタンスを返します。元のインスタンスへの変更は引き続きデータベースに反映されません。

Removed（削除）状態

remove()メソッドを呼び出すと、エンティティはRemoved状態になります。この状態のエンティティは、トランザクションコミット時にデータベースから削除されます。

1
2
3
4
5
6
7


@Transactional
public void deleteUser(Long id) {
    User user = entityManager.find(User.class, id);
    entityManager.remove(user);
    // user は Removed 状態
    // コミット時にDELETE文が発行される
}

重要: Detached状態のエンティティに対してremove()を呼び出すと、IllegalArgumentExceptionがスローされます。削除する前にmerge()で再アタッチするか、find()で取得し直す必要があります。

状態遷移の実践例

以下のコードは、エンティティの状態遷移を包括的に示しています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


@Service
public class EntityStateDemo {
    
    @PersistenceContext
    private EntityManager entityManager;
    
    @Transactional
    public void demonstrateLifecycle() {
        // 1. New状態
        User user = new User();
        user.setName("山田花子");
        System.out.println("Contains (New): " + entityManager.contains(user)); // false
        
        // 2. New → Managed（persist）
        entityManager.persist(user);
        System.out.println("Contains (Managed): " + entityManager.contains(user)); // true
        
        // 3. Managed状態での変更（ダーティチェック対象）
        user.setEmail("yamada@example.com");
        
        // 4. Managed → Detached（detach）
        entityManager.detach(user);
        System.out.println("Contains (Detached): " + entityManager.contains(user)); // false
        
        // 5. Detached → Managed（merge）
        User managedUser = entityManager.merge(user);
        System.out.println("Contains (Re-Managed): " + entityManager.contains(managedUser)); // true
        
        // 6. Managed → Removed（remove）
        entityManager.remove(managedUser);
        System.out.println("Contains (Removed): " + entityManager.contains(managedUser)); // false
    }
}

ダーティチェックと自動更新の仕組み

ダーティチェック（Dirty Checking）は、JPAの最も強力な機能の1つです。Managed状態のエンティティに対する変更を自動的に検出し、トランザクションコミット時に適切なUPDATE文を生成します。

ダーティチェックの動作原理

永続化コンテキストは、エンティティがManaged状態になった時点でその状態のスナップショット（コピー）を保持します。フラッシュ時に現在の状態とスナップショットを比較し、差分があればUPDATE文を生成します。

sequenceDiagram
    participant App as アプリケーション
    participant EM as EntityManager
    participant PC as 永続化コンテキスト
    participant DB as データベース
    
    App->>EM: find(User.class, 1)
    EM->>DB: SELECT * FROM users WHERE id = 1
    DB-->>EM: User データ
    EM->>PC: スナップショット保存
    EM-->>App: User エンティティ（Managed）
    
    App->>App: user.setName("新しい名前")
    
    Note over App,DB: トランザクションコミット時
    
    App->>EM: commit()
    EM->>PC: ダーティチェック実行
    PC->>PC: 現在の状態とスナップショットを比較
    PC-->>EM: 変更検出（name が異なる）
    EM->>DB: UPDATE users SET name = ? WHERE id = ?
    DB-->>EM: 更新完了

実践的なダーティチェックの例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


@Service
@Transactional
public class UserService {
    
    @PersistenceContext
    private EntityManager entityManager;
    
    public void updateUserEmail(Long userId, String newEmail) {
        // データベースからUser取得（Managed状態）
        User user = entityManager.find(User.class, userId);
        
        // 単にsetterを呼ぶだけでよい
        user.setEmail(newEmail);
        
        // save()やupdate()の明示的な呼び出しは不要
        // トランザクションコミット時に自動的にUPDATEが発行される
    }
}

実行されるSQL（Hibernateログ）:

Hibernate: select u1_0.id,u1_0.email,u1_0.name from users u1_0 where u1_0.id=?
Hibernate: update users set email=?,name=? where id=?

@DynamicUpdateによる最適化

デフォルトでは、Hibernateは全カラムを含むUPDATE文を生成します。変更されたカラムのみを更新したい場合は、@DynamicUpdateアノテーションを使用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@Entity
@Table(name = "users")
@DynamicUpdate
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String name;
    
    private String email;
    
    private String phone;
    
    // getter/setter省略
}

@DynamicUpdateを使用した場合、emailのみを変更すると:

Hibernate: update users set email=? where id=?

使用上の注意: @DynamicUpdateはUPDATE文の動的生成によるオーバーヘッドがあるため、カラム数が多いテーブルや頻繁に更新されるエンティティに対してのみ使用を検討してください。

フラッシュのタイミング

ダーティチェックとデータベースへの書き込み（フラッシュ）は、以下のタイミングで発生します。

トランザクションコミット時: デフォルトの動作
JPQLクエリ実行前: FlushModeType.AUTOの場合、クエリ対象テーブルへの保留中の変更がフラッシュされる
明示的なflush()呼び出し時: アプリケーションから強制的にフラッシュ

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Transactional
public void flushExample(Long userId) {
    User user = entityManager.find(User.class, userId);
    user.setName("更新後の名前");
    
    // この時点ではDBに反映されていない
    
    // 明示的にフラッシュ
    entityManager.flush();
    
    // この時点でDBに反映済み
}

よくある誤解とアンチパターン

永続化コンテキストとEntityManagerに関して、開発者がよく陥る誤解とアンチパターンを紹介します。

アンチパターン1: Detached状態でのsetterによる更新期待

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 間違った実装
@Service
public class UserService {
    
    @Autowired
    private UserRepository userRepository;
    
    public void updateUser(Long id, String newName) {
        User user = userRepository.findById(id).orElseThrow();
        // ここでトランザクションが終了している場合、userはDetached状態
        
        user.setName(newName);
        // この変更はDBに反映されない！
    }
}

正しい実装:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Service
public class UserService {
    
    @Autowired
    private UserRepository userRepository;
    
    @Transactional // トランザクションを追加
    public void updateUser(Long id, String newName) {
        User user = userRepository.findById(id).orElseThrow();
        user.setName(newName);
        // トランザクション内なのでダーティチェックが機能する
    }
}

アンチパターン2: 不要なsave()の呼び出し

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// 冗長な実装
@Service
@Transactional
public class UserService {
    
    @Autowired
    private UserRepository userRepository;
    
    public void updateUser(Long id, String newName) {
        User user = userRepository.findById(id).orElseThrow();
        user.setName(newName);
        userRepository.save(user); // 不要！ダーティチェックで自動更新される
    }
}

既にManaged状態のエンティティに対するsave()呼び出しは不要です。save()は内部でmerge()を呼び出すため、余計なオーバーヘッドが発生します。

アンチパターン3: 長時間オープンな永続化コンテキスト

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// 問題のある実装
@Service
public class UserService {
    
    @PersistenceContext
    private EntityManager entityManager;
    
    // 長時間のトランザクション
    @Transactional(timeout = 3600) // 1時間のタイムアウト
    public void longRunningProcess() {
        List<User> users = entityManager.createQuery(
            "SELECT u FROM User u", User.class).getResultList();
        
        for (User user : users) {
            // 外部APIへのHTTPリクエストなど、時間のかかる処理
            externalApiCall(user);
            user.setStatus("PROCESSED");
        }
        // 数千件のエンティティが1次キャッシュに蓄積される
    }
}

正しい実装:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


@Service
public class UserService {
    
    @PersistenceContext
    private EntityManager entityManager;
    
    @Transactional
    public void processInBatches() {
        int batchSize = 100;
        int offset = 0;
        List<User> batch;
        
        do {
            batch = entityManager.createQuery(
                "SELECT u FROM User u WHERE u.status = 'PENDING'", User.class)
                .setFirstResult(offset)
                .setMaxResults(batchSize)
                .getResultList();
            
            for (User user : batch) {
                externalApiCall(user);
                user.setStatus("PROCESSED");
            }
            
            entityManager.flush();
            entityManager.clear(); // メモリ解放
            
            offset += batchSize;
        } while (!batch.isEmpty());
    }
}

アンチパターン4: LazyInitializationException

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


// 問題のある実装
@Service
public class OrderService {
    
    @Autowired
    private OrderRepository orderRepository;
    
    public Order getOrder(Long id) {
        return orderRepository.findById(id).orElseThrow();
        // トランザクション終了、OrderはDetached状態
    }
}

@RestController
public class OrderController {
    
    @Autowired
    private OrderService orderService;
    
    @GetMapping("/orders/{id}")
    public OrderDto getOrder(@PathVariable Long id) {
        Order order = orderService.getOrder();
        // order.getItems()にアクセスするとLazyInitializationException
        return new OrderDto(order.getId(), order.getItems().size());
    }
}

解決策1: DTOへの変換をサービス層で行う

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Service
public class OrderService {
    
    @Autowired
    private OrderRepository orderRepository;
    
    @Transactional(readOnly = true)
    public OrderDto getOrderDto(Long id) {
        Order order = orderRepository.findById(id).orElseThrow();
        // トランザクション内でDTOに変換
        return new OrderDto(order.getId(), order.getItems().size());
    }
}

解決策2: @EntityGraphでJOIN FETCHする

1
2
3
4
5


public interface OrderRepository extends JpaRepository<Order, Long> {
    
    @EntityGraph(attributePaths = {"items"})
    Optional<Order> findWithItemsById(Long id);
}

まとめと実践Tips

本記事では、Spring JPAにおける永続化コンテキストの核心概念を解説しました。

重要なポイント

永続化コンテキストはエンティティの一時的なキャッシュ: 同一トランザクション内で同じエンティティへのアクセスを最適化します
4つのエンティティ状態を理解する: New、Managed、Detached、Removedの状態遷移を把握することで、データ永続化の問題を回避できます
ダーティチェックを活用する: Managed状態のエンティティは明示的なsave()なしに自動更新されます
トランザクション境界を意識する: @Transactionalの有無によってエンティティの状態が変わり、ダーティチェックの動作が異なります

実践Tips

シナリオ	推奨アプローチ
単純なCRUD操作	Spring Data JPAの`JpaRepository`を使用
更新処理	`@Transactional`内でエンティティを取得・変更、明示的な`save()`は不要
大量データ処理	バッチサイズを設定し、定期的に`flush()`と`clear()`を呼び出す
読み取り専用操作	`@Transactional(readOnly = true)`を使用してパフォーマンスを向上
遅延読み込み対策	`@EntityGraph`またはJPQLのJOIN FETCHを使用

永続化コンテキストを正しく理解し活用することで、より効率的で保守性の高いJPAアプリケーションを構築できます。

実行環境と前提条件#

永続化コンテキストとは#

永続化コンテキストの主な役割#

EntityManagerのライフサイクルとスコープ#

コンテナ管理EntityManager（推奨）#

アプリケーション管理EntityManager#

Spring Data JPAにおけるEntityManager#

1次キャッシュの動作とパフォーマンスへの影響#

1次キャッシュの動作原理#

1次キャッシュによるパフォーマンス向上#

1次キャッシュの注意点#

エンティティの4つの状態#

New（新規）状態#

Managed（管理）状態#

Detached（分離）状態#

Removed（削除）状態#

状態遷移の実践例#

ダーティチェックと自動更新の仕組み#

ダーティチェックの動作原理#

実践的なダーティチェックの例#

@DynamicUpdateによる最適化#

フラッシュのタイミング#

よくある誤解とアンチパターン#

アンチパターン1: Detached状態でのsetterによる更新期待#

アンチパターン2: 不要なsave()の呼び出し#

アンチパターン3: 長時間オープンな永続化コンテキスト#

アンチパターン4: LazyInitializationException#

まとめと実践Tips#

重要なポイント#

実践Tips#

参考リンク#