JPA自定义findBy方法枚举值转换异常问题

核心问题原因 #

你在Repository方法上添加@Convert是无效的，这个注解是用来标记实体字段与数据库列之间的转换规则，并非作用于Repository的查询方法。Spring Data JPA生成查询时，会依据实体字段的映射配置处理参数，若实体字段未关联转换器，就会默认使用枚举名称（如ACTIVE）而非转换后的字符串（如Active）。

具体解决方案 #

1. 在实体字段上绑定转换器 #

找到实体类中Status类型的字段，给它添加@Convert注解指定转换器：

@Entity
public class Entity {
    // 其他字段...
    
    @Convert(converter = StatusConverter.class)
    private Status status;
    
    // getter、setter...
}

如果希望所有Status类型的字段都自动应用该转换器，可以给转换器类本身加上@Converter(autoApply = true)注解，无需在每个实体字段重复配置：

@Converter(autoApply = true)
public class StatusConverter implements AttributeConverter<Status, String> {
    @Override
    public String convertToDatabaseColumn(Status status) {
        return status != null ? status.getStatus() : null;
    }

    @Override
    public Status convertToEntityAttribute(String dbData) {
        if (dbData == null) {
            return null;
        }
        return Arrays.stream(Status.values())
                .filter(s -> s.getStatus().equals(dbData))
                .findFirst()
                .orElseThrow(() -> new IllegalArgumentException("无效状态值: " + dbData));
    }
}

2. 验证转换器逻辑 #

确保转换器的两个核心方法逻辑正确：

• convertToDatabaseColumn：将枚举实例转换为数据库存储的目标字符串（如Status.ACTIVE转"Active"）
• convertToEntityAttribute：将数据库中的字符串转回对应的枚举实例（如"Inactive"转Status.INACTIVE）

3. 若自动查询仍异常，手动编写查询 #

如果自动生成的查询不符合预期，直接用@Query注解编写JPQL查询，Spring Data JPA会自动利用实体字段的转换器处理参数：

@Repository
public interface EntityRepository extends JpaRepository<Entity, Long> {
    @Query("SELECT e FROM Entity e WHERE e.status = :status")
    List<Entity> findByStatus(@Param("status") Status status);
}

也可以使用原生SQL查询（需传入转换后的字符串值）：

@Query(value = "SELECT * FROM entity_table WHERE status = :statusStr", nativeQuery = true)
List<Entity> findByStatus(@Param("statusStr") String statusStr);

// 调用示例：repository.findByStatus(Status.INACTIVE.getStatus());

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