Hibernate中的@Subselect注解详解

1. 引言

本文将深入探讨Hibernate中的@Subselect注解，包括其使用方法、核心优势以及相关限制。我们将重点分析该注解如何实现实体与SQL查询的映射，并讨论其不可变性带来的影响。

2. @Subselect注解概述

@Subselect注解允许我们将实体映射到一个SQL查询结果，而非直接映射到数据库表。这种映射方式在特定场景下非常有用，但需要理解其工作原理和限制。

2.1. 映射到SQL查询

传统Hibernate实体映射通常使用@Entity和@Table注解，直接关联到数据库表。但@Subselect打破了这种模式：

✅ 核心特点：

实体数据来源于SQL查询结果集
查询可包含任意复杂逻辑（JOIN、GROUP BY等）
底层可能不存在对应的物理表

例如，以下SQL查询可映射为Client实体：

SELECT 
  u.id        as id,
  u.firstname as name,
  u.lastname  as lastname,
  r.name      as role
FROM users AS u
INNER JOIN roles AS r 
ON r.id = u.role_id
WHERE u.type = 'CLIENT'

⚠️ 关键区别：数据库中可能根本不存在clients表，实体数据完全来自子查询结果。

2.2. 不可变性

使用@Subselect的实体本质上是只读的：

❌ 限制：

无法执行INSERT/UPDATE操作
Hibernate不会生成写操作SQL
尝试持久化会抛出异常

✅ 原因：

Hibernate无法从查询中推断表结构
子查询结果集不可写入（违反ANSI SQL标准）

3. 使用示例

下面通过RuntimeConfiguration实体展示@Subselect的实际应用：

@Data
@Entity
@Immutable
// language=sql
@Subselect(value = """
    SELECT
      ss.id,
      ss.key,
      ss.value,
      ss.created_at
    FROM system_settings AS ss
    INNER JOIN (
      SELECT
        ss2.key as k2,
        MAX(ss2.created_at) as ca2
      FROM system_settings ss2
      GROUP BY ss2.key
    ) AS t ON t.k2 = ss.key AND t.ca2 = ss.created_at
    WHERE ss.type = 'SYSTEM' AND ss.active IS TRUE
    """)
public class RuntimeConfiguration {
    @Id
    private Long id;

    @Column(name = "key")
    private String key;

    @Column(name = "value")
    private String value;

    @Column(name = "created_at")
    private Instant createdAt;
}

✅ 关键点：

使用@Immutable显式声明不可变性
子查询获取最新生效的系统配置
支持标准JPA查询操作

查询示例：

@Test
void givenEntityMarkedWithSubselect_whenSelectingRuntimeConfigByKey_thenSelectedSuccessfully() {
    String key = "config.enabled";
    CriteriaBuilder criteriaBuilder = entityManager.getCriteriaBuilder();

    CriteriaQuery<RuntimeConfiguration> query = criteriaBuilder.createQuery(RuntimeConfiguration.class);
    var root = query.from(RuntimeConfiguration.class);

    RuntimeConfiguration configurationParameter = entityManager
      .createQuery(query.select(root).where(criteriaBuilder.equal(root.get("key"), key)))
      .getSingleResult();

    Assertions.assertThat(configurationParameter.getValue()).isEqualTo("true");
}

Hibernate生成的SQL：

select
    rc1_0.id,
    rc1_0.created_at,
    rc1_0.key,
    rc1_0.value 
from
    ( SELECT
        ss.id,
        ss.key,
        ss.value,
        ss.created_at 
    FROM
        system_settings AS ss 
    INNER JOIN
        (   SELECT
            ss2.key as k2,     MAX(ss2.created_at) as ca2   
        FROM
            system_settings ss2   
        GROUP BY
            ss2.key ) AS t 
            ON t.k2 = ss.key 
            AND t.ca2 = ss.created_at 
    WHERE
        ss.type = 'SYSTEM' 
        AND ss.active IS TRUE  ) rc1_0 
where
    rc1_0.key=?

4. 替代方案

对于类似需求，Hibernate提供其他实现方式，各有优劣：

4.1. 投影映射

DTO投影是常见替代方案：

✅ 优势：

性能更高（无持久化上下文管理）
天然不可变
适合只读场景

❌ 限制：

不支持关联映射（如@OneToMany）
每次查询需重复编写复杂SQL
无法复用查询逻辑

⚠️ 与@Subselect核心区别：

@Subselect是实体映射，支持关联关系
投影映射是DTO映射，无持久化能力

4.2. 视图映射

Hibernate支持直接映射到数据库视图：

✅ 特点：

与@Subselect功能相似
支持关联映射
视图通常只读（部分数据库例外）

❌ 差异点：

需要预先创建数据库视图
@Subselect使用内联SQL
视图维护依赖数据库

5. 总结

@Subselect注解为Hibernate提供了灵活的实体映射方式：

✅ 适用场景：

需要复用复杂查询逻辑
实体数据来自计算结果集
明确的只读需求

❌ 注意事项：

实体必须标记为@Immutable
禁止任何写操作
替代方案需根据需求选择

⚠️ 选型建议：

优先考虑@Subselect当需要复用查询逻辑时
简单只读场景可用DTO投影
已有数据库视图时直接映射

源码示例可在GitHub仓库获取。

Persistence

REST

Security