JPA & Hibernate — ORM principle, Spring Data abstraction layers

Module 03 build TaskFlow REST API với in-memory ConcurrentHashMap. Pattern này OK cho demo nhưng không production: data mất khi restart, không query phức tạp, không transaction. Module 04 này thay storage layer bằng PostgreSQL + JPA + Hibernate + Spring Data JPA.

Bài đầu tiên trả lời câu hỏi căn bản: JPA là gì? Hibernate là gì? Spring Data JPA là gì? Tại sao 3 layer? Hiểu rồi, mọi annotation @Entity, @OneToMany, JpaRepository ở các bài sau hiện ra logic, không còn là magic.

1. Bài toán ORM giải quyết

Code thuần JDBC kết nối Postgres lưu Project:

public Long save(Project project) {
    String sql = "INSERT INTO projects (name, description, status, created_at) VALUES (?, ?, ?, ?) RETURNING id";
    try (Connection conn = dataSource.getConnection();
         PreparedStatement ps = conn.prepareStatement(sql)) {
        ps.setString(1, project.name());
        ps.setString(2, project.description());
        ps.setString(3, project.status().name());
        ps.setObject(4, project.createdAt());

        try (ResultSet rs = ps.executeQuery()) {
            if (rs.next()) return rs.getLong(1);
            throw new RuntimeException("INSERT failed");
        }
    } catch (SQLException e) {
        throw new RuntimeException(e);
    }
}

public Optional<Project> findById(Long id) {
    String sql = "SELECT id, name, description, status, created_at FROM projects WHERE id = ?";
    try (Connection conn = dataSource.getConnection();
         PreparedStatement ps = conn.prepareStatement(sql)) {
        ps.setLong(1, id);
        try (ResultSet rs = ps.executeQuery()) {
            if (rs.next()) {
                return Optional.of(new Project(
                    rs.getLong("id"),
                    rs.getString("name"),
                    rs.getString("description"),
                    ProjectStatus.valueOf(rs.getString("status")),
                    rs.getObject("created_at", Instant.class)
                ));
            }
            return Optional.empty();
        }
    } catch (SQLException e) {
        throw new RuntimeException(e);
    }
}

40+ dòng cho 2 method. App có 20 entity → 800+ dòng boilerplate. Pain rõ ràng:

ORM (Object-Relational Mapping) là pattern giải quyết: map giữa Java object world và SQL relational world tự động. Developer code POJO + annotation, framework sinh SQL.

2. 3 layer abstraction

Java có 3 layer ORM build trên nhau:

flowchart TB
    App["Application code"]
    SDJ["Spring Data JPA<br/>(Repository abstraction)"]
    JPA["JPA Specification<br/>(jakarta.persistence)"]
    HB["Hibernate<br/>(implementation)"]
    JDBC["JDBC Driver"]
    DB[("PostgreSQL")]

    App -->|"interface OrderRepository extends JpaRepository"| SDJ
    SDJ -->|"EntityManager API"| JPA
    JPA -->|"Hibernate impl"| HB
    HB -->|"PreparedStatement, ResultSet"| JDBC
    JDBC --> DB

    style SDJ fill:#fef3c7
    style JPA fill:#d1fae5
    style HB fill:#fed7aa

Mỗi layer add abstraction giúp dev viết less code.

2.1 JPA Specification

JPA = Jakarta Persistence API (trước: Java Persistence API). Spec ra 2006 — define standard ORM cho Java. Không phải implementation, chỉ contract.

JPA define:

• Annotation: @Entity, @Id, @Column, @OneToMany, @ManyToOne, @JoinColumn, ...
• API: EntityManager, EntityManagerFactory, Query, TypedQuery.
• JPQL: query language giống SQL nhưng object-oriented (SELECT p FROM Project p WHERE p.status = 'ACTIVE').
• Lifecycle: persist, merge, remove, refresh.
• Persistence Context: cache + change tracking.

JPA spec không chạy được — chỉ là interface. Cần implementation.

2.2 Hibernate — implementation

Hibernate là implementation chính của JPA (>90% market). Thực thi mọi annotation/API JPA bằng cách:

• Generate SQL từ entity annotation (DDL) và JPQL query.
• Map ResultSet → entity qua reflection.
• Persistence context cache entity, dirty checking.
• Lazy loading qua proxy (CGLIB).
• Caching L1 (per-session) và L2 (cross-session, optional).

Hibernate là project tự sống — có từ 2001 (trước JPA). JPA 1.0 (2006) standardize idea từ Hibernate. Hibernate giờ là JPA-compliant implementation.

Alternatives: EclipseLink (Oracle), OpenJPA (Apache). Hiếm dùng. 99% Spring app dùng Hibernate.

2.3 Spring Data JPA — repository abstraction

Hibernate + JPA vẫn yêu cầu boilerplate:

// Pure JPA + Hibernate
@PersistenceContext
private EntityManager em;

public List<Project> findActiveByCustomer(String customer) {
    return em.createQuery(
        "SELECT p FROM Project p WHERE p.status = 'ACTIVE' AND p.customer = :customer",
        Project.class
    ).setParameter("customer", customer).getResultList();
}

Spring Data JPA elimnate luôn:

// Spring Data JPA — interface only
public interface ProjectRepository extends JpaRepository<Project, Long> {
    List<Project> findByStatusAndCustomer(ProjectStatus status, String customer);
}

Không implement — Spring Data sinh proxy class tại runtime. Method name findByStatusAndCustomer được parse → JPQL SELECT p FROM Project p WHERE p.status = ?1 AND p.customer = ?2.

Spring Data thêm:

• Repository abstraction: interface, không class.
• Derived query: parse method name → query.
• @Query annotation: custom JPQL/SQL khi derived không đủ.
• Pagination: Pageable + Sort chuẩn.
• Auditing: @CreatedDate, @LastModifiedDate, @CreatedBy.
• Specifications: dynamic query với Criteria API.

3 layer cộng dồn: Spring Data JPA dùng JPA API, JPA delegate Hibernate, Hibernate generate SQL → JDBC → DB.

3. ORM impedance mismatch

ORM không hoàn hảo. Java object model + SQL relational model có impedance mismatch — 5 khác biệt cốt lõi:

5 mismatch → 5 source bug subtle. Ví dụ:

@Entity
public class Order {
    @Id Long id;
    @ManyToOne Customer customer;
}

// Code: navigation 2 level
String name = order.customer.name();

ORM phải:

1. Generate SQL JOIN: SELECT o.*, c.* FROM orders o JOIN customers c ON o.customer_id = c.id WHERE o.id = ?.
2. Hoặc lazy load: load Order first, khi access order.customer → query thứ 2 SELECT * FROM customers WHERE id = ?.

Lazy load thuận tiện nhưng gây N+1: load 100 order + access customer → 1 + 100 query (Module 04 bài 04 đào sâu).

4. EntityManager — JPA core API

EntityManager là interface trung tâm JPA — analog Connection của JDBC nhưng cho object world.

5 method chính:

@PersistenceContext
private EntityManager em;

// 1. persist — INSERT
Project project = new Project("Mobile App", ProjectStatus.PLANNING);
em.persist(project);
// Sau commit: SQL INSERT chay

// 2. find — SELECT BY ID
Project loaded = em.find(Project.class, 42L);
// SQL: SELECT * FROM projects WHERE id = 42

// 3. merge — UPDATE
loaded.setStatus(ProjectStatus.ACTIVE);
em.merge(loaded);
// Sau commit: SQL UPDATE chay

// 4. remove — DELETE
em.remove(loaded);
// Sau commit: SQL DELETE chay

// 5. createQuery — JPQL
List<Project> active = em.createQuery(
    "SELECT p FROM Project p WHERE p.status = :status",
    Project.class
).setParameter("status", ProjectStatus.ACTIVE).getResultList();

Spring Data JPA wrap EntityManager qua JpaRepository. Bạn rarely call em trực tiếp — repository đủ 95% case.

4.1 Persistence Context — first-level cache

EntityManager quản 1 persistence context — Map từ ID → entity instance per transaction. Tính năng:

• Identity guarantee: trong cùng tx, em.find(Project, 42L) == em.find(Project, 42L) — same instance.
• Dirty checking: thay đổi field entity managed → SQL UPDATE auto chạy khi commit.
• Cascade: thay đổi Order → cascade Project (nếu config CascadeType.ALL).
• Lazy loading: proxy load related entity khi access.

@Transactional
public void example() {
    Project p1 = em.find(Project.class, 42L);     // SELECT
    p1.setName("New name");                        // mark dirty
    Project p2 = em.find(Project.class, 42L);     // KHONG SELECT — return p1 from cache
    System.out.println(p1 == p2);                  // true
    // Khi tx commit: UPDATE projects SET name = 'New name' WHERE id = 42 (auto)
}

Persistence context = transaction scope (mặc định). Khi tx kết thúc, context flush tất cả change → commit hoặc rollback.

4.2 Entity lifecycle — 4 state

stateDiagram-v2
    [*] --> Transient
    Transient --> Managed: persist()
    Managed --> Detached: detach() / em close
    Detached --> Managed: merge()
    Managed --> Removed: remove()
    Removed --> [*]: commit

State transition critical cho debug bug "tại sao change không save". Đa phần: object detached (out of tx) → modify không sync.

5. JPQL — query language

JPQL = JPA Query Language. Giống SQL nhưng query entity thay table:

SELECT p FROM Project p
WHERE p.status = 'ACTIVE' AND p.createdAt > :since
ORDER BY p.name ASC

Lưu ý:

• Project là entity class, không phải table name.
• p.status là field, không phải column name.
• :since là named parameter.

Hibernate compile JPQL → SQL:

SELECT p.id, p.name, p.description, p.status, p.created_at
FROM projects p
WHERE p.status = 'ACTIVE' AND p.created_at > ?
ORDER BY p.name ASC

Mapping field → column qua @Column annotation hoặc naming strategy default (camelCase → snake_case).

5.1 JPQL vs SQL

JPQL không thay SQL — nó wrap SQL với object semantics. Khi cần SQL native:

@Query(value = "SELECT * FROM projects WHERE created_at > ?1", nativeQuery = true)
List<Project> findRecentNative(Instant since);

Use case native SQL:

• DB-specific feature (Postgres array, JSON columns, full-text search).
• Performance critical query (window function, CTE).
• Complex JOIN không express được trong JPQL.

90% case JPQL đủ.

6. Spring Data Repository — sinh implementation

Magic chính của Spring Data: interface repository sinh implementation tại runtime.

public interface ProjectRepository extends JpaRepository<Project, Long> {
    List<Project> findByStatus(ProjectStatus status);
    Optional<Project> findByName(String name);
    long countByStatus(ProjectStatus status);
    boolean existsByName(String name);
    void deleteByStatus(ProjectStatus status);
}

Spring làm gì lúc startup:

sequenceDiagram
    participant Boot as Spring Boot startup
    participant SDR as Spring Data Repository scanner
    participant Proxy as ProjectRepository$$ProxyByCGLIB
    participant Parser as Method name parser
    participant EM as EntityManager
    participant DB as PostgreSQL

    Boot->>SDR: scan @EnableJpaRepositories packages
    SDR->>SDR: find ProjectRepository extends JpaRepository
    SDR->>Proxy: create proxy implementing interface
    Note over Proxy: For each method, register query

    Proxy->>Parser: parse "findByStatus"
    Parser->>Parser: detect property "status"
    Parser->>Parser: build JPQL "SELECT p FROM Project p WHERE p.status = ?1"

    Proxy->>Parser: parse "findByName"
    Parser->>Parser: detect property "name"
    Parser->>Parser: build JPQL ...

    Boot->>Proxy: register as bean

    Note over Boot: Runtime — service gọi repository
    Boot->>Proxy: findByStatus(ACTIVE)
    Proxy->>EM: createQuery JPQL setParameter
    EM->>DB: SQL query
    DB-->>EM: ResultSet
    EM-->>Proxy: List<Project>
    Proxy-->>Boot: return

Spring Data parse method name theo grammar:

[query verb] [subject] By [property] [keyword] [property] ...

Bài 03 sẽ đào sâu derived queries.

7. Spring Data JPA — autoconfiguration

Boot autoconfig setup mọi thứ:

flowchart TB
    Pull["Pull starter"]
    SBSDJPA["spring-boot-starter-data-jpa"]
    SDJ["spring-data-jpa"]
    HB["hibernate-core"]
    JDBC["spring-jdbc"]
    Tx["spring-tx"]
    SQL["jakarta.persistence-api"]

    Pull --> SBSDJPA
    SBSDJPA --> SDJ
    SBSDJPA --> HB
    SBSDJPA --> JDBC
    SBSDJPA --> Tx
    SBSDJPA --> SQL

spring-boot-starter-data-jpa pull:

• spring-data-jpa — repository abstraction.
• hibernate-core — JPA implementation.
• spring-orm — Spring's ORM integration (transaction, exception translation).
• spring-jdbc — DataSource, transaction.
• jakarta.persistence-api — JPA annotation.
• jakarta.transaction-api — @Transactional.

Boot autoconfig kích hoạt:

• DataSourceAutoConfiguration — HikariDataSource từ spring.datasource.*.
• HibernateJpaAutoConfiguration — EntityManagerFactory + JpaTransactionManager.
• JpaRepositoriesAutoConfiguration — scan @Repository interface, sinh proxy.

Setup tối thiểu:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/taskflow
    username: ${DB_USER}
    password: ${DB_PASS}
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        format_sql: true

@SpringBootApplication
public class App {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

@Repository
public interface ProjectRepository extends JpaRepository<Project, Long> { }

Đó là toàn bộ — Boot tự setup connection pool, transaction, EntityManager, repository proxy. Compare với Spring 4 era 50 dòng XML config.

8. ddl-auto — DDL strategy

spring.jpa.hibernate.ddl-auto quản schema generation:

Cảnh báo: không bao giờ create/update production. Schema change phải qua migration tool (Flyway/Liquibase — bài 06).

Pattern thực tế:

# application.yml
spring:
  jpa:
    hibernate:
      ddl-auto: validate

# application-dev.yml
spring:
  jpa:
    hibernate:
      ddl-auto: update           # dev convenience

# application-test.yml
spring:
  jpa:
    hibernate:
      ddl-auto: create-drop      # ephemeral schema

9. Vận hành production — persistence context, ddl-auto, monitoring

Hibernate persistence context (1st level cache) là source of truth cho dirty checking. Tuning sai → memory leak hoặc slow flush. Section này cover production tuning.

9.1 ddl-auto strategy production

Production rule: ddl-auto: validate + Flyway migration.

validate fail startup nếu entity không match DB schema → catch bug Flyway migration miss.

9.2 Hibernate Statistics — diagnostic

spring.jpa.properties.hibernate.generate_statistics: true
logging.level.org.hibernate.stat: INFO

Output cuối tx:

Statistics:
  3000000 nanoseconds spent acquiring 1 JDBC connection
  120 nanoseconds spent executing 12 JDBC statements
  4 entities loaded
  0 collections fetched

Production: bật khi diagnose, tắt sau (overhead 5-10%). Hoặc bật trên 1 instance debug mode.

Export Micrometer cho dashboard:

management.metrics.enable.hibernate: true

9.3 Persistence context bloat — heap pressure

Default Hibernate hold mọi entity loaded trong tx → 1st level cache. Long tx + nhiều entity = heap pressure → GC pause lớn.

Pattern batch (Module 04 bài 04 cover sâu):

for (int i = 0; i < records.size(); i++) {
    em.persist(new Project(records.get(i)));
    if (i % 50 == 0) {
        em.flush();
        em.clear();        // detach all → free heap
    }
}

9.4 Failure runbook

Mode 1 — LazyInitializationException production:

• Cause: serialize entity ngoài tx (OSIV tắt — Module 04 bài 04).
• Remediate: map sang DTO trong service.

Mode 2 — OptimisticLockException:

• Cause: 2 user update cùng entity, version field conflict.
• Remediate: @Version annotation + retry logic, hoặc inform user "data changed, reload".

Mode 3 — Schema validation fail tại startup:

• Triệu chứng: Boot start fail "missing column" hoặc "wrong type".
• Diagnose: entity field đổi nhưng Flyway migration chưa apply.
• Remediate: add migration tương ứng, redeploy.

Mode 4 — Persistence context bloat:

• Triệu chứng: heap usage tăng dần, GC pause lớn.
• Diagnose: heap dump → EntityManager instance hold nhiều entity.
• Remediate: shorter tx, batch processing với em.clear().

10. Pitfall tổng hợp

❌ Nhầm 1: Tin Spring Data JPA "thay" SQL. ✅ Spring Data JPA wrap JPA wrap SQL. Mọi query cuối cùng là SQL. Hiểu SQL → debug query nhanh hơn 10x.

❌ Nhầm 2: Modify entity ngoài transaction.

Project p = repo.findById(42L).orElseThrow();
// tx ket thuc o day
p.setStatus(ACTIVE);              // KHONG sync DB — detached

✅ Modify trong @Transactional method. Hoặc repo.save(p) explicit.

❌ Nhầm 3: Quên transactional read.

public Project findById(Long id) {              // KHONG @Transactional
    Project p = em.find(Project.class, id);
    return p.tasks();                            // LazyInitializationException
}

Lazy load tasks cần persistence context active. ✅ @Transactional (read-only OK) cho method query lazy association.

❌ Nhầm 4: Dùng ddl-auto=update production. ✅ ddl-auto=validate + Flyway migrate. Production never auto-modify schema.

❌ Nhầm 5: Thinking "JPA is slow". ✅ JPA cho phép viết slow code (N+1, lazy in loop) dễ. Đúng cách: fetch joins, projections, batch — hiệu năng comparable JDBC.

❌ Nhầm 6: Mix EntityManager direct + Repository.

@Service
public class S {
    @PersistenceContext EntityManager em;
    @Autowired ProjectRepository repo;
    // hai cách quản entity, dễ confusion
}

✅ Default Repository cho 95% case. EntityManager chỉ khi cần native query phức tạp hoặc bulk operation.

11. 📚 Deep Dive Spring Reference

12. Tóm tắt

• 3 layer abstraction: Spring Data JPA → JPA spec → Hibernate impl → JDBC → DB.
• JPA = Jakarta Persistence API, spec define @Entity, EntityManager, JPQL.
• Hibernate = >90% market JPA implementation. Generate SQL, lazy load proxy, persistence context.
• Spring Data JPA = repository abstraction. Sinh implementation runtime từ interface method name.
• ORM impedance mismatch 5 issue: inheritance, identity, association, navigation, granularity.
• EntityManager core API: persist/find/merge/remove/createQuery. Spring Data wrap qua JpaRepository.
• Persistence Context = first-level cache + dirty tracking. Scope = transaction.
• Entity lifecycle 4 state: Transient → Managed → Detached → Removed.
• JPQL query entity, không table. Hibernate compile JPQL → SQL theo dialect.
• Spring Data sinh implementation từ interface qua method name parsing — findByStatusAndCustomer → JPQL.
• Boot autoconfig: DataSourceAutoConfiguration + HibernateJpaAutoConfiguration + JpaRepositoriesAutoConfiguration — tối thiểu cấu hình spring.datasource.url.
• ddl-auto: production validate, dev update, test create-drop. Production schema change qua Flyway.

13. Tự kiểm tra

@Service
public class ProjectService {

  private final ProjectRepository repo;

  public ProjectDto getProjectWithTasks(Long id) {
      Project p = repo.findById(id).orElseThrow();
      return new ProjectDto(
          p.getId(),
          p.getName(),
          p.getTasks().size()           // CRASH here
      );
  }
}

@Service
public class ProjectService {

  @Transactional(readOnly = true)
  public ProjectDto getProjectWithTasks(Long id) {
      Project p = repo.findById(id).orElseThrow();
      return new ProjectDto(p.getId(), p.getName(), p.getTasks().size());
  }
}

@Query("SELECT p FROM Project p LEFT JOIN FETCH p.tasks WHERE p.id = :id")
Optional<Project> findByIdWithTasks(@Param("id") Long id);

// Service
public ProjectDto get(Long id) {
  Project p = repo.findByIdWithTasks(id).orElseThrow();
  return new ProjectDto(p.getId(), p.getName(), p.getTasks().size());
  // Tasks da load — khong can active session
}

@Query("SELECT new com.olhub.dto.ProjectDto(p.id, p.name, COUNT(t.id)) " +
     "FROM Project p LEFT JOIN p.tasks t WHERE p.id = :id GROUP BY p.id, p.name")
Optional<ProjectDto> findDtoById(@Param("id") Long id);

findByStatusAndCustomer
 ↓
[verb=find] [subject=By] [criteria]
 ↓
criteria: Status AND Customer
 ↓
JPQL: SELECT p FROM Project p WHERE p.status = ?1 AND p.customer = ?2

Method = (find | get | read | query | count | exists | delete) (By | All) Criteria
Criteria = Property [Keyword] [And | Or] Property [Keyword]
Keyword = Equals | Like | StartsWith | Between | LessThan | GreaterThan | IsNull | NotNull | OrderBy ...

findByName(String n)                                  WHERE name = ?
findByStatusIn(List<Status> s)                        WHERE status IN ?
findByCreatedAtBetween(Instant s, Instant e)          WHERE created_at BETWEEN ? AND ?
findByNameContainingIgnoreCase(String n)              WHERE LOWER(name) LIKE LOWER(?)
findTop10ByStatusOrderByCreatedAtDesc(Status s)       LIMIT 10
countByStatus(Status s)                               SELECT COUNT(*)
existsByName(String n)                                 SELECT 1
deleteByStatus(Status s)                               DELETE

@Transactional
public void identityExample() {
  Project p1 = repo.findById(42L).orElseThrow();    // SELECT
  Project p2 = repo.findById(42L).orElseThrow();    // KHONG SELECT — cache hit
  System.out.println(p1 == p2);                      // true (same instance)
  System.out.println(p1.hashCode() == p2.hashCode());// true
}

@Transactional
public void dirtyExample(Long id, String newName) {
  Project p = repo.findById(id).orElseThrow();
  p.setName(newName);          // KHONG goi save()
  // Method return — tx commit
  // Hibernate phat hien field 'name' thay doi → auto SQL UPDATE
}

public void outsideTxExample(Long id, String newName) {
  // KHONG @Transactional
  Project p = repo.findById(id).orElseThrow();   // tx cua repo.findById ket thuc
  p.setName(newName);                              // entity detached, KHONG sync DB
  // Method return — KHONG UPDATE
}

# DUNG dev — KHONG production
spring.jpa.hibernate.ddl-auto=update

// Repository interface
public interface ProjectRepository {
  Project save(Project p);
  Optional<Project> findById(Long id);
  List<Project> findByStatus(ProjectStatus status);
  boolean existsByName(String name);
  void delete(Long id);
}

// Implementation in-memory
@Repository
public class InMemoryProjectRepository implements ProjectRepository {
  private final Map<Long, Project> data = new ConcurrentHashMap<>();
  private final AtomicLong sequence = new AtomicLong();

  public Project save(Project p) {
      if (p.id() == null) {
          Long id = sequence.incrementAndGet();
          p = new Project(id, p.name(), ...);
      }
      data.put(p.id(), p);
      return p;
  }
  // ...
}

// Service KHONG biet implementation
@Service
public class ProjectService {
  private final ProjectRepository repo;     // depend interface

  public Project create(...) {
      if (repo.existsByName(name)) throw ...;
      return repo.save(...);
  }
}

// Same interface
public interface ProjectRepository extends JpaRepository<Project, Long> {
  List<Project> findByStatus(ProjectStatus status);
  boolean existsByName(String name);
}

// Bo InMemoryProjectRepository — Spring Data sinh impl tu dong

// Service KHONG DOI
@Service
public class ProjectService {
  private final ProjectRepository repo;     // van depend interface

  public Project create(...) {
      if (repo.existsByName(name)) throw ...;
      return repo.save(...);
  }
}

Standard CRUD?
Yes → Spring Data Repository (default)
No → Continue

Complex JPQL/JOIN/aggregate?
Yes → @Query annotation in Repository, hoặc EntityManager
No → Continue

DB-specific feature (Postgres array, JSON, full-text)?
Yes → @Query nativeQuery=true, hoặc JdbcClient
No → Continue

Bulk update/delete (millions of rows)?
Yes → JdbcClient (raw SQL, no entity overhead)
No → Continue

Performance ultra-critical (microbenchmark, hot path)?
Yes → JdbcClient hoặc raw JDBC
No → Continue

Default → Spring Data Repository

@Service
public class OrderService {

  private final OrderRepository repo;          // Spring Data: 90% case
  private final JdbcClient jdbc;                // Modern Spring 6.1+
  private final EntityManager em;               // JPA fallback

  // 90% method: standard CRUD
  public Order create(...) { return repo.save(...); }
  public List<Order> findActive() { return repo.findByStatus(ACTIVE); }

  // 5% method: complex query không express qua Repository
  public OrderStats getStats() {
      return jdbc.sql("""
          SELECT status, COUNT(*) AS cnt, SUM(total) AS sum
          FROM orders
          WHERE created_at >= :since
          GROUP BY status
          """)
          .param("since", LocalDate.now().minusDays(30))
          .query(OrderStats.class)
          .single();
  }

  // 5% method: bulk operation
  public void archiveOldOrders() {
      em.createQuery("UPDATE Order o SET o.archived = true WHERE o.createdAt < :cutoff")
          .setParameter("cutoff", LocalDate.now().minusYears(2))
          .executeUpdate();
  }
}

Bài tiếp theo: Entity mapping — @Entity, @Id, @GeneratedValue, naming strategy