Как Quarkus интегрируется с Hibernate ORM и Panache?

Hibernate ORM и Panache в Quarkus

Quarkus интегрирует Hibernate ORM через расширение quarkus-hibernate-orm, которое настраивается декларативно через application.properties без XML-конфигурации. Panache — это тонкая обёртка над Hibernate, которая устраняет шаблонный код и предлагает два паттерна работы с данными: Active Record и Repository.

Подключение зависимостей

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-hibernate-orm-panache</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

Конфигурация источника данных

quarkus:
  datasource:
    db-kind: postgresql
    username: app
    password: secret
    jdbc:
      url: jdbc:postgresql://localhost:5432/mydb
  hibernate-orm:
    database:
      generation: update
    log:
      sql: true

Паттерн Active Record

Сущность наследует PanacheEntity (или PanacheEntityBase для кастомного ID). Все методы запросов (find, list, count, delete, persist) доступны статически прямо на классе сущности.

@Entity
@Table(name = "products")
public class Product extends PanacheEntity {
    public String name;
    public BigDecimal price;
    public String category;

    // Кастомные запросы — статические методы прямо в сущности
    public static List<Product> findByCategory(String category) {
        return list("category", category);
    }

    public static Optional<Product> findCheapest(String category) {
        return find("category = ?1 order by price asc", category).firstResultOptional();
    }
}

// Использование в сервисе
@ApplicationScoped
public class ProductService {
    @Transactional
    public void create(String name, BigDecimal price, String category) {
        Product p = new Product();
        p.name = name;
        p.price = price;
        p.category = category;
        p.persist(); // INSERT в БД
    }

    public List<Product> getByCategory(String category) {
        return Product.findByCategory(category);
    }

    public PanacheQuery<Product> listPaged(int page, int size) {
        return Product.findAll().page(page, size);
    }
}

Паттерн Repository

Альтернативный подход: сущность остаётся чистым JPA @Entity, а логика выносится в отдельный класс, реализующий PanacheRepository<T>.

@Entity
public class Order {
    @Id @GeneratedValue
    public Long id;
    public String status;
    public LocalDate createdAt;
}

@ApplicationScoped
public class OrderRepository implements PanacheRepository<Order> {
    public List<Order> findPending() {
        return list("status", "PENDING");
    }

    public long countByStatus(String status) {
        return count("status", status);
    }

    @Transactional
    public void markCompleted(Long id) {
        update("status = 'COMPLETED' where id = ?1", id);
    }
}

// Инъекция репозитория
@Inject
OrderRepository orderRepository;

HQL и нативные запросы

Panache поддерживает сокращённый HQL (можно опускать from Entity where), параметры по позиции (?1) и по имени (:status):

// Сокращённый синтаксис
Product.find("price < ?1 and category = ?2", 100.0, "electronics");

// Именованные параметры
Product.find("category = :cat", Map.of("cat", "books"));

// Нативный SQL через EntityManager
@Inject EntityManager em;
List<Object[]> rows = em.createNativeQuery(
    "SELECT name, price FROM products WHERE price < :max"
).setParameter("max", 50.0).getResultList();

Подводные камни

• @Transactional обязателен для мутаций. Без этой аннотации на методе сервиса вызов persist() бросит TransactionRequiredException в runtime.
• Публичные поля vs геттеры. Active Record предпочитает публичные поля — Panache генерирует геттеры/сеттеры через байт-код инструментацию. Если вы объявите собственный геттер с иной логикой, это нарушит генерацию и Hibernate может не видеть поле.
• Ленивые ассоциации в native mode. В GraalVM native image Hibernate требует явной регистрации всех проксируемых классов; ленивые @OneToMany без явной аннотации могут падать с ClassNotFoundException.
• PanacheEntityBase для кастомного ID. Если нужен составной ключ или UUID, используйте PanacheEntityBase и определяйте поле ID вручную с @Id.
• database.generation=drop-and-create в проде. Настройка drop-and-create при рестарте контейнера удалит все данные. Используйте none в продакшне и управляйте схемой через Flyway/Liquibase.
• N+1 проблема. Panache не устраняет N+1 — нужно явно писать fetch join: find("select p from Product p join fetch p.tags where p.id = ?1", id).
• Транзакции в CDI бинах. @Transactional работает только на managed CDI бинах (@ApplicationScoped, @RequestScoped). Вызов транзакционного метода внутри того же класса (self-invocation) не создаёт новую транзакцию.

• Путать термин «hibernate orm panache» с соседним механизмом Quarkus.
• Не называть границу lifecycle, transaction, thread или request для «hibernate orm panache».
• Игнорировать production-эффекты «hibernate orm panache»: latency, SQL shape, memory, security или observability.

• Попросить объяснить механизм «hibernate orm panache» на минимальном примере.
• Проверить, видит ли кандидат failure mode и диагностику для «hibernate orm panache».
• Уточнить, какие настройки или API меняют «hibernate orm panache» в реальном сервисе.