JPA查询返回无效自定义枚举时如何通过注解自动映射为未知值

有两种常用的无侵入式方案可以实现需求，无需修改业务层代码，仅调整实体、枚举相关配置即可：

方案1：使用JPA标准自定义属性转换器（全实现兼容） #

该方案遵循JPA规范，所有JPA实现框架都支持，兼容性最强：

1. 编写自定义枚举转换器，逻辑为读取数据库值时校验合法性，非法值自动映射为UNK

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

@Converter(autoApply = false) 
// autoApply设为true时，项目中所有EnumCustom类型的字段会自动应用该转换器
public class EnumCustomConverter implements AttributeConverter<EnumCustom, String> {

    @Override
    public String convertToDatabaseColumn(EnumCustom attribute) {
        // 存入数据库的逻辑，可根据业务调整空值处理规则
        return attribute == null ? EnumCustom.UNK.name() : attribute.name();
    }

    @Override
    public EnumCustom convertToEntityAttribute(String dbData) {
        if (dbData == null) {
            return EnumCustom.UNK;
        }
        try {
            return EnumCustom.valueOf(dbData);
        } catch (IllegalArgumentException e) {
            // 匹配不到枚举值时返回未知项
            return EnumCustom.UNK;
        }
    }
}

2. 调整实体类字段配置，移除原有@Enumerated注解，添加转换器绑定：

@Entity
@Table(name = "TABLE_CUSTOM")
public class CustModel{
    @Convert(converter = EnumCustomConverter.class)
    @Column(name = "CUSTOM", length = 3, nullable = false)
    private EnumCustom enumCustom;
}

方案2：使用Hibernate内置注解（Hibernate 6+适用，更简洁） #

如果项目使用Hibernate 6.0及以上版本作为JPA实现，可以直接用Hibernate原生注解实现，无需编写转换器：

1. 调整枚举类，给默认未知项添加@EnumeratedValue注解标注为未知值映射项：

import org.hibernate.annotations.EnumeratedValue;

public enum EnumCustom{
    A, B, C, D,
    @EnumeratedValue(unknownName = true)
    UNK;
}

2. 实体类字段无需修改，保留原有@Enumerated注解即可生效，遇到数据库未定义的枚举值会自动映射到UNK。

注意事项 #

• 方案1适配所有JPA实现，适合需要兼容多框架、或者需要自定义更复杂转换逻辑的场景
• 方案2是Hibernate专属特性，代码更简洁，但仅支持Hibernate 6.0及以上版本
• 两种方案都支持自定义空值处理规则，可根据业务需求调整是否将数据库空值也映射为UNK

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