Sự Kiện Vòng Đời Thực Thể trong Spring Data JPA: Những ‘Hooks’ Bạn Cần Nắm Vững | Java Spring Roadmap

Bạn gọi repository.save(order) nhưng log chưa hề có câu UPDATE. Rồi bạn sửa một field, không gọi save, và cuối transaction dữ liệu trong DB vẫn đổi. Cả hai đều đúng: quyết định là persistence context và thời điểm flush, không phải method bạn gọi. Hiểu vòng đời thực thể trong Spring Data JPA giúp bạn đặt logic ở đúng callback thay vì vá lỗi ở tầng service.

Cập nhật 2026

  • Nền tảng hiện tại là Jakarta Persistence 3.2, Hibernate ORM 7.4.15.Final, Spring Data JPA 4.1.2 (train 2026.0.2) trên Spring Boot 4.1.2.
  • Toàn bộ annotation và API nằm trong jakarta.persistence; javax.persistence không còn được hỗ trợ.
  • save, saveAndFlush, AuditingEntityListener giữ nguyên hợp đồng; không có API mới thay thế callback trong 4.1.2.
  • Hibernate 8.0.0.Beta4 vẫn là bản development; production 2026 nằm ở nhánh 7.4.

Bốn trạng thái trong vòng đời thực thể

Persistence context là một identity map: khóa là cặp (loại entity, id), giá trị là instance đang được theo dõi. Mọi thứ còn lại — dirty checking, callback, flush — đều bắt đầu từ việc instance có nằm trong map đó hay không.

Trạng thái Dấu hiệu Ai quyết định
Transient / new Tạo bằng new, chưa có id hoặc id do bạn gán, contains trả false, chưa có row Bạn, cho tới lần persist hoặc merge
Managed Nằm trong context, contains trả true, mọi thay đổi field được theo dõi persist, find, merge, hoặc kết quả query
Detached Từng managed nhưng context đã detach/clear/close; sửa field không ai ghi nhận Đóng transaction, detach, serialize qua network
Removed Đã gọi remove, vẫn còn trong context tới khi flush; row chưa mất remove, rồi flush mới sinh DELETE

Hai lần findById(42) trong cùng transaction trả về cùng một instance. Vì vậy đừng coi entity là DTO: nó là object chia sẻ trong context, và thay đổi trên đó có thể lọt xuống DB ngoài ý muốn.

EntityManager: từng method thực sự làm gì

Method Việc thật sự làm Cạm bẫy
persist New thành managed; INSERT được lên lịch, chạy ngay với IDENTITY, chạy ở flush với sequence/table Gọi trên detached không làm nó managed; đừng dùng thay merge
find Trả instance managed hoặc null; ưu tiên first-level cache trước khi query Không khóa row; cần khóa thì truyền LockModeType
merge Copy state sang instance managed cùng id (load nếu chưa có), trả instance đó Input vẫn detached; instance trả về là object khác
remove Managed thành removed; DELETE ở flush Gọi trên detached hoặc transient ném IllegalArgumentException
flush Đẩy toàn bộ SQL còn chờ xuống DB Không commit; rollback vẫn xảy ra sau đó
detach / clear Bỏ một instance hoặc toàn bộ khỏi context Sau đó dirty checking không còn; lazy load có thể lỗi
contains Kiểm tra instance có trong context hay không Không cho biết row đã tồn tại; chỉ nói về membership
// File: src/main/java/com/evotek/catalog/CatalogService.java
// imports: jakarta.persistence.*, org.springframework.stereotype.Service, org.springframework.transaction.annotation.Transactional
@Service
class CatalogService {

    @PersistenceContext
    private EntityManager em;

    @Transactional
    void walkThroughStates() {
        Product p = new Product("Bàn phím");   // transient
        em.persist(p);                          // managed
        boolean inContext = em.contains(p);     // true

        em.flush();                             // INSERT thật sự
        em.detach(p);                           // detached
        p.setName("Bàn phím mới");              // không được theo dõi

        Product managed = em.merge(p);          // SELECT + copy state, trả instance khác
        em.remove(managed);                     // removed
        em.flush();                             // DELETE
    }
}

Với IDENTITY, INSERT đã chạy trong persist; với sequence, nó mới chạy ở flush. Đừng suy ra thời điểm INSERT từ việc bạn có gọi flush.

save không phải persist: nhánh isNew và merge

SimpleJpaRepository.save có đúng hai nhánh: nếu isNew(entity) thì em.persist(entity), ngược lại em.merge(entity). Với entity dùng id sinh tự động, isNew là “id còn null“. Với entity có @Version kiểu wrapper, isNew là “version còn null“.

Hệ quả thực tế: nếu bạn gán id trong code, hoặc dùng UUID tự sinh, mọi lần save đều đi nhánh merge. Hibernate phải SELECT trước để lấy instance managed, rồi mới UPDATE. Muốn tránh, implement Persistable<ID> và trả true từ isNew() cho entity mới, hoặc để id sinh tự động.

Product incoming = new Product();
incoming.setId(42L);
incoming.setName("Màn hình");

Product saved = catalog.save(incoming);   // isNew=false → merge
// incoming vẫn detached; saved là instance managed khác object
saved.setName("Màn hình 27 inch");         // thay đổi này mới được flush

merge trả về một instance khác. Bỏ qua giá trị trả về là lỗi phổ biến: bạn sửa incoming, nhưng Hibernate chỉ theo dõi saved. Luôn viết Product saved = repository.save(incoming) và dùng saved từ đó về sau.

Callback chạy ở đâu trong timeline

Callback Thời điểm Được phép làm gì
@PrePersist Trước INSERT, entity đã managed Set default, normalize, kiểm tra invariant; id có thể còn null
@PostPersist Sau INSERT; id đã có Chỉ đọc state; không gọi EntityManager/Query
@PreUpdate Trước UPDATE, trong flush Cập nhật timestamp, validate; sửa field có kiểm soát
@PostUpdate Sau UPDATE Chỉ đọc state
@PreRemove Trước DELETE Kiểm tra điều kiện xóa, ghi log
@PostRemove Sau DELETE Chỉ đọc state
@PostLoad Sau SELECT hoặc refresh, trước khi trả về Tính field transient từ state đã load

Thứ tự theo thời điểm là cố định: Pre* trước SQL, Post* sau SQL. Nhưng @PreUpdate/@PostUpdate chỉ chạy khi flush — không chạy lúc gọi save hay lúc sửa field. Còn @PrePersist chạy ngay trong persist, @PostPersist sau INSERT. Đừng giả định thứ tự giữa nhiều listener cùng loại.

Không gọi EntityManager hay Query trong callback. Đặc biệt trong @PostPersist: INSERT đã xảy ra nhưng transaction chưa commit, context đang ở giữa vòng flush. JPA quy định việc gọi EntityManager/Query trong lifecycle callback là không hợp lệ; Hibernate có thể không ném lỗi ngay, nhưng hành vi không xác định. Việc cần ghi thêm dữ liệu hãy đưa ra service hoặc event sau commit.

Auditing: cách đúng để điền ngày tạo/ngày sửa

Đừng tự viết @PrePersist để set createdAt nếu bạn chỉ cần audit. Spring Data JPA có AuditingEntityListener và bộ annotation @CreatedDate/@LastModifiedDate; bật bằng @EnableJpaAuditing. Listener này xử lý đúng cả create và update, kể cả khi entity được sửa bởi dirty checking mà không qua save.

// File: src/main/java/com/evotek/catalog/config/AuditingConfig.java
// imports: java.time.*, java.util.Optional, org.springframework.context.annotation.*
//          org.springframework.data.auditing.DateTimeProvider
@Configuration
@EnableJpaAuditing(dateTimeProviderRef = "auditingDateTimeProvider")
class AuditingConfig {

    @Bean
    DateTimeProvider auditingDateTimeProvider(Clock clock) {
        return () -> Optional.of(Instant.now(clock));
    }

    @Bean
    Clock clock() {
        return Clock.systemUTC();
    }
}
// File: src/main/java/com/evotek/sales/Order.java
// imports: jakarta.persistence.*, java.time.Instant
//          org.springframework.data.annotation.CreatedDate
//          org.springframework.data.annotation.LastModifiedDate
//          org.springframework.data.jpa.domain.support.AuditingEntityListener
@Entity
@Table(name = "orders")
@EntityListeners(AuditingEntityListener.class)
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @CreatedDate
    @Column(nullable = false, updatable = false)
    private Instant createdAt;

    @LastModifiedDate
    @Column(nullable = false)
    private Instant updatedAt;

    @Version
    private Long version;

    @Column(nullable = false, length = 40)
    private String sku;

    protected Order() { }

    public Order(String sku) { this.sku = sku; }

    void rename(String sku) { this.sku = sku; }

    // getters
}
// File: src/main/java/com/evotek/sales/OrderService.java
// imports: org.springframework.data.jpa.repository.JpaRepository
//          org.springframework.stereotype.Service, org.springframework.transaction.annotation.Transactional
interface OrderRepository extends JpaRepository<Order, Long> { }

@Service
class OrderService {

    private final OrderRepository orders;

    OrderService(OrderRepository orders) { this.orders = orders; }

    @Transactional
    public Order place(String sku) {
        Order order = orders.save(new Order(sku));
        // IDENTITY: INSERT chạy ngay; createdAt/updatedAt đã được listener điền
        return order;
    }

    @Transactional
    public Order rename(Long id, String sku) {
        Order order = orders.findById(id).orElseThrow();
        order.rename(sku);     // managed: không cần save
        orders.flush();        // @PreUpdate + @LastModifiedDate chạy ở đây
        return order;
    }
}

Hai chi tiết dễ sai. @CreatedDate chỉ điền khi field còn null, nên đừng set trong constructor. @LastModifiedDate được điền cả lần tạo đầu tiên; muốn nó chỉ đổi khi thật sự sửa thì chấp nhận giá trị bằng createdAt ở lần đầu. modifyOnCreation = false sẽ để updatedAt null, nên chỉ dùng khi cột cho phép null. Cần thêm người thao tác thì dùng @CreatedBy/@LastModifiedBy cùng bean AuditorAware<String>.

Nếu schema đã có default ở DB, có thể bỏ auditing phía Java: cột created_at timestamp not null default CURRENT_TIMESTAMP, map với @Column(insertable = false, updatable = false). Cách này đúng cho mọi client nhưng mất kiểm soát timestamp trong test và kém portable khi đổi database. Với Hibernate, @CreationTimestamp/@UpdateTimestamp là phương án thay thế nhưng gắn với provider, không phải chuẩn Jakarta Persistence.

Dirty checking và thời điểm flush

Khi entity thành managed, Hibernate giữ một snapshot state. Ở flush, nó so từng field với snapshot; field nào khác thì sinh UPDATE. Mặc định UPDATE chứa toàn bộ cột updatable, không chỉ cột đổi — bật @DynamicUpdate (Hibernate) nếu bảng rộng và bạn cập nhật lẻ tẻ.

Flush xảy ra ở bốn nơi: trước khi commit; trước một query JPQL/Criteria chạm bảng liên quan (FlushModeType.AUTO, mặc định); khi bạn gọi flush/saveAndFlush; và khi provider cần id cho một thao tác sau đó. saveAndFlush chỉ là save + em.flush(), không commit. Dùng nó khi bạn cần id hoặc muốn vi phạm constraint nổi lên sớm, đừng dùng như “nút lưu”.

@Transactional là biên của persistence context: context sống từ lúc mở transaction tới lúc commit/rollback, sau đó entity detached. Đó là lý do lazy association ném LazyInitializationException ngoài transaction. @Transactional(readOnly = true) chuyển flush mode sang MANUAL; ghi trong method read-only bị bỏ im lặng, không có UPDATE và không có callback. Bài giao dịch trong Spring đi sâu phần này.

Sáu pitfall tốn nhiều giờ debug

1. Làm I/O trong callback

Gửi email, gọi HTTP, publish Kafka trong @PostPersist là sai cả về hiệu năng lẫn tính đúng. Callback chạy trong lúc flush, đang giữ DB connection và transaction; nếu transaction rollback sau đó, email đã bay và message đã đi. Chuyển sang service: publish một event rồi xử lý bằng @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT).

2. @PostLoad chạm association lazy

@PostLoad chạy ngay sau khi entity được load. Nếu method đọc order.getLines() và collection đang lazy, Hibernate phát thêm một câu query cho mỗi entity — N+1 đúng nghĩa, có khi nổ to hơn mọi vòng lặp ở service. Tệ hơn, trong callback bạn không kiểm soát được fetch context. Chỉ tính từ field đã load; cần association thì dùng join fetch hoặc @EntityGraph ở query, như bài quan hệ JPA đã bàn.

3. Merge cả graph detached

merge trên aggregate lớn cascading MERGE sẽ load từng entity con, so sánh rồi copy — một graph 500 dòng thành hàng trăm SELECT. Nguy hiểm hơn là dữ liệu: state detached cũ ghi đè thay đổi mới hơn ở field client không gửi, kể cả null. Cách đúng là load entity trong transaction rồi gọi method nghiệp vụ, hoặc patch bằng DTO.

4. equals/hashCode dựa trên id sinh tự động

Entity mới có id = null, sau persist thành 42. Nếu hashCode tính từ id, bỏ entity vào HashSet trước khi save rồi tìm lại sau khi save sẽ không thấy. Dùng business key bất biến, hoặc UUID gán trong constructor; nếu buộc dùng id, chỉ dùng cho entity đã detached và so sánh cùng loại. Đừng gọi getId() trên proxy Hibernate trong equals — nó có thể trigger load.

5. Tin vào id trước flush

Trong @PrePersist với IDENTITY, id còn null vì Hibernate phải INSERT mới lấy được id. Với sequence, id có thể đã được cấp trước INSERT. Đừng dùng id trong @PrePersist để tạo business key, số hóa đơn hay mã vận đơn. Dùng UUID, hoặc chuyển logic sang @PostPersist — lúc đó id đã tồn tại, nhưng vẫn chưa commit.

6. @Version và optimistic locking

@Version tăng mỗi lần UPDATE và là cách chặn lost update. OptimisticLockException thường ném ở flush/commit, không phải lúc gọi merge; merge graph detached mang version cũ sẽ thất bại, nhưng chỉ sau khi đã copy state. Với @Version kiểu Long, entity có version khác null bị isNew coi là cũ, nên đừng set version thủ công khi tạo mới. Bulk update qua @Modifying không bump version và không chạy callback.

Đặt logic ở đâu

Nhu cầu Đặt ở đâu Lý do
Ngày tạo/ngày sửa, người thao tác @CreatedDate/@LastModifiedDate + AuditingEntityListener Chuẩn, chạy cho mọi đường ghi JPA, dễ inject Clock khi test
Chuẩn hóa field, default, invariant @PrePersist/@PreUpdate Gần entity, không phụ thuộc service nào gọi
Email, HTTP, message, thông báo Service + @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT) Chỉ chạy khi dữ liệu đã commit; retry được
Ràng buộc cuối cùng Constraint/default ở DB Không phụ thuộc application, đúng cho mọi client

Nhìn về 2027

Hibernate 8 vẫn beta, nên 2027 mới là lúc cân nhắc nâng major; Jakarta Persistence 3.2 và bộ callback hiện tại còn nguyên trong Spring Boot 4.x. Đáng theo dõi nhất là kiểm thử: inject Clock vào auditing và dùng Testcontainers thay database nhúng.

Checklist

  • Dùng Product saved = repository.save(incoming) và bỏ biến incoming sau đó.
  • Không gọi EntityManager, query, HTTP hay email trong bất kỳ callback nào.
  • Auditing bằng @EnableJpaAuditing + AuditingEntityListener, không tự viết @PrePersist set ngày.
  • Rà @PostLoad và mọi equals/hashCode dùng id sinh tự động.
  • Biết rõ entity của bạn đi nhánh persist hay merge; id gán tay thì kiểm tra isNew.
  • Side effect chỉ chạy sau commit, qua event hoặc outbox — không qua @PostPersist.

Để nối lại mạch kiến thức: bài Hibernate Basics giải thích mapping và id, bài Spring Data JPA repository giải thích save/deleteById. Đọc xong hai bài đó, bạn có đủ mental model để đoán callback nào sẽ chạy trước khi nhìn log.