Spring Boot 3+Hibernate 6：Java枚举映射PostgreSQL枚举失败

问题背景 #

现有Java枚举AnimalType（常量为DOG/CAT/UNKNOWN）需要映射到PostgreSQL的animal枚举类型（值为dog/cat/other），迁移到Spring Boot 3+Hibernate 6后，原基于废弃EnumType的实现无法继续使用，且不想修改Java枚举常量名称以保证代码可读性。

解决方案：自定义AttributeConverter + Hibernate JdbcType配置 #

1. 实现AttributeConverter #

创建自定义转换器，复用原有枚举的getType()和fromType()方法，完成Java枚举与数据库枚举值的双向映射：

import jakarta.persistence.AttributeConverter;
import jakarta.persistence.Converter;

@Converter(autoApply = false)
public class AnimalTypeConverter implements AttributeConverter<AnimalType, String> {

    @Override
    public String convertToDatabaseColumn(AnimalType attribute) {
        return attribute == null ? null : attribute.getType();
    }

    @Override
    public AnimalType convertToEntityAttribute(String dbData) {
        return dbData == null ? null : AnimalType.fromType(dbData);
    }
}

2. 配置实体类字段 #

在实体类的animalType字段上组合使用注解，明确映射规则和数据库类型：

import org.hibernate.annotations.JdbcType;
import org.hibernate.type.descriptor.jdbc.PostgreSQLEnumJdbcType;
import jakarta.persistence.Column;
import jakarta.persistence.Convert;

// 其他实体注解
public class AnimalEntity {

    @Convert(converter = AnimalTypeConverter.class)
    @JdbcType(PostgreSQLEnumJdbcType.class)
    @Column(name = "TYPE", columnDefinition = "animal")
    private AnimalType animalType;

    // getter/setter方法
}

关键说明 #

• @Convert：指定自定义转换器，避免直接使用Java枚举的常量名（如DOG）与数据库枚举值（如dog）不匹配的问题。
• @JdbcType(PostgreSQLEnumJdbcType.class)：告诉Hibernate采用PostgreSQL专属的枚举类型处理逻辑，确保读写数据库时类型匹配，避免抛出异常。
• columnDefinition = "animal"：明确标注数据库列的枚举类型，防止Hibernate自动推断类型出错。
• 原有AnimalType枚举无需任何修改，保留DOG/CAT/UNKNOWN的常量名称，保证代码可读性。

验证效果 #

配置完成后：

• 插入数据时，AnimalType.DOG会被转换器转为dog存入数据库；
• 查询数据时，数据库返回的dog会被转回AnimalType.DOG，全程无类型不匹配异常。

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