Spring Data JPA Cho Người Mới Bắt Đầu: Repository Dễ Dàng Hơn Bạn Tưởng (Series Java Spring Roadmap)

Bạn thêm extends JpaRepository<Product, Long>, và có ngay hơn hai chục phương thức. Nhưng trong mã nguồn không có class nào tên ProductRepository. Với Spring Data JPA, bạn khai báo hợp đồng và thư viện dựng implementation lúc chạy. Hiểu cơ chế đó quyết định bạn debug được lỗi khởi động chậm, N+1 và save sinh UPDATE thừa hay không.

Cập nhật 2026

  • Spring Data JPA 4.1.2 (train 2026.0.2) trên Spring Boot 4.1.2 / Spring Framework 7.0.10, Hibernate ORM 7.4.15.Final. Tất cả là jakarta.persistence; javax.persistence không còn được hỗ trợ.
  • Boot 4 tách module nên test slice đổi package: org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest (trước là ...test.autoconfigure.orm.jpa).
  • @NativeQuery là biến thể chính thức cho SQL thuần, thay dần @Query(nativeQuery = true). Specification có thêm allOf, anyOf, unrestricted.
  • Báo cáo phức tạp: cửa vào JDBC hiện đại là JdbcClient.

Repository là một proxy, không phải một class bạn viết

Khi context khởi động, DataJpaRepositoriesAutoConfiguration quét các interface kế thừa Repository và gọi JpaRepositoryFactory cho từng cái. Factory dựng JDK dynamic proxy implement interface của bạn, tạo target SimpleJpaRepository — class thật sự gọi EntityManager — và gắn hai interceptor: transaction (đọc metadata @Transactional) và query (parse tên phương thức).

Vì vậy ProductRepository bạn inject là proxy: stack trace lỗi có SimpleJpaRepository, RepositoryFactorySupport và lớp $Proxy, không phải code của bạn.

Chi phí khởi động. Mỗi repository tốn một proxy và một target; mỗi query method tốn một lần parse tên thành PartTree; mỗi @Query tốn một lần dựng Query để validate cú pháp và tên property. Sáu mươi repository, mỗi cái mười lăm method, cộng Hibernate dựng metamodel, là chi phí thật trước request đầu. Đánh đổi nằm ở spring.data.jpa.repositories.bootstrap-mode=lazy. Mặc định default dựng ngay, và bù lại, sai tên property trong findByNamme ném PropertyReferenceException lúc khởi động.

CrudRepository, PagingAndSortingRepository, JpaRepository

Interface Có gì Chọn khi
CrudRepository<T, ID> save, findById, findAll, count, delete*; trả Iterable Chỉ cần CRUD, không phân trang
PagingAndSortingRepository<T, ID> Chỉ findAll(Sort) và findAll(Pageable) Ghép thêm khi chỉ cần đọc có trang
JpaRepository<T, ID> Cả hai, cộng List-returning, flush, saveAndFlush, deleteAllInBatch, getReferenceById Mặc định cho hầu hết ứng dụng

Một chi tiết hay bị nói sai: trong Spring Data 4.x, PagingAndSortingRepository không kế thừa CrudRepository, superinterface duy nhất của nó là Repository. JpaRepository mới là cái gộp ListCrudRepository và ListPagingAndSortingRepository.

Entity và repository đầu tiên

// File: src/main/java/com/evotek/catalog/Product.java
// imports: jakarta.persistence.*, java.math.BigDecimal
@Entity
@Table(name = "products")
public class Product {

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

    @Column(nullable = false, length = 120)
    private String name;

    @Column(nullable = false, precision = 12, scale = 2)
    private BigDecimal price;

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

    protected Product() { } // Hibernate cần constructor không tham số

    public Product(String name, BigDecimal price, String category) {
        this.name = name;
        this.price = price;
        this.category = category;
    }

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

    // getters
}

Constructor protected đủ cho Hibernate và ngăn code business tạo entity rỗng. Setter công khai chỉ nên có khi thật cần; method như rename thể hiện ý định rõ hơn. Chi tiết mapping ở bài Hibernate Basics.

// File: src/main/java/com/evotek/catalog/ProductRepository.java
// imports: org.springframework.data.jpa.repository.*, org.springframework.data.domain.*
public interface ProductRepository extends JpaRepository<Product, Long> {

    List<Product> findByNameContainingIgnoreCase(String keyword);

    List<Product> findByPriceBetween(BigDecimal min, BigDecimal max);

    Page<Product> findByCategory(String category, Pageable pageable);

    Slice<Product> findByNameContaining(String keyword, Pageable pageable);

    int deleteByCategory(String category);
}

Tên phương thức chính là query

Cú pháp: find|read|count|exists|delete, rồi By, rồi các predicate nối bằng And/Or, rồi tùy chọn OrderBy. Từ khóa hay dùng: Between, GreaterThan/LessThan, Containing, StartingWith, In, IsNull, IgnoreCase, True/False. Giới hạn kết quả: findFirstBy, findTop3By.

Tham số cuối là Pageable hoặc Sort, và kiểu trả về quyết định cách chạy: Page thêm câu count, Slice không, List bỏ phân trang. Spring Data phân tích tên property lúc bootstrap, nên sai chính tả là lỗi khởi động chứ không phải lỗi dữ liệu.

Tên method dài quá ba predicate là dấu hiệu bạn đang viết query bằng cú pháp Đức. Lúc đó chuyển sang @Query, dễ đọc và dễ tối ưu index hơn.

@Query, @NativeQuery và projection

public interface ProductRepository extends JpaRepository<Product, Long> {

    @Query("""
            select p from Product p
            where p.category = :category and p.price >= :min
            order by p.price desc
            """)
    List<Product> findExpensive(@Param("category") String category, @Param("min") BigDecimal min);

    @Modifying(clearAutomatically = true)
    @Query("update Product p set p.price = p.price * :factor where p.category = :category")
    int reprice(String category, BigDecimal factor);

    @NativeQuery(value = "select * from products where sku = :sku",
                 countQuery = "select count(*) from products where sku = :sku")
    Optional<Product> findBySku(@Param("sku") String sku);
}

@Modifying bắt buộc cho UPDATE/DELETE; clearAutomatically = true xóa first-level cache, không có nó entity đã load vẫn giữ giá cũ. Update kiểu này bỏ qua lifecycle callback và không bump @Version.

Projection cắt dữ liệu ngay ở query thay vì load entity rồi map. Ba dạng:

// 1. Interface — Spring Data tự tạo proxy, chỉ đọc đúng cột cần
interface ProductView {
    String getName();
    BigDecimal getPrice();
}
List<ProductView> findByCategory(String category, Sort sort);

// 2. Record — constructor expression trong JPQL
record ProductSummary(Long id, String name, BigDecimal price) { }

@Query("select new com.evotek.catalog.ProductSummary(p.id, p.name, p.price) from Product p")
List<ProductSummary> summarize();

// 3. Class DTO thường — cùng cơ chế, cần đúng thứ tự tham số
@Query("select new com.evotek.catalog.ProductDto(p.name, p.category) from Product p where p.price > :min")
List<ProductDto> expensiveDtos(@Param("min") BigDecimal min);

Interface projection kiểu “closed” chỉ bind property, không chạy code. Dùng @Value thì thành open projection, SpEL evaluate từng phần tử — chậm trong list dài. Record và class cần FQCN trong select new; sai thứ tự tham số không báo lỗi kiểu. Với @NativeQuery, alias trong SQL phải khớp property.

Specification: truy vấn động không cần viết 2^n method

Bộ lọc trên UI thường là tổ hợp tùy chọn: category, khoảng giá, từ khóa. Viết derived method cho từng tổ hợp là bất khả thi. Specification biến mỗi điều kiện thành object ghép được:

// repository phải extends JpaSpecificationExecutor<Product>
public static Specification<Product> inCategory(String category) {
    return (root, query, cb) -> category == null ? null : cb.equal(root.get("category"), category);
}

public static Specification<Product> cheaperThan(BigDecimal max) {
    return (root, query, cb) -> max == null ? null : cb.lessThan(root.get("price"), max);
}

Specification<Product> spec = Specification.allOf(inCategory(cat), cheaperThan(maxPrice));
Page<Product> page = products.findAll(spec, PageRequest.of(0, 20, Sort.by("price").descending()));

allOf bỏ qua spec null, nên hai spec trên phục vụ cả bốn tổ hợp lọc. Đổi lại bạn mất type-safety của tên property và mất kiểu đọc tên method như tài liệu. Với một điều kiện cố định, derived method vẫn rẻ hơn.

Phân trang: Page khác Slice ở câu count

Page chạy hai câu: lấy dữ liệu và count để tính getTotalElements(). Slice chỉ chạy một câu, xin size + 1 bản ghi để biết hasNext(). Trên bảng vài chục triệu dòng với điều kiện phức tạp, câu count thường đắt hơn câu lấy dữ liệu — vì thế infinite scroll dùng Slice, bảng có số trang mới cần Page.

Pageable đánh số từ 0: PageRequest.of(0, 20) là trang đầu. Thêm tie-breaker như Sort.by("price").descending().and(Sort.by("id")), nếu không một bản ghi có thể xuất hiện ở hai trang.

save, saveAll, flush: ngữ nghĩa thật

SimpleJpaRepository.save có hai nhánh: isNew(entity) thì em.persist, ngược lại em.merge. Với Long id sinh tự động, id null nghĩa là new. Với id bạn gán hoặc UUID, isNew trả false nên mọi save thành merge: SELECT trước, INSERT sau. Sửa bằng Persistable<ID> hoặc @Version.

merge trả về một instance khác. Entity bạn truyền vào vẫn detached; bỏ qua giá trị trả về thì thay đổi sau đó không được flush. Luôn dùng Product saved = repository.save(p).

saveAll chỉ là vòng lặp gọi save. Batch thật cần spring.jpa.properties.hibernate.jdbc.batch_size=50 và order_inserts=true, và GenerationType.IDENTITY vô hiệu hóa batch insert vì Hibernate phải lấy id từng dòng. Cần insert hàng loạt thì dùng sequence hoặc JdbcClient.

flush() đẩy SQL xuống DB nhưng không commit; transaction vẫn rollback được. Dùng nó để phát hiện vi phạm constraint sớm, hoặc trước câu native đọc dữ liệu vừa ghi. Đừng coi flush là “lưu lại” — commit mới là lưu.

deleteById và những cái bẫy xóa

Trong Spring Data JPA 4.1.2, deleteById là findById(id).ifPresent(this::delete). Hai hệ quả: nó luôn SELECT trước khi DELETE, và nếu id không tồn tại thì nó không ném lỗi — im lặng không làm gì. Đừng trả 204 rồi coi như đã xóa; cần 404 thì kiểm tra existsById trước.

deleteAll() load toàn bộ entity rồi xóa từng cái; deleteAllInBatch() phát một câu DELETE nhưng bỏ qua lifecycle callback và cascade. Derived deleteByCategory cũng load rồi xóa từng entity: 10.000 dòng là 10.000 lệnh — gọi trong @Transactional, và dùng @Modifying nếu chỉ cần một câu.

Service: @Transactional(readOnly = true) ở class

// File: src/main/java/com/evotek/catalog/ProductService.java
@Service
@Transactional(readOnly = true)
public class ProductService {

    private final ProductRepository products;

    public ProductService(ProductRepository products) { this.products = products; }

    public Page<ProductSummary> byCategory(String category, int page) {
        return products.findByCategory(category, PageRequest.of(page, 20, Sort.by("price").descending()))
                .map(ProductSummary::from);
    }

    @Transactional
    public Product create(String name, BigDecimal price, String category) {
        return products.save(new Product(name, price, category));
    }

    @Transactional
    public void rename(Long id, String name) {
        Product product = products.findById(id)
                .orElseThrow(() -> new ProductNotFoundException(id));
        product.rename(name); // managed entity: dirty checking flush khi commit
    }
}

Hai điểm đáng chú ý. readOnly = true không chỉ là gợi ý: Hibernate chuyển flush mode sang MANUAL, nên ghi trong method read-only bị bỏ im lặng — method ghi phải có @Transactional riêng. Entity trong rename đang managed nên không cần save.

Test repository với @DataJpaTest

// File: src/test/java/com/evotek/catalog/ProductRepositoryTest.java
// imports: org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest
import static org.assertj.core.api.Assertions.assertThat;

@DataJpaTest
class ProductRepositoryTest {

    @Autowired
    ProductRepository products;

    @Test
    void loc_theo_khoang_gia_va_sap_xep() {
        products.saveAll(List.of(
                new Product("Phím cơ", new BigDecimal("1500000"), "gear"),
                new Product("Chuột", new BigDecimal("400000"), "gear")));

        List<Product> found = products.findByPriceBetween(
                new BigDecimal("1000000"), new BigDecimal("2000000"));

        assertThat(found).extracting(Product::getName).containsExactly("Phím cơ");
    }
}

@DataJpaTest nạp đúng phần JPA, thay datasource bằng database nhúng và rollback sau mỗi test. Đây là nơi phát hiện sớm lỗi countQuery hay @EntityGraph, vì test chạy cả bootstrap repository như production. Cần Postgres thật thì thêm Testcontainers và @AutoConfigureTestDatabase(replace = NONE).

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

1. N+1 từ derived query

findByCategory trả 200 Order; vòng lặp gọi order.getLines().size() phát thêm 200 câu. Sửa bằng @EntityGraph(attributePaths = "lines") hoặc join fetch. Fetch type đã bàn ở bài quan hệ JPA.

2. findAll rồi lọc trong Java

findAll() kéo cả bảng về heap rồi stream().filter(). Danh sách id thì dùng findAllById; điều kiện thì viết query, để database lọc thay JVM.

3. Trả entity ra controller

Entity không phải DTO. Association lazy serialize sau khi transaction đóng gây LazyInitializationException; quan hệ hai chiều gây đệ quy vô hạn trong JSON; và bạn expose cột nội bộ. Trả projection hoặc DTO. spring.jpa.open-in-view=true (mặc định Boot 4.1.2) chỉ che lỗi đầu.

4. save trên entity detached

new Product(), setId(id), rồi save: isNew false nên đây là merge. Hibernate SELECT rồi copy toàn bộ field từ object detached — kể cả field null client không gửi — và UPDATE. Kết quả là mất dữ liệu. Sửa: load entity trong transaction rồi gọi method nghiệp vụ.

5. Fetch join đi kèm Pageable

join fetch collection rồi trả Page khiến Hibernate không đặt được LIMIT: nó load hết rồi phân trang trong bộ nhớ. Với collection, trả List rồi tự cắt, hoặc query hai bước theo id.

6. @Query native sai kiểu trả về

@NativeQuery khai báo List<Product> nhưng SELECT vài cột sẽ lỗi mapping, vì Hibernate map theo alias. Native cũng không được viết lại miễn phí: câu đơn giản thì tự suy ra count, câu phức tạp cần countQuery. SQL phức tạp thì JdbcClient tốt hơn.

Khi nào không nên dùng Spring Data JPA

Tình huống Chọn
Báo cáo nhiều bảng, window function, đọc hàng triệu dòng JdbcClient với SQL viết tay, map sang record
Aggregate root đơn giản, không cần lazy loading hay identity map Spring Data JDBC — cùng mô hình repository, không proxy, không session
Batch lớn, ETL, import file JdbcClient batch, hoặc jOOQ nếu cần type-safe SQL
Domain giàu hành vi, quan hệ phức tạp, cần dirty checking JPA — chính bài này

Ranh giới không phải “JPA hay không”, mà là dùng cả hai: JPA cho command và domain, JdbcClient cho read model. Bài Spring Data JDBC đi sâu lựa chọn thứ hai; thứ tự các bài nằm ở lộ trình Spring Boot.

Nhìn về 2027

Hibernate 8 mới ở beta, nên 2026 vẫn là năm của Hibernate 7.4 trên Jakarta Persistence. Hai hướng đáng theo dõi: keyset pagination qua Window và ScrollPosition cho bảng lớn, và @NativeQuery gom các câu SQL báo cáo về một chỗ có kiểu trả về rõ ràng. Virtual thread làm JDBC blocking rẻ hơn, nhưng không làm câu count nhanh hơn.

Checklist

  • Chọn JpaRepository trừ khi cần interface nhỏ hơn.
  • Method ghi nằm trong @Transactional; class để readOnly = true.
  • Không trả entity ra ngoài service — map sang projection hoặc record.
  • Rà mọi chỗ findAll và mọi vòng lặp chạm association lazy.
  • Đặt hibernate.jdbc.batch_size trước khi tối ưu insert; bỏ IDENTITY nếu cần batch.
  • Viết @DataJpaTest cho mỗi query method có điều kiện, không chỉ đường CRUD.

Đường đi tiếp theo: quay lại bài transaction trong Spring để hiểu vì sao flush khác commit, rồi thử viết một Specification cho bộ lọc thật của dự án bạn. Khi sai, log SQL sẽ chỉ ra.