Quarkus项目枚举转字符串偶发ClassCastException异常如何解决

根因说明 #

该偶发ClassCastException的核心原因是泛型擦除+反序列化框架类型解析不稳定：

1. Java泛型为编译期校验，运行时Map<SearchableField, ?>的泛型信息会被擦除，Quarkus默认使用的Jackson反序列化框架如果没有拿到明确的类型提示，部分启动场景下会默认将Map的key反序列化为String类型，而非预期的SearchableField枚举。
2. 偶发特性是Quarkus开发模式的动态类加载机制导致：Jackson模块注册、类信息加载的顺序存在不确定性，部分启动场景能读取到字段泛型信息正常反序列化为枚举，部分场景读取不到就会生成key为String的Map，遍历取值时强转就会抛出异常，重启后加载顺序变化就可能恢复正常。

彻底解决步骤 #

步骤1：为枚举类添加显式反序列化规则 #

给SearchableField枚举类添加Jackson反序列化注解，同时做非法值校验，强制所有该类型的反序列化走统一逻辑：

import com.fasterxml.jackson.databind.annotation.JsonDeserialize;

@JsonDeserialize(using = SearchableFieldDeserializer.class)
public enum SearchableField {
    name, version;

    // 自定义反序列化器
    public static class SearchableFieldDeserializer extends com.fasterxml.jackson.databind.deser.std.StdDeserializer<SearchableField> {
        public SearchableFieldDeserializer() {
            super(SearchableField.class);
        }

        @Override
        public SearchableField deserialize(com.fasterxml.jackson.core.JsonParser p, com.fasterxml.jackson.databind.DeserializationContext ctxt) throws java.io.IOException {
            String value = p.getText().trim();
            try {
                return SearchableField.valueOf(value);
            } catch (IllegalArgumentException e) {
                throw new IllegalArgumentException("非法检索字段：" + value + "，仅支持name、version");
            }
        }
    }
}

步骤2：为Query类的Map属性补充类型提示与反射注册 #

给Query类添加@RegisterForReflection避免Quarkus类裁剪丢失字段信息，同时给三个Map字段显式指定key反序列化类型：

import io.quarkus.runtime.annotations.RegisterForReflection;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;

@RegisterForReflection
public class Query {
    @JsonDeserialize(keyAs = SearchableField.class)
    private Map<SearchableField,Object> query;
    @JsonDeserialize(keyAs = SearchableField.class)
    private Map<SearchableField, Long> field;
    @JsonDeserialize(keyAs = SearchableField.class)
    private Map<SearchableField,Long> sort;
    
    // 原有getter、setter保持不变
}

步骤3：添加运行时兼容校验（可选但推荐） #

修改Map转换逻辑，添加类型兼容判断，即使出现异常反序列化场景也能正常兼容：

Map<String,Object> query = doc.getQuery().entrySet().stream()
        .collect(Collectors.toMap(
                e -> {
                    Object key = e.getKey();
                    if (key instanceof SearchableField) {
                        return ((SearchableField) key).name();
                    } else if (key instanceof String) {
                        return SearchableField.valueOf((String) key).name();
                    }
                    throw new IllegalArgumentException("不支持的字段类型：" + key.getClass().getName());
                },
                Map.Entry::getValue
        ));

步骤4：补充Quarkus Jackson配置（生产环境必加） #

在application.properties中添加如下配置，强制枚举按name序列化/反序列化，避免类型解析异常：

# 枚举统一按name值处理
quarkus.jackson.serialization.write-enums-using-to-string=false
quarkus.jackson.deserialization.read-enums-using-to-string=false

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