Entity đầu tiên thường chạy được trong mười phút, rồi âm thầm sai trong mười tháng. Lỗi hiếm khi đến từ thiếu annotation, mà từ những gì Hibernate làm sau lưng bạn: persistence context, dirty checking và chiến lược khóa chính.
Hibernate trong Spring Boot là tầng ORM mặc định của Spring Data JPA. Bài này ánh xạ entity đầu tiên vào một bảng, kèm repository và test chạy được, trên Hibernate ORM 7.4.15.Final, Spring Boot 4.1.2, Spring Data JPA 4.1.2 và Java 25 LTS. Nếu mới vào series, đọc lộ trình Spring Boot trước.
Mục lục
Cập nhật 2026
- Hibernate 7.4.15.Final là bản stable (2026-11-06). Hibernate 8.0.0.Beta4 chỉ là bản phát triển; đừng đưa vào production.
- Jakarta Persistence 3.2 (Jakarta EE 11): import
jakarta.persistence.*. Codejavax.persistencekhông còn compile. - Spring Boot 4.1.2 cần Java 17+ và chạy tốt trên Java 25 LTS; Spring Data JPA 4.1.2 đi cùng Framework 7.0.10.
- Schema vẫn là việc của migration:
ddl-autochỉ cho dev/test, production dùngvalidatehoặcnone.
Hibernate làm gì: ORM và persistence context
Hibernate là ORM: ánh xạ class sang bảng, field sang cột, sinh SQL từ thao tác trên object. Nhưng phần quyết định hành vi là persistence context.
Persistence context và first-level cache
Mỗi EntityManager giữ một persistence context. Trong đó, mỗi bản ghi có đúng một object, định danh bằng khóa chính. Gọi find(Product.class, 1L) hai lần trong cùng transaction trả về cùng instance và chỉ một SELECT: đó là first-level cache. Cache sống theo transaction, không theo request hay JVM; transaction đóng thì entity detached và cache mất.
Dirty checking
Khi load, Hibernate giữ snapshot. Lúc flush — trước commit hoặc trước query cần dữ liệu mới — nó so sánh và sinh UPDATE cho field đã đổi. Trong transaction, entity managed không cần save(). Ngược lại, sửa field trên object detached ở transaction khác thì không có gì được ghi. Biết biên transaction quan trọng hơn tin vào cảm giác “setter là lưu”.
Entity đầu tiên: Product
Entity dưới đây dùng field access: annotation trên field, Hibernate đọc/ghi trực tiếp, không bắt buộc getter. Constructor không đối số là bắt buộc, để protected.
// File: src/main/java/com/example/shop/catalog/Product.java
package com.example.shop.catalog;
import java.math.BigDecimal;
import java.time.Instant;
import java.util.Objects;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.EnumType;
import jakarta.persistence.Enumerated;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Index;
import jakarta.persistence.Table;
import jakarta.persistence.Version;
@Entity
@Table(name = "products", indexes = {
@Index(name = "idx_products_sku", columnList = "sku", unique = true),
@Index(name = "idx_products_status_created", columnList = "status, created_at")
})
public class Product {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, length = 64)
private String sku;
@Column(nullable = false, length = 200)
private String name;
@Column(nullable = false, precision = 12, scale = 2)
private BigDecimal price;
@Enumerated(EnumType.STRING)
@Column(nullable = false, length = 20)
private ProductStatus status = ProductStatus.DRAFT;
@Column(nullable = false, updatable = false)
private Instant createdAt;
@Version
private long version;
protected Product() {
// bat buoc cho JPA; khong goi truc tiep
}
public Product(String sku, String name, BigDecimal price) {
this.sku = sku;
this.name = name;
this.price = price;
this.createdAt = Instant.now();
}
public Long getId() { return id; }
public String getSku() { return sku; }
@Override
public boolean equals(Object other) {
if (this == other) return true;
if (!(other instanceof Product product)) return false;
return Objects.equals(sku, product.sku); // business key bat bien
}
@Override
public int hashCode() {
return Objects.hash(sku);
}
}
@Entity biến class thành entity được quản lý. Lớp phải không final và là top-level class. @Id đánh dấu khóa chính, @GeneratedValue chọn cách sinh. @Table(name = "products") chỉ định bảng; không có nó, tên bảng lấy từ class qua naming strategy, không tự thêm “s”.
ProductStatus là enum riêng, lưu bằng tên hằng số nhờ EnumType.STRING:
// File: src/main/java/com/example/shop/catalog/ProductStatus.java
package com.example.shop.catalog;
public enum ProductStatus {
DRAFT, ACTIVE, ARCHIVED
}
Khóa chính: IDENTITY, SEQUENCE hay UUID
Ba chiến lược phổ biến không tương đương về hiệu năng và vận hành; chọn theo database và tải ghi.
| Chiến lược | Cơ chế | Dùng khi |
|---|---|---|
IDENTITY |
Database tự tăng; phải INSERT rồi mới có id. |
MySQL, SQL Server; không batch insert. |
SEQUENCE |
Lấy số từ sequence trước INSERT; batch được. |
PostgreSQL, Oracle; tải ghi cao. |
UUID |
Sinh UUID, không round-trip database. | Id phân tán, sinh ở client. |
IDENTITY phổ biến ở MySQL nhưng có giá: id chỉ biết sau INSERT, nên Hibernate không gộp được nhiều insert thành JDBC batch. Với luồng ghi dày, đó là chênh lệch thật.
// SEQUENCE: id duoc cap truoc khi INSERT, batch insert van chay
@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "product_seq")
@SequenceGenerator(name = "product_seq", sequenceName = "product_seq",
allocationSize = 50)
private Long id;
// UUID: id khong phu thuoc database, hop voi he phan tan
@Id
@GeneratedValue(strategy = GenerationType.UUID)
private UUID id;
Với SEQUENCE, allocationSize phải khớp sequence trong database, nếu không hai bên cấp số lệch. Với UUID, v4 ngẫu nhiên làm phân mảnh B-tree index; bảng lớn nên dùng UUID có thứ tự thời gian do Hibernate hoặc database sinh, và kiểm tra tài liệu phiên bản trước khi chọn generator. AUTO tiện cho prototype, production nên chỉ định rõ.
@Column, @Version, @Enumerated và kiểu thời gian
@Column điều chỉnh ánh xạ cột: nullable = false, length cho chuỗi, precision/scale cho số thập phân. nullable = false chủ yếu là gợi ý cho DDL, không phải validation runtime; chặn null ở tầng ứng dụng bằng Bean Validation (@NotNull, @NotBlank).
@Version bật optimistic locking. Hibernate tăng giá trị mỗi lần update và thêm điều kiện version vào UPDATE. Hai transaction sửa cùng bản ghi thì transaction sau nhận OptimisticLockException thay vì ghi đè âm thầm. Đặt nó trên aggregate root có khả năng bị sửa đồng thời, đừng đặt tràn lan.
@Enumerated mặc định là ORDINAL — lưu số thứ tự enum. Thêm một hằng số vào giữa danh sách là dữ liệu cũ lệch nghĩa. Luôn dùng EnumType.STRING với length đủ lớn; tên hằng số là hợp đồng dữ liệu.
@Temporal chỉ áp dụng cho java.util.Date và Calendar. Với Java hiện tại, dùng thẳng java.time: Instant cho timestamp UTC, LocalDate cho ngày, OffsetDateTime khi cần offset. Đừng đặt @Temporal lên Instant hay LocalDateTime; nó không có tác dụng.
Constructor, entity hay record, và equals/hashCode
JPA cần constructor không đối số để tạo instance khi hydrate từ ResultSet; protected tốt hơn public vì API không mở đường tạo object rỗng. Class cũng không được final vì Hibernate cần subclass cho proxy và enhancement.
Record là final, bất biến, không có constructor không đối số, nên không thể là entity. Record hợp làm DTO hoặc projection, nhưng đừng gắn @Entity lên nó. Entity là object có vòng đời do Hibernate quản lý, không phải value object.
equals/hashCode là chỗ dễ tạo bug nhất. Ba quy tắc:
- Không dùng id tự sinh. Trước persist id là
null, sau persist thành số; object trongHashSethoặc làm keyHashMapsẽ “mất tích” vì hashCode đổi. - Dùng business key bất biến.
sku,isbn, email đã chuẩn hóa, hoặc UUID gán trong constructor; key phải unique và không đổi. - hashCode phải ổn định. Chỉ tính từ field bất biến; đừng đưa collection lazy hoặc field có setter vào.
Dùng instanceof thay vì getClass() để không vỡ với proxy của Hibernate. Nếu entity không có business key tự nhiên, thêm khóa UUID bất biến thay vì lấy id làm equals.
Naming strategy: createdAt thành created_at
Spring Boot đặt physical naming strategy mặc định là CamelCaseToUnderscoresNamingStrategy. Field createdAt thành cột created_at. Tên bảng cũng đi qua strategy này và không được pluralize tự động: class Product thành bảng product, không phải products.
Nếu schema dùng số nhiều, đặt @Table(name = "products") như ví dụ trên. Khi đã chỉ định tên, viết đúng dạng bạn muốn để kết quả không phụ thuộc strategy. JPQL vẫn dùng tên property (p.createdAt); chỉ native query mới dùng created_at.
DDL: ddl-auto và chuyện schema production
spring.jpa.hibernate.ddl-auto quyết định Hibernate làm gì với schema lúc khởi động. Các giá trị hợp lệ gồm none, validate, update, create, create-drop.
| Giá trị | Hành vi | Dùng ở đâu |
|---|---|---|
none |
Không kiểm tra, không đổi schema. | Production có migration riêng. |
validate |
Kiểm tra schema khớp entity, fail fast. | Staging và production. |
update |
Thêm bảng/cột còn thiếu, không xóa. | Chỉ dev; không bao giờ production. |
create-drop |
Tạo schema rồi xóa khi dừng. | Test và H2 in-memory. |
Với database nhúng, Boot mặc định create-drop; với database thật, mặc định là none. Đừng dựa vào mặc định: khai báo rõ theo profile. Cấu hình dev tối thiểu:
# File: src/main/resources/application-dev.yml
spring:
datasource:
url: jdbc:h2:mem:shop;DB_CLOSE_DELAY=-1
username: sa
password:
jpa:
hibernate:
ddl-auto: create-drop
open-in-view: false
properties:
hibernate:
format_sql: true
Production không dùng update: nó không xóa cột thừa, không xử lý rename đúng, không rollback, và mỗi môi trường có thể ra schema khác. Schema phải là artefact có version:
# File: src/main/resources/application-prod.yml
spring:
jpa:
hibernate:
ddl-auto: validate
open-in-view: false
flyway:
enabled: true
locations: classpath:db/migration
Flyway chạy migration trước khi EntityManagerFactory được tạo, nên validate nhìn thấy schema đã migrate. Liquibase cũng dùng được; chọn một công cụ và giữ migration trong repo. Nếu team có quy trình DDL riêng, đặt none và kiểm tra bằng pipeline.
Repository và test chạy được
Repository chỉ là interface kế thừa JpaRepository; Spring Data tạo proxy lúc khởi động, nên không cần @Repository và không cần implementation.
// File: src/main/java/com/example/shop/catalog/ProductRepository.java
package com.example.shop.catalog;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
public interface ProductRepository extends JpaRepository<Product, Long> {
Optional<Product> findBySku(String sku);
}
save() gọi persist khi id còn null và merge khi id đã có. Với entity đã managed, không cần save() để cập nhật; dirty checking lo việc đó. Cách dùng repository trong service ở bài Spring Data JPA cho người mới bắt đầu.
@DataJpaTest chỉ load JPA, repository và entity, mặc định rollback sau mỗi test. Nếu classpath có H2, nó thay DataSource bằng H2 in-memory. Test dưới đây chạy với H2:
// File: src/test/java/com/example/shop/catalog/ProductRepositoryTest.java
package com.example.shop.catalog;
import java.math.BigDecimal;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import static org.assertj.core.api.Assertions.assertThat;
@DataJpaTest
class ProductRepositoryTest {
@Autowired
ProductRepository repository;
@Test
void luu_va_tim_theo_sku() {
Product saved = repository.save(
new Product("SKU-1", "Ao thun", new BigDecimal("199000")));
assertThat(saved.getId()).isNotNull();
assertThat(repository.findBySku("SKU-1")).isPresent();
}
}
H2 không chứng minh được hành vi của PostgreSQL. Khi cần test trên database thật, giữ container và bảo @DataJpaTest đừng thay DataSource:
@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class ProductRepositoryPostgresTest {
@Container
@ServiceConnection
static PostgreSQLContainer<?> postgres =
new PostgreSQLContainer<>("postgres:17-alpine");
// ... cung mot test, khong can cau hinh url/password
}
Testcontainers 2.0.5 là dòng hiện hành; @ServiceConnection lấy connection details từ container, không cần hard-code URL. Cách này chậm hơn H2 nhưng bắt được lệch kiểu cột và SQL thật.
Pitfalls hay gặp
open-in-view và lazy loading trong view
Boot bật spring.jpa.open-in-view=true mặc định và in warning lúc khởi động. OSIV giữ EntityManager mở đến khi view render xong, nên truy cập association lazy trong template vẫn chạy — kèm một query mỗi lần. Kết quả là N+1 query và connection bị giữ lâu. Tắt OSIV và map sang DTO trong service; đừng “sửa” bằng cách đổi association sang EAGER.
Entity làm DTO của API
Serialize entity trực tiếp kéo theo lazy association (lỗi hoặc query ngoài transaction), lộ field nội bộ, và tạo vòng lặp JSON với quan hệ hai chiều. Dùng record DTO và map trong transaction; đừng biến schema thành hợp đồng API không kiểm soát.
Lombok @Data trên entity
@Data sinh equals/hashCode trên toàn bộ field, gồm id và field mutable; toString có thể chạm association lazy và bắn query. Nó cũng không tự sinh constructor không đối số. Dùng @Getter/@Setter với @EqualsAndHashCode(onlyExplicitlyIncluded = true).
Thiếu index
Khóa ngoại, cột lọc và cột sort đều cần index. Thiếu index trên sku biến mỗi lần tra cứu thành full scan; thiếu composite index khiến query status + created_at chậm dần. Khai báo bằng @Table(indexes = ...) để index đi cùng entity và vào migration; đừng rải unique = true nếu muốn kiểm soát tên constraint.
@Transactional trên thao tác đọc
Đọc dữ liệu vẫn nên có transaction, nhưng dùng @Transactional(readOnly = true). Spring đặt Hibernate session read-only, flush mode MANUAL, bỏ dirty checking — tránh việc một setter vô tình sinh UPDATE. Đừng coi read-only là tăng tốc thần kỳ; lợi ích chính là tính đúng đắn. Transaction và rollback ở bài Làm chủ giao dịch trong Spring.
Checklist trước khi commit entity đầu tiên
- Import
jakarta.persistence; entity khôngfinal, có constructorprotectedkhông đối số. - Khóa chính chọn theo database và tải ghi; nếu
SEQUENCE,allocationSizekhớp sequence. @Enumerated(STRING),java.timekhông kèm@Temporal,@Versiontrên aggregate root bị sửa đồng thời.- equals/hashCode dựa trên business key bất biến, không dựa trên id tự sinh.
- Index cho cột tra cứu và khóa ngoại;
ddl-autolàvalidate/noneở production. open-in-view=false, API trả DTO, test repository chạy trên H2 hoặc container.
Nhìn về 2027
Hibernate 8 vẫn beta, nên 2027 nhiều khả năng vẫn là năm của Hibernate 7.x và Jakarta Persistence 3.2. Khi Hibernate 8 GA, API entity cốt lõi khó đổi; điều đáng theo dõi là Jakarta EE 12, id có thứ tự thời gian và mặc định DDL. Trong lúc chờ, giữ schema bằng migration và giữ entity nhỏ.
Đọc tiếp
Entity chỉ là một bảng. Bước tiếp theo là nối các bảng trong Mô hình hóa các mối quan hệ trong JPA, rồi xem Hibernate gọi callback nào trong vòng đời entity. Một entity đúng nghĩa giúp repository và migration phía sau dễ hơn.



