Cách khắc phục org.hibernate.PersistentObjectException: detached entity passed to persist trong Spring Data JPA

Thông báo lỗi

Lỗi này thường xảy ra vào lúc bạn ít ngờ tới nhất. Bạn gọi một phương thức save, và console của bạn bùng nổ với một stack trace như sau:

org.hibernate.PersistentObjectException: detached entity passed to persist
    at org.hibernate.event.internal.DefaultPersistEventListener.onPersist(DefaultPersistEventListener.java:124)
    at org.hibernate.internal.SessionImpl.firePersist(SessionImpl.java:775)
    at org.hibernate.internal.SessionImpl.persist(SessionImpl.java:754)

Tại sao Hibernate lại báo lỗi

Lỗi này là cách Hibernate thông báo: "Bạn yêu cầu tôi tạo một bản ghi mới hoàn toàn, nhưng đối tượng này đã có một ID thuộc về một bản ghi hiện có." Hibernate theo dõi các entity bằng một state machine. Để khắc phục điều này, bạn cần biết đối tượng của mình đang ở trạng thái nào.

- **Transient:** Một đối tượng mới. Nó không có ID và Hibernate chưa biết đến sự tồn tại của nó.
- **Persistent:** Một đối tượng gắn liền với database session hiện tại. Hibernate theo dõi mọi thay đổi mà bạn thực hiện trên đó.
- **Detached:** Một đối tượng đã có ID (ví dụ `id=101`) nhưng không còn liên kết với một session đang hoạt động.

Phương thức persist() rất "kén chọn". Nó chỉ chấp nhận các transient entities. Nếu bạn truyền vào một detached entity—một đối tượng đã có primary key—Hibernate sẽ báo lỗi vì nó không biết nên cập nhật bản ghi cũ hay bỏ qua ID đó.

Các tình huống thường gặp và cách khắc phục

1. Bẫy đặt ID thủ công

Bạn có đang thiết lập ID thủ công cho một đối tượng mới không? Nếu bạn gán entity.setId(500L) rồi gọi repository.save(), Hibernate sẽ thấy ID đó và giả định rằng bản ghi đã tồn tại. Khi nó cố gắng thực hiện thao tác persist trên thứ mà nó nghĩ là một bản ghi mới, sự xung đột này sẽ kích hoạt exception.

Cách khắc phục: Hãy để cơ sở dữ liệu xử lý các công việc nặng nhọc. Sử dụng @GeneratedValue và không chạm vào trường ID cho các bản ghi mới. Nếu bạn bắt buộc phải sử dụng ID thủ công, hãy đảm bảo entity của bạn implement Persistable để bạn có thể báo cho Spring Data JPA biết một cách rõ ràng liệu đối tượng đó có thực sự mới hay không.

2. Cạm bẫy Cascade (Nguyên nhân hàng đầu)

Hầu hết các lập trình viên đều gặp phải lỗi này trong các thao tác Parent-Child. Hãy tưởng tượng bạn lấy một Category hiện có (ID: 5) từ cơ sở dữ liệu và gắn nó vào một Product mới tinh. Nếu mapping của bạn trông như thế này:

@ManyToOne(cascade = CascadeType.PERSIST)
private Category category;

Khi bạn lưu Product, Hibernate cũng cố gắng persist cả Category. Nhưng vì Category đã có ID là 5, thao tác PERSIST thất bại. Nó thấy một detached entity trong khi nó mong đợi một entity mới.

Cách khắc phục: Cập nhật cascade logic của bạn. Sử dụng MERGE hoặc ALL để Hibernate biết cách xử lý các bản ghi hiện có.

// Thay vì chỉ dùng PERSIST, hãy dùng cả hai:
@ManyToOne(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
private Category category;

3. Xử lý dữ liệu JSON từ REST APIs

Khi một ứng dụng di động hoặc frontend gửi một đối tượng JSON có chứa ID, Hibernate sẽ coi đó là detached. Nếu service layer của bạn cố gắng lưu đối tượng này trực tiếp bằng entityManager.persist(), nó sẽ luôn thất bại.

Cách khắc phục: Sử dụng repository.save(). Phương thức này của Spring Data JPA rất thông minh. Nó kiểm tra xem ID có tồn tại không; nếu có, nó sẽ gọi merge(). Nếu ID là null, nó gọi persist(). Nếu bạn đang làm việc trực tiếp với EntityManager, hãy luôn ưu tiên em.merge(entity) cho các đối tượng đến từ bên ngoài hệ thống.

4. Sequence của cơ sở dữ liệu bị lệch

Đôi khi mã nguồn vẫn ổn, nhưng dữ liệu lại lộn xộn. Nếu PostgreSQL sequence của bạn bắt đầu từ 1, nhưng bạn đã chèn thủ công 100 hàng, Hibernate có thể cố gắng tạo ra ID là 1. Vì ID 1 đã tồn tại trong bảng, persistence context sẽ bị bối rối.

Cách khắc phục: Đồng bộ hóa các sequence của bạn. Chạy một câu lệnh SQL như SELECT setval('your_sequence_name', (SELECT max(id) FROM your_table)); để đảm bảo Hibernate tạo ra các ID chưa được sử dụng.

Kiểm tra cách khắc phục

Đừng đoán—hãy xác minh. Bạn có thể viết một integration test nhanh để mô phỏng việc lưu một đối tượng cha mới với một đối tượng con đã tồn tại. Điều này đảm bảo các thiết lập CascadeType của bạn thực sự hoạt động.

@SpringBootTest
class SaveOperationTest {
    @Autowired private ProductRepository productRepo;
    @Autowired private CategoryRepository categoryRepo;

    @Test
    void shouldSaveProductWithExistingCategory() {
        Category existing = categoryRepo.save(new Category("Electronics"));
        
        Product laptop = new Product("MacBook");
        laptop.setCategory(existing);

        // Điều này sẽ ném ra PersistentObjectException nếu cascade chỉ là PERSIST
        assertDoesNotThrow(() -> productRepo.save(laptop));
    }
}

Các thực hành tốt nhất để Persistence sạch sẽ

- **Gắn bó với Repository:** Tránh trộn lẫn `EntityManager` và `JpaRepository` trong cùng một service. Repository tự động xử lý logic giữa `persist` và `merge`.
- **Kiểm tra các Cascade:** `CascadeType.ALL` rất tiện lợi nhưng nguy hiểm. Hãy sử dụng các loại cụ thể như `{PERSIST, MERGE}` để tránh việc xóa nhầm hoặc xung đột trạng thái.
- **Sử dụng DTOs:** Đừng bao giờ truyền trực tiếp các Entity thuần túy sang frontend. Hãy map DTO của bạn sang một Entity mới được lấy từ cơ sở dữ liệu để giữ cho Hibernate session luôn sạch sẽ.