Для чего нужен named query в Hibernate?

# Named Query в Hibernate: назначение и применение

Named Query — это именованный запрос, который определяется один раз в коде модели и может переиспользоваться во многих местах приложения. Это мощный инструмент, который решает несколько важных задач.

Основное назначение

Named Query нужны для:

1. Централизации HQL/SQL запросов — все запросы хранятся в одном месте (в аннотациях сущности или XML файле), а не разбросаны по DAO классам

2. Переиспользования запросов — один определённый запрос можно применять в разных местах кода без дублирования

3. Преждевременной проверки синтаксиса — запросы проверяются при запуске приложения, а не при их первом выполнении

4. Производительности — Hibernate может кэшировать скомпилированные запросы

Синтаксис и примеры

Определение на уровне сущности

@Entity
@Table(name = "users")
@NamedQuery(
    name = "User.findByEmail",
    query = "SELECT u FROM User u WHERE u.email = :email"
)
@NamedQuery(
    name = "User.findAllActive",
    query = "SELECT u FROM User u WHERE u.isActive = true ORDER BY u.createdAt DESC"
)
public class User {
    @Id
    private Long id;
    
    @Column(unique = true)
    private String email;
    
    private boolean isActive;
    
    private LocalDateTime createdAt;
}

Использование в DAO

@Repository
public class UserRepository {
    @PersistenceContext
    private EntityManager em;
    
    // Поиск пользователя по email
    public User findByEmail(String email) {
        return em.createNamedQuery("User.findByEmail", User.class)
            .setParameter("email", email)
            .getSingleResult();
    }
    
    // Получение всех активных пользователей
    public List<User> findAllActive() {
        return em.createNamedQuery("User.findAllActive", User.class)
            .getResultList();
    }
}

Несколько запросов через @NamedQueries

@Entity
@Table(name = "orders")
@NamedQueries({
    @NamedQuery(
        name = "Order.findByUserId",
        query = "SELECT o FROM Order o WHERE o.user.id = :userId ORDER BY o.createdAt DESC"
    ),
    @NamedQuery(
        name = "Order.findCompletedOrders",
        query = "SELECT o FROM Order o WHERE o.status = COMPLETED AND o.createdAt >= :date"
    ),
    @NamedQuery(
        name = "Order.countByStatus",
        query = "SELECT COUNT(o) FROM Order o WHERE o.status = :status"
    )
})
public class Order {
    @Id
    private Long id;
    
    @ManyToOne
    private User user;
    
    @Enumerated(EnumType.STRING)
    private OrderStatus status;
    
    private LocalDateTime createdAt;
}

Преимущества Named Query

1. Контроль синтаксиса при старте приложения

Eсли в Named Query ошибка в HQL, приложение не запустится. Это выявляет проблемы на ранней стадии, не дожидаясь их появления при выполнении код в продакшене:

// Ошибка в имени параметра будет выловлена при старте
@NamedQuery(
    name = "User.search",
    query = "SELECT u FROM User u WHERE u.email = :emailAddress" // но параметр :email
)

2. Кэширование скомпилированных запросов

Hibernate кэширует parse tree запроса, что ускоряет их повторное выполнение. Это лучше, чем постоянно парсить динамические запросы.

3. Разделение логики запросов и бизнес-логики

// Вся SQL-подобная логика в одном месте
// Классы сервисов остаются чистыми и сосредоточены на бизнес-логике

public List<User> getActiveUsersByRole(Role role) {
    // Логика бизнеса
    return userRepository.findActiveByRole(role);
}

Native Query с @NamedNativeQuery

Для сложных запросов на чистом SQL используют @NamedNativeQuery:

@Entity
@Table(name = "employees")
@NamedNativeQuery(
    name = "Employee.findHighEarners",
    query = "SELECT e.* FROM employees e WHERE e.salary > :minSalary",
    resultClass = Employee.class
)
public class Employee {
    @Id
    private Long id;
    private String name;
    private BigDecimal salary;
}

// Использование
public List<Employee> findHighEarners(BigDecimal minSalary) {
    return em.createNamedQuery("Employee.findHighEarners", Employee.class)
        .setParameter("minSalary", minSalary)
        .getResultList();
}

Named Query vs Criteria API vs JPQL

Лучшие практики

1. Используй Named Query для стандартных запросов, которые выполняются часто (find by ID, find by email, get all active)

2. Размещай связанные запросы вместе — если несколько запросов относятся к одной сущности, группируй их в @NamedQueries

3. Применяй логичные имена: EntityName.actionOrDescription

4. Кэшируй результаты при необходимости:

   @NamedQuery(
       name = "Department.findAll",
       query = "SELECT d FROM Department d"
   )
   @QueryHints(@QueryHint(name = "org.hibernate.cacheable", value = "true"))
   

5. Для очень сложных запросов переходи на Native SQL — Named Query остаёт JPQL нечитаемым

В итоге Named Query — это отличный инструмент для изоляции запросов, их кэширования и ранней проверки ошибок, что делает код более надёжным и производительным.