本文详解 Hibernate 6.2+ 下如何替代已废弃的 @TypeDef 和自定义 EnumType，通过 @Type 配合 PostgreSQLEnumType 实现与 PostgreSQL 原生 ENUM 类型的无缝映射，并确保支持命名查询、JPQL 和 Criteria API。
本文详解 hibernate 6.2+ 下如何替代已废弃的 `@typedef` 和自定义 `enumtype`，通过 `@type` 配合 `postgresqlenumtype` 实现与 postgresql 原生 enum 类型的无缝映射，并确保支持命名查询、jpql 和 criteria api。
在 Hibernate 6 中，@TypeDef 全局类型注册机制已被移除，org.hibernate.type.EnumType 也进行了重构（不再支持直接继承重写 nullSafeSet），因此 Hibernate 5 中基于 @TypeDef + 自定义 EnumType 的枚举映射方案无法直接迁移。但 Hibernate 6 提供了更标准化、更安全的替代路径：使用 @Type 注解结合社区成熟工具库（如 Hypersistence Utils）提供的专用类型处理器。
✅ 推荐方案：Hypersistence Utils 的 PostgreSQLEnumType
该方案完全兼容 PostgreSQL 原生 ENUM 类型（而非仅字符串列），并原生支持 JPQL 命名查询、参数绑定、排序及聚合操作——这正是你强调的关键需求。
步骤一：添加依赖（Maven）
<dependency><groupid>io.hypersistence</groupid><artifactid>hypersistence-utils-hibernate-63</artifactid><!-- 注意版本后缀需匹配你的 Hibernate 主版本 --><version>3.7.4</version><!-- 请访问 https://github.com/vladmihalcea/hypersistence-utils/ 获取最新版 --></dependency>
⚠️ 注意：务必选择与你使用的 Hibernate 版本严格匹配的 Hypersistence Utils 子模块（如 hibernate-63 对应 Hibernate 6.3.x；若用 6.2.x，请选 hibernate-62）。
步骤二：实体类映射（简洁且功能完备）
import io.hypersistence.utils.hibernate.type.basic.PostgreSQLEnumType;
import jakarta.persistence.*;
import org.hibernate.annotations.Type;
@Entity
public class MyEntity {
@Id
private int id;
@Column(name = "my_enum_column") // 显式指定列名，推荐
@Enumerated(EnumType.STRING) // 告诉 JPA 按枚举名持久化（非序号）
@Type(PostgreSQLEnumType.class) // 启用 PostgreSQL 原生 ENUM 支持
private MyEnum myEnum;
// 构造函数、getter/setter 省略
}
✅ 为什么此方案满足所有要求？
- 支持命名查询（Named Queries）：PostgreSQLEnumType 在底层将 MyEnum 转换为 PostgreSQL ENUM 类型的 text OID，Hibernate 6 的 SQL 生成器能正确识别并绑定参数，JPQL 如 SELECT e FROM MyEntity e WHERE e.myEnum = :status 完全可用；
- 无需数据库方言特殊配置：自动适配 PostgreSQL10Dialect 及以上；
- 类型安全：编译期检查枚举值是否存在于数据库 CREATE TYPE 定义中（运行时抛出 PSQLException 若不匹配）；
- 零侵入：不修改原有枚举定义，也不需额外 XML 或 Java 配置。
? 数据库前提（不可省略！）
确保 PostgreSQL 中已创建对应枚举类型：
CREATE TYPE my_enum AS ENUM ('ENTRY1', 'ENTRY2');
且表结构中该列为：
ALTER TABLE my_entity ADD COLUMN my_enum_column my_enum;
? 提示：可使用 Flyway/Liquibase 管理该 DDL，保证环境一致性。
❌ 不推荐的替代方案说明
- 仅用 @Enumerated(EnumType.STRING)：虽能存取，但列类型为 VARCHAR，丢失 PostgreSQL ENUM 的约束能力（如非法值插入被拒绝）、排序语义及索引优化；
- 手动实现 UserType：Hibernate 6 的 UserType API 更复杂，且难以完美支持 JPQL 参数解析和缓存策略，易引发 QueryException；
- 使用 @JdbcTypeCode(SqlTypes.OTHER)：缺乏类型转换逻辑，无法处理 ENUM 到 String 的双向映射，命名查询会失败。
总结
Hibernate 6 的枚举映射应拥抱标准化生态：弃用自定义 EnumType，改用经过生产验证的 PostgreSQLEnumType + @Type 组合。它不仅代码更简短，更重要的是保障了 JPQL 命名查询、原生 SQL 集成、数据库约束完整性三者的统一。迁移时请严格核对 Hypersistence Utils 的 Hibernate 版本兼容性，并同步维护数据库端的 ENUM 类型定义。
