如何利用Hibernate注解校验Java枚举与PostgreSQL枚举的一致性？

核心思路 #

要实现类似@Column指定不存在列时直接抛出错误的效果，核心是在Hibernate的Session Factory初始化流程中，拦截元数据处理环节，主动校验Java枚举与对应PostgreSQL枚举的取值、顺序是否完全匹配，不匹配则终止构建并抛出异常。

具体实现步骤 #

1. 定义自定义校验注解 #

创建一个自定义注解，用来标记需要校验的Java枚举，并指定对应的PostgreSQL枚举名称：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface PGEnumValidate {
    // PostgreSQL中的枚举类型名称
    String dbEnumName();
}

2. 实现Hibernate元数据校验器 #

通过扩展Hibernate的Integrator接口，在Session Factory构建的元数据收集完成后执行枚举校验逻辑：

public class PGEnumValidationIntegrator implements Integrator {
    @Override
    public void integrate(Metadata metadata, SessionFactoryImplementor sessionFactory, SessionFactoryServiceRegistry serviceRegistry) {
        JdbcServices jdbcServices = serviceRegistry.getService(JdbcServices.class);
        Connection connection = null;
        try {
            connection = jdbcServices.getBootstrapJdbcConnectionAccess().obtainConnection();
            // 遍历所有带校验注解的Java枚举
            for (Class<?> clazz : metadata.getAnnotatedClasses()) {
                PGEnumValidate validateAnnotation = clazz.getAnnotation(PGEnumValidate.class);
                if (validateAnnotation != null && clazz.isEnum()) {
                    String dbEnumName = validateAnnotation.dbEnumName();
                    // 查询PostgreSQL枚举的取值及顺序
                    String querySql = "SELECT unnest(enum_range(CAST(NULL AS %s))) AS v".formatted(dbEnumName);
                    try (PreparedStatement stmt = connection.prepareStatement(querySql);
                         ResultSet rs = stmt.executeQuery()) {
                        List<String> dbEnumValues = new ArrayList<>();
                        while (rs.next()) {
                            dbEnumValues.add(rs.getString("v"));
                        }
                        // 获取Java枚举的取值及顺序
                        List<String> javaEnumValues = Arrays.stream(clazz.getEnumConstants())
                                .map(Enum::name)
                                .collect(Collectors.toList());
                        // 校验一致性
                        if (!javaEnumValues.equals(dbEnumValues)) {
                            throw new HibernateException(
                                    String.format("Java枚举[%s]与PostgreSQL枚举[%s]不一致，Java侧：%s，数据库侧：%s",
                                            clazz.getName(), dbEnumName, javaEnumValues, dbEnumValues)
                            );
                        }
                    }
                }
            }
        } catch (SQLException e) {
            throw new HibernateException("校验PostgreSQL枚举时数据库访问出错", e);
        } finally {
            if (connection != null) {
                try {
                    jdbcServices.getBootstrapJdbcConnectionAccess().releaseConnection(connection);
                } catch (SQLException ignored) {}
            }
        }
    }

    @Override
    public void disintegrate(SessionFactoryImplementor sessionFactory, SessionFactoryServiceRegistry serviceRegistry) {}
    @Override
    public void prepareServices(SessionFactoryServiceRegistry serviceRegistry) {}
}

3. 注册自定义Integrator #

让Hibernate加载这个校验器有两种方式：

• 配置文件方式：在hibernate.properties中添加

hibernate.integrator_provider=com.yourpackage.PGEnumValidationIntegrator

• 编程式注册：构建SessionFactory时手动添加

StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
        .applySettings(configuration.getProperties())
        .addService(Integrator.class, new PGEnumValidationIntegrator())
        .build();
SessionFactory sessionFactory = configuration.buildSessionFactory(registry);

4. 标记需要校验的Java枚举 #

在目标Java枚举类上添加自定义注解：

@PGEnumValidate(dbEnumName = "your_pg_enum_name")
public enum YourJavaEnum {
    VALUE1,
    VALUE2,
    VALUE3
}

效果说明 #

当Session Factory构建时，会自动校验所有标记了@PGEnumValidate的枚举类：

• 若Java枚举与PostgreSQL枚举的取值、顺序完全一致，Session Factory正常初始化；
• 若不一致，会直接抛出HibernateException，终止Session Factory构建，与@Column指定不存在列时的错误表现一致。

内容的提问来源于stack exchange，提问作者Andrew Lazarus