如何为含Enum列的JPA实体编写Search Specification并解决枚举匹配错误

你遇到的报错本质是枚举值转换失败，和JPA的枚举映射配置无关：

OnboardingTaskStatus.2769df0841; nested exception is java.lang.IllegalArgumentException: No enum constant OnboardingTaskStatus.2769df0841
报错信息里的随机字符串2769df0841说明你传入cb.equal方法的params.getStatus()要么是格式非法的字符串，要么是没有正确反序列化为OnboardingTaskStatus枚举实例，JPA Criteria API尝试将传入的值转换为对应枚举时找不到匹配的常量，才抛出异常。

先排查参数类型，对应修复即可：

1. 如果params类中的status字段定义为String类型：需要先手动转换为枚举实例再传入查询条件：

if (params.getStatus() != null) {
    // 注意统一大小写，避免前端传小写导致匹配失败
    OnboardingTaskStatus statusEnum = OnboardingTaskStatus.valueOf(params.getStatus().toUpperCase());
    predicates.add(cb.equal(root.get("status"), statusEnum));
}

2. 如果params类中的status字段已经定义为OnboardingTaskStatus枚举类型：排查接口参数反序列化逻辑，确认前端传入的status值为NEW/IN_PROGRESS/DISABLED三者之一，没有拼写错误、大小写不匹配的问题。

你当前使用的@Enumerated(EnumType.STRING)已经完全满足“存储枚举常量名”的需求，不需要额外引入@Convert转换器。
只有当你需要自定义枚举存储规则（比如存枚举的自定义编码值、而非枚举名，例如NEW存1、IN_PROGRESS存2）的时候，才需要通过@Convert实现自定义枚举转换器。

• 参数校验前置：在Controller层接收参数时就做枚举合法性校验，非法值直接返回参数错误，不需要到DAO层才抛出异常。如果是Spring Boot项目，可以配置spring.jackson.deserialization.read-unknown-enum-values-as-null=true，或者给枚举加@JsonEnumDefaultValue注解，自动将未知枚举值转为null或默认值。
• 枚举匹配兼容：如果需要兼容前端传小写、驼峰格式的枚举值，可以给枚举字段加@JsonProperty注解指定别名，无需修改JPA映射逻辑。
• 多状态查询支持：如果后续需要支持一次查多个状态，可直接使用in查询：

predicates.add(root.get("status").in(Arrays.asList(OnboardingTaskStatus.NEW, OnboardingTaskStatus.IN_PROGRESS)));

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