Bạn sửa một field trên entity JPA, không gọi save, và transaction commit vẫn ghi thay đổi. Đó là dirty checking. Với Spring Data JDBC, cùng đoạn code đó không ghi gì, và bạn không có proxy nào có thể nổ sau khi transaction đóng. Đổi lại, mọi thứ phải rõ: save gọi tay, query viết tay khi cần, và bạn tự quyết định cột nào thuộc aggregate nào.
Mục lục
Cập nhật 2026
- Spring Boot 4.1.2 trên Spring Framework 7.0.10; Spring Data JDBC nằm trong train 2026.0.2. Bài viết không pin số version riêng của module
spring-data-jdbcvì nó đi theo train, không phải một dòng phát hành độc lập. - Toàn bộ là
jakarta.*;javax.*đã bị loại khỏi Framework 7. Không cònjavax.persistencehayjavax.annotationtrong code mới. - JDBC không bị deprecated. Đây là lựa chọn có chủ đích cho aggregate đơn giản, không phải bậc thấp hơn của JPA.
- Testcontainers 2.0.5 đổi tên artifact:
testcontainers-postgresql,testcontainers-junit-jupiter. Boot 4 cũng tách module test, nên đừng chép import cũ từ blog 2023.
Mô hình Spring Data JDBC: aggregate root là đơn vị, không phải entity
Spring Data JDBC không nhìn database qua một object graph. Nó nhìn qua aggregate root: một cụm object được ghi và đọc như một đơn vị nhất quán. Một aggregate có đúng một repository. Object con nằm trong aggregate được khai báo bằng collection và ghi cùng root; object thuộc aggregate khác chỉ được tham chiếu bằng id.
Ví dụ dưới đây có hai aggregate: Customer và Order. OrderItem không phải aggregate root; nó là phần của Order.
Customer (aggregate root)
└── Order (aggregate root, giữ customer_id)
└── OrderItem (thuộc Order, @MappedCollection)
Ba hệ quả bạn phải chấp nhận:
- Không lazy loading. Load một
Ordersẽ load luônitems. Không có proxy, không cóLazyInitializationException, nhưng cũng không có cách trì hoãn collection. - Không persistence context, không dirty checking. Không có identity map, không có flush tự động. Sửa object mà không gọi
savethì database không đổi. - Save là tường minh. Mỗi lần
savephát INSERT hoặc UPDATE; nó không so sánh trạng thái để bỏ qua cập nhật.
Transaction vẫn là của Spring: @Transactional trên service, không phải transaction do JDBC tự quản lý. Một lần ghi aggregate nên nằm trong một transaction, vì root và các bảng con được ghi bằng nhiều câu SQL.
Năm annotation đủ để bắt đầu
| Annotation | Package | Việc nó làm |
|---|---|---|
@Table |
org.springframework.data.relational.core.mapping |
Đặt tên bảng khi khác quy ước snake_case của tên class. |
@Column |
org.springframework.data.relational.core.mapping |
Đặt tên cột khi khác quy ước snake_case của tên field. |
@Id |
org.springframework.data.annotation |
Khóa chính của aggregate root; id null nghĩa là bản ghi mới. |
@MappedCollection |
org.springframework.data.relational.core.mapping |
Ánh xạ collection con sang bảng riêng; idColumn là cột FK trỏ về root, keyColumn chỉ cần cho List/Map. |
@Version |
org.springframework.data.annotation |
Optimistic locking; null hoặc 0 là bản ghi mới, mỗi lần update tăng thêm 1. |
Tên bảng và cột mặc định đã là snake_case, nên annotation chỉ cần khi schema của bạn không theo quy ước. Đừng thêm @GeneratedValue: nó là annotation JPA và không có tác dụng ở đây.
Aggregate, repository và service chạy được
Giả sử bạn dùng Maven, Java 25 (Boot 4.1.2 hỗ trợ 17 đến 27), PostgreSQL và Flyway. Dependency tối thiểu:
org.springframework.boot:spring-boot-starter-data-jdbcorg.postgresql:postgresqlở scope runtimeorg.flywaydb:flyway-corevàorg.flywaydb:flyway-database-postgresql- Test:
spring-boot-starter-test,spring-boot-testcontainers,org.testcontainers:testcontainers-postgresql:2.0.5,org.testcontainers:testcontainers-junit-jupiter:2.0.5
-- File: src/main/resources/db/migration/V1__orders.sql
create table orders (
id bigint generated by default as identity primary key,
customer_id bigint not null,
placed_at timestamptz not null,
status varchar(20) not null,
version bigint not null default 0
);
create table order_items (
id bigint generated by default as identity primary key,
order_id bigint not null references orders (id) on delete cascade,
sku varchar(64) not null,
quantity int not null,
unit_price numeric(12, 2) not null
);
create index idx_orders_customer on orders (customer_id);
// File: src/main/java/com/evotek/sales/Order.java
import org.springframework.data.annotation.Id;
import org.springframework.data.annotation.Version;
import org.springframework.data.relational.core.mapping.Column;
import org.springframework.data.relational.core.mapping.MappedCollection;
import org.springframework.data.relational.core.mapping.Table;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.LinkedHashSet;
import java.util.Set;
@Table("orders")
public class Order {
@Id
private Long id;
@Column("customer_id")
private Long customerId;
@Column("placed_at")
private OffsetDateTime placedAt;
private String status;
@Version
private Long version;
@MappedCollection(idColumn = "order_id")
private Set<OrderItem> items = new LinkedHashSet<>();
protected Order() { } // Spring Data JDBC cần constructor không tham số
public Order(Long customerId, OffsetDateTime placedAt) {
this.customerId = customerId;
this.placedAt = placedAt;
this.status = "NEW";
}
public void addItem(String sku, int quantity, BigDecimal unitPrice) {
items.add(new OrderItem(sku, quantity, unitPrice));
}
public void confirm() {
this.status = "CONFIRMED";
}
public Long getId() {
return id;
}
public Set<OrderItem> getItems() {
return items;
}
}
// File: src/main/java/com/evotek/sales/OrderItem.java
import org.springframework.data.annotation.Id;
import org.springframework.data.relational.core.mapping.Column;
import org.springframework.data.relational.core.mapping.Table;
import java.math.BigDecimal;
@Table("order_items")
public class OrderItem {
@Id
private Long id;
private String sku;
private int quantity;
@Column("unit_price")
private BigDecimal unitPrice;
protected OrderItem() { }
public OrderItem(String sku, int quantity, BigDecimal unitPrice) {
this.sku = sku;
this.quantity = quantity;
this.unitPrice = unitPrice;
}
// getters
}
OrderItem có @Id riêng vì nó là entity trong bảng riêng, nhưng nó không có repository. Bạn không gọi orderItemRepository.save; mọi thay đổi đi qua Order.
// File: src/main/java/com/evotek/sales/OrderRepository.java
import org.springframework.data.jdbc.repository.query.Query;
import org.springframework.data.repository.CrudRepository;
import org.springframework.data.repository.query.Param;
import java.util.List;
public interface OrderRepository extends CrudRepository<Order, Long> {
List<Order> findByCustomerId(Long customerId);
@Query("""
select * from orders
where customer_id = :customerId and status = :status
order by placed_at desc
""")
List<Order> findRecent(@Param("customerId") Long customerId,
@Param("status") String status);
}
@Query ở đây là org.springframework.data.jdbc.repository.query.Query, không phải annotation cùng tên của JPA. Với aggregate root, câu query của bạn chỉ nạp root và các quan hệ one-to-one; collection như items được nạp bằng câu SELECT riêng do Spring Data sinh ra. Vì vậy một findByCustomerId trả 50 đơn hàng sẽ chạy 1 câu cho root và 50 câu cho items — đúng như mô hình eager, không phải lỗi N+1 ngầm.
// File: src/main/java/com/evotek/sales/OrderService.java
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
@Service
@Transactional(readOnly = true)
public class OrderService {
private final OrderRepository orders;
public OrderService(OrderRepository orders) {
this.orders = orders;
}
public Order get(Long id) {
return orders.findById(id)
.orElseThrow(() -> new IllegalArgumentException("Order " + id));
}
@Transactional
public Order place(Long customerId) {
Order order = new Order(customerId, OffsetDateTime.now());
order.addItem("SKU-1", 2, new BigDecimal("19.90"));
return orders.save(order); // INSERT root, rồi INSERT items
}
@Transactional
public void confirm(Long id) {
Order order = get(id);
order.confirm();
orders.save(order); // UPDATE root; items bị xóa và insert lại
}
}
Chi tiết cuối cùng quan trọng hơn bạn tưởng: khi save một aggregate đã tồn tại, Spring Data JDBC xóa toàn bộ bản ghi con rồi insert lại, không update từng dòng. Trigger, sequence và audit log trên bảng con sẽ thấy DELETE/INSERT, không phải UPDATE. Nếu bảng con có dữ liệu lịch sử, đừng dùng nó làm nơi lưu vết.
Reporting: dùng JdbcClient, đừng ép aggregate
Báo cáo không cần aggregate. Một câu SQL phẳng, map sang record, chạy trên connection read-only là đủ:
// File: src/main/java/com/evotek/sales/OrderReportService.java
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.stereotype.Service;
import java.math.BigDecimal;
import java.util.List;
@Service
public class OrderReportService {
private final JdbcClient jdbc;
public OrderReportService(JdbcClient jdbc) {
this.jdbc = jdbc;
}
public List<CustomerOrderCount> topCustomers(int limit) {
return jdbc.sql("""
select customer_id,
count(*) as order_count,
sum(unit_price * quantity) as revenue
from orders o
join order_items i on i.order_id = o.id
where o.status = 'CONFIRMED'
group by customer_id
order by order_count desc
limit :limit
""")
.param("limit", limit)
.query((rs, rowNum) -> new CustomerOrderCount(
rs.getLong("customer_id"),
rs.getLong("order_count"),
rs.getBigDecimal("revenue")))
.list();
}
public record CustomerOrderCount(Long customerId, long orderCount, BigDecimal revenue) { }
}
JdbcClient là cửa vào JDBC hiện đại của Spring Framework; nó thay JdbcTemplate cho code mới, nhưng JdbcTemplate vẫn tồn tại và vẫn dùng được. Với reporting, SQL viết tay cho bạn quyền kiểm soát index, window function và cách join mà repository aggregate không có.
Test với Testcontainers
// File: src/test/java/com/evotek/sales/OrderRepositoryTest.java
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import static org.assertj.core.api.Assertions.assertThat;
@Testcontainers
@SpringBootTest
class OrderRepositoryTest {
@Container
@ServiceConnection
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17");
@Autowired
OrderRepository orders;
@Test
void save_va_load_aggregate() {
Order order = new Order(42L, OffsetDateTime.parse("2026-11-09T08:00:00Z"));
order.addItem("SKU-1", 2, new BigDecimal("19.90"));
order.addItem("SKU-2", 1, new BigDecimal("5.00"));
Order saved = orders.save(order);
Order loaded = orders.findById(saved.getId()).orElseThrow();
assertThat(loaded.getItems()).hasSize(2);
}
}
@ServiceConnection lấy URL, user và password từ container, nên không cần @DynamicPropertySource. Flyway chạy migration trên container trước khi test, đúng như production. Đây là bài test bắt được lỗi mapping @MappedCollection sớm hơn nhiều so với việc mở Postgres bằng tay.
JPA hay JDBC: nhìn theo năm tiêu chí
| Tiêu chí | Spring Data JPA | Spring Data JDBC |
|---|---|---|
| Mô hình | Entity graph, quan hệ hai chiều, cascade và fetch type | Aggregate root, tham chiếu bằng id, @MappedCollection cho bảng con |
| Load | Lazy hoặc eager qua proxy; N+1 tùy fetch | Eager theo aggregate; mỗi collection một SELECT, không proxy |
| Cache | Persistence context (L1) và second-level cache của Hibernate | Không có cache tích hợp; tự làm ở tầng ngoài nếu cần |
| Schema | Có thể sinh DDL bằng ddl-auto (không dùng cho production) |
Không sinh DDL; migration là bắt buộc |
| Use case | Domain phức tạp, nhiều quan hệ, cần tính năng ORM nâng cao | Aggregate đơn giản, SQL dự đoán được, service read-heavy |
Khi nào chọn JDBC, khi nào không
Chọn Spring Data JDBC khi:
- Aggregate nhỏ, một root và vài bảng con, không có đồ thị object nhiều tầng.
- Bạn muốn đọc code là thấy ngay câu SQL nào sẽ chạy, không phải đoán qua fetch type.
- Service read-heavy hoặc microservice có schema biên rõ ràng.
- Bạn muốn tránh N+1 và những cú
LazyInitializationExceptionxuất hiện sau khi transaction đóng. - Reporting cần SQL viết tay, join nhiều bảng, window function.
Không chọn khi:
- Domain có quan hệ phức tạp, nhiều aggregate tham chiếu chéo và cần cascade có kiểm soát.
- Bạn phụ thuộc vào second-level cache, entity graph, JPQL/Criteria hoặc dirty checking.
- Team đã chuẩn hóa JPA, có sẵn convention và không có lý do cụ thể để đổi.
Trong dự án thật, ranh giới thường không phải “JPA hay JDBC”. Nhiều team dùng JPA cho command model và JdbcClient cho read model; Spring Data JDBC phù hợp khi module đó có ít aggregate và schema ổn định.
Sáu pitfall tốn thời gian nhất
1. Chờ lazy loading
findById nạp luôn collection. Nếu bạn chỉ cần tổng số item, đừng load aggregate rồi đếm trong Java; viết một câu count hoặc query report. Ngược lại, đừng giả định có thể gọi order.getItems() sau khi transaction đóng mà không có gì xảy ra — dữ liệu đã nằm trong object, nhưng object đó không còn gắn với database.
2. Giả định có dirty checking
Đây là lỗi phổ biến nhất khi chuyển từ JPA. order.confirm() không ghi gì. Phải gọi orders.save(order) trong transaction. Ngược lại, save một aggregate không đổi cũng vẫn phát UPDATE, nên đừng coi save là “chỉ ghi khi cần”.
3. Thiếu @MappedCollection
Nếu items không có @MappedCollection(idColumn = "order_id"), Spring Data JDBC không biết bảng con trỏ về root bằng cột nào. Kết quả là collection không được ghi/đọc theo cách bạn mong đợi. Tên trong idColumn phải khớp chính xác cột FK trong schema; sai tên là lỗi runtime, không phải lỗi compile.
4. Chờ cascade như JPA
Không có CascadeType, orphanRemoval hay fetch. Xóa Order không tự xóa Customer; quan hệ khác aggregate chỉ là id, bạn phải tự gọi repository hoặc để FK xử lý. Với bảng con trong aggregate, việc ghi/xóa do cơ chế aggregate quyết định, không phải annotation cascade.
5. Quên migration
Spring Data JDBC không tạo bảng. Không có ddl-auto, không có schema generation. Flyway hoặc Liquibase là bắt buộc ngay từ ngày đầu; schema.sql chỉ phù hợp cho demo hoặc database nhúng. Đây là điểm khác biệt lớn so với JPA khi mới bắt đầu.
6. Dùng nhầm @Query của JPA
org.springframework.data.jpa.repository.Query và org.springframework.data.jdbc.repository.query.Query là hai annotation khác nhau. Chép import JPA sang repository JDBC thì method không chạy như bạn nghĩ, thường bị coi là derived query và parse tên sai. Kiểm tra import trước khi debug SQL.
Nhìn về 2027
Không có tín hiệu Spring Data JDBC bị gộp hay khai tử; nó vẫn là module chính thức trong train Spring Data. Hướng đáng theo dõi là JdbcClient ngày càng được dùng làm read model chuẩn, và các module JDBC/R2DBC chia sẻ dialect cùng metadata tốt hơn. Nếu bạn chọn công nghệ cho 2027, tiêu chí vẫn là ranh giới aggregate và khả năng dự đoán SQL, không phải benchmark CRUD.
Checklist
- Vẽ aggregate boundary trước khi viết class; mỗi aggregate một repository.
- Đặt
@MappedCollection(idColumn = "...")cho mọi bảng con và kiểm tra tên cột FK. - Gọi
saveở mọi đường ghi; đừng dựa vào dirty checking. - Đặt
@Transactionalở method ghi,readOnly = trueở class service. - Dùng
@Versioncho aggregate có cập nhật đồng thời; nhớ rằng SQL tay không bump version. - Viết Flyway migration và một Testcontainers test cho mỗi aggregate.
Đọc tiếp bài Spring Data JPA cho người mới bắt đầu để so sánh repository proxy, rồi bài Hibernate Basics để hiểu mapping entity. Khi đã quen, quay lại giao dịch trong Spring vì JDBC hay JPA đều phụ thuộc cùng một transaction manager. Toàn bộ thứ tự bài nằm ở lộ trình Spring Boot.



