Spring Boot迁移中H2数据库枚举空值映射异常排查求助

问题场景 #

• 迁移背景：Spring Boot从1.5.19升级至2.4.5，同步升级Liquibase从3.5.5到3.10.3；H2数据库、Hibernate 5.2.4.Final版本未变更
• 触发异常：枚举字段本应读取null值，却触发Hibernate枚举映射异常，栈跟踪如下：

Caused by: java.lang.IllegalArgumentException: Unknown name value [] for enum class [***MyBusinessEnum***]
    at org.hibernate.type.EnumType$NamedEnumValueMapper.fromName(EnumType.java:433)
    at org.hibernate.type.EnumType$NamedEnumValueMapper.getValue(EnumType.java:417)
    at org.hibernate.type.EnumType.nullSafeGet(EnumType.java:231)
    at org.hibernate.type.CustomType.nullSafeGet(CustomType.java:119)
    at org.hibernate.type.AbstractType.hydrate(AbstractType.java:82)

• 排查结论：旧分支中ResultSet对应列类型为ValueNull（返回null），升级Liquibase后变为ValueLobDb且getString()返回空串而非null；锁定Liquibase 3.5.5可恢复正常，问题出现在3.5.5至3.6.2版本之间。

原因分析 #

Liquibase 3.6.x版本对数据库空值的处理逻辑发生变更：在生成或维护数据库结构时，原本应存储为null的LOB类型列被存储为空字符串。Hibernate的EnumType默认不会将空串转换为null，直接尝试将空串映射到枚举值，从而触发IllegalArgumentException。

解决方案 #

1. 自定义Hibernate枚举类型处理空串 #

重写EnumType的nullSafeGet方法，将读取到的空串转为null后再进行枚举映射：

public class NullSafeEnumType extends EnumType {
    @Override
    public Object nullSafeGet(ResultSet rs, String[] names, SharedSessionContractImplementor session, Object owner) throws HibernateException, SQLException {
        String value = rs.getString(names[0]);
        if (value == null || value.trim().isEmpty()) {
            return null;
        }
        return super.nullSafeGet(rs, names, session, owner);
    }
}

在实体类的枚举字段上指定使用该自定义类型：

@Column(name = "your_enum_column")
@Type(type = "com.your.package.NullSafeEnumType")
private MyBusinessEnum businessEnum;

2. 修正Liquibase变更集的空值处理 #

• 调整列定义：在Liquibase变更集中，确保枚举列的默认值显式设置为null，而非空串：

<addColumn tableName="your_table">
    <column name="your_enum_column" type="VARCHAR(255)" defaultValueNull="true"/>
</addColumn>

• 修复已有数据：如果数据库中已存在空串数据，添加变更集将空串转为null：

<update tableName="your_table">
    <column name="your_enum_column" valueNull="true"/>
    <where>your_enum_column = ''</where>
</update>

3. 选用Liquibase兼容版本 #

• 可以尝试升级到Liquibase 3.6.x之后的稳定版本（如3.10.x的后续小版本），验证空值处理逻辑是否已修复；或者直接升级至Liquibase 4.x系列，同时检查官方文档中是否有控制空值存储的配置项。
• 若暂时无法适配新版本，可在依赖管理中锁定Liquibase版本至3.5.5，待后续验证兼容版本后再升级。

内容的提问来源于stack exchange，提问作者Sylvain B.