簡介
Hibernate ORM Panache 是 Hibernate ORM 之上的一層，可簡化 JPA 實體和查詢的編寫。 Panache 支援兩種模式：Active Record（實體自查詢）和 Repository（實體/儲存庫分離）。與開發服務結合使用，您無需安裝 PostgreSQL — Quarkus 會自動啟動容器。
設定 PostgreSQL
依賴關係
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-hibernate-orm-panache</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>
開發服務 — 零配置
只需新增依賴項，開發模式無需進一步配置：
# application.properties
# Dev Services tự động:
# - Pull postgres:latest container
# - Tạo database
# - Cấu hình JDBC URL
# - Inject vào Hibernate ORM
# Chỉ cần cấu hình cho production
%prod.quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.username=${DB_USERNAME}
%prod.quarkus.datasource.password=${DB_PASSWORD}
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
# Schema management
quarkus.hibernate-orm.database.generation=drop-and-create
# Production dùng Flyway (bài sau)
%prod.quarkus.hibernate-orm.database.generation=none
檢查開發服務是否有效
# Start dev mode
quarkus dev
# Kiểm tra container đang chạy
docker ps
# CONTAINER ID IMAGE PORTS NAMES
# abc123 postgres:16 0.0.0.0:55432->5432/tcp ...
# Dev UI → http://localhost:8080/q/dev-ui → Database
活動記錄模式
實體類別
package com.xdev.ecommerce.product.entity;
import io.quarkus.hibernate.orm.panache.PanacheEntity;
import jakarta.persistence.*;
import java.math.BigDecimal;
import java.time.LocalDateTime;
@Entity
@Table(name = "products")
public class Product extends PanacheEntity {
// id được tự động generate bởi PanacheEntity (Long)
@Column(nullable = false, length = 255)
public String name;
@Column(columnDefinition = "TEXT")
public String description;
@Column(nullable = false, precision = 12, scale = 2)
public BigDecimal price;
@Column(name = "stock_quantity", nullable = false)
public int stockQuantity;
@Column(length = 100)
public String category;
@Column(length = 50)
public String status = "ACTIVE";
@Column(name = "created_at", updatable = false)
public LocalDateTime createdAt;
@Column(name = "updated_at")
public LocalDateTime updatedAt;
@PrePersist
void onPersist() {
createdAt = LocalDateTime.now();
updatedAt = createdAt;
}
@PreUpdate
void onUpdate() {
updatedAt = LocalDateTime.now();
}
}
使用活動記錄
// CREATE
Product product = new Product();
product.name = "Laptop Dell XPS 15";
product.price = new BigDecimal("32990000");
product.stockQuantity = 50;
product.category = "Electronics";
product.persist();
// READ by ID
Product found = Product.findById(1L);
// READ all
List<Product> all = Product.listAll();
// QUERY
List<Product> electronics = Product.list(
"category = ?1 and status = ?2", "Electronics", "ACTIVE");
// QUERY with named parameters
List<Product> cheap = Product.list(
"price < :maxPrice and category = :cat",
Parameters.with("maxPrice", new BigDecimal("10000000"))
.and("cat", "Electronics"));
// UPDATE
Product.update("price = price * 0.9 where category = ?1",
"Electronics");
// DELETE
Product.deleteById(1L);
Product.delete("status", "INACTIVE");
// COUNT
long total = Product.count();
long active = Product.count("status", "ACTIVE");
儲存庫模式
實體（不要擴充 PanacheEntity）
@Entity
@Table(name = "categories")
public class Category extends PanacheEntityBase {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
public Long id;
@Column(nullable = false, unique = true)
public String name;
public String description;
@OneToMany(mappedBy = "category", cascade = CascadeType.ALL)
public List<Product> products;
}
儲存庫類
package com.xdev.ecommerce.product.repository;
import io.quarkus.hibernate.orm.panache.PanacheRepository;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;
import java.util.Optional;
@ApplicationScoped
public class CategoryRepository implements PanacheRepository<Category> {
public Optional<Category> findByName(String name) {
return find("name", name).firstResultOptional();
}
public List<Category> findActive() {
return list("status", "ACTIVE");
}
public long countProducts(Long categoryId) {
return Product.count("category.id", categoryId);
}
}
在服務中使用儲存庫
@ApplicationScoped
public class CategoryService {
@Inject
CategoryRepository categoryRepository;
public List<Category> getAll() {
return categoryRepository.listAll();
}
@Transactional
public Category create(String name, String description) {
Category cat = new Category();
cat.name = name;
cat.description = description;
categoryRepository.persist(cat);
return cat;
}
}
PanacheQuery — 分頁與排序
import io.quarkus.panache.common.Page;
import io.quarkus.panache.common.Sort;
@GET
public Response listProducts(
@QueryParam("page") @DefaultValue("0") int page,
@QueryParam("size") @DefaultValue("20") int size,
@QueryParam("sort") @DefaultValue("createdAt") String sortBy,
@QueryParam("dir") @DefaultValue("desc") String direction) {
Sort sort = Sort.by(sortBy,
direction.equalsIgnoreCase("asc")
? Sort.Direction.Ascending
: Sort.Direction.Descending);
PanacheQuery<Product> query = Product
.find("status = ?1", sort, "ACTIVE")
.page(Page.of(page, size));
List<Product> items = query.list();
long total = query.count();
int totalPages = query.pageCount();
return Response.ok(items)
.header("X-Total-Count", total)
.header("X-Total-Pages", totalPages)
.build();
}
自訂查詢 — JPQL 和 Native
JPQL 查詢
@Entity
@Table(name = "products")
@NamedQuery(name = "Product.search",
query = """
SELECT p FROM Product p
WHERE (LOWER(p.name) LIKE LOWER(:keyword)
OR LOWER(p.description) LIKE LOWER(:keyword))
AND p.status = 'ACTIVE'
ORDER BY p.createdAt DESC
""")
public class Product extends PanacheEntity {
// ...
}
// Sử dụng
List<Product> results = Product.find("#Product.search",
Parameters.with("keyword", "%" + keyword + "%")).list();
原生 SQL 查詢
@ApplicationScoped
public class ProductRepository implements PanacheRepository<Product> {
public List<Product> searchFullText(String query) {
return find(
"""
to_tsvector('english', name || ' ' || description)
@@ plainto_tsquery('english', ?1)
""", query).list();
}
public List<Object[]> getTopCategories(int limit) {
return getEntityManager()
.createNativeQuery("""
SELECT category, COUNT(*) as cnt, AVG(price) as avg_price
FROM products
WHERE status = 'ACTIVE'
GROUP BY category
ORDER BY cnt DESC
LIMIT :limit
""")
.setParameter("limit", limit)
.getResultList();
}
}
交易
import jakarta.transaction.Transactional;
@ApplicationScoped
public class OrderService {
@Transactional
public Order createOrder(CreateOrderRequest request) {
// 1. Kiểm tra stock
Product product = Product.findById(request.productId());
if (product == null) {
throw new NotFoundException("Product not found");
}
if (product.stockQuantity < request.quantity()) {
throw new BadRequestException("Insufficient stock");
}
// 2. Giảm stock
product.stockQuantity -= request.quantity();
// Không cần persist() — entity đã managed
// 3. Tạo order
Order order = new Order();
order.productId = product.id;
order.quantity = request.quantity();
order.totalPrice = product.price
.multiply(BigDecimal.valueOf(request.quantity()));
order.status = "PENDING";
order.persist();
return order;
// Transaction auto-commit khi method return
// Auto-rollback nếu throw exception
}
}
使用開發服務進行測試
import io.quarkus.test.junit.QuarkusTest;
import jakarta.transaction.Transactional;
@QuarkusTest
class ProductRepositoryTest {
@Test
@Transactional
void testCreateAndFind() {
Product product = new Product();
product.name = "Test Product";
product.price = new BigDecimal("100000");
product.stockQuantity = 10;
product.persist();
assertNotNull(product.id);
Product found = Product.findById(product.id);
assertEquals("Test Product", found.name);
}
@Test
void testPagination() {
PanacheQuery<Product> query = Product.findAll()
.page(Page.of(0, 5));
List<Product> page1 = query.list();
assertTrue(page1.size() <= 5);
}
}
練習
- 建立實體
Product使用 Active Record 模式，包括生命週期回呼（@PrePersist,@PreUpdate） - 創建
Category具有儲存庫模式的實體，建立關係@OneToMany - 透過分頁和排序實現產品的 CRUD 端點
- 撰寫自訂查詢以按關鍵字搜尋產品 (JPQL)
5.使用PostgreSQL新增全文搜索
tsvector（本機查詢） - 建立訂單服務
@Transactional確保庫存一致性
總結
- 開發服務自動執行 PostgreSQL 容器，無需本機安裝
- 活動記錄 (
extends PanacheEntity) — 自存實體persist(),find(),delete() - 存儲庫模式 (
implements PanacheRepository<T>) — 單獨的關注點 - PanacheQuery 支援分頁（
page()), 計數 (count()), 排序 (Sort.by()） @Transactional確保原子性，返回時自動提交，異常時自動回滾- JPQL + Native SQL 適用於 Panache 不夠的複雜查詢
下一篇文章：Bean 驗證和錯誤處理 - 專業資料和錯誤處理。